@hivelore/core 0.30.0

package/dist/index.d.ts

@@ -0,0 +1,2752 @@
+import { z } from 'zod';
+
+declare const MemoryScopeSchema: z.ZodEnum<["personal", "team", "module", "shared"]>;
+declare const MemoryStatusSchema: z.ZodEnum<["draft", "proposed", "validated", "deprecated", "stale", "rejected"]>;
+declare const MemoryTypeSchema: z.ZodEnum<["convention", "decision", "gotcha", "architecture", "glossary", "skill", "attempt", "session_recap"]>;
+declare const AnchorSchema: z.ZodObject<{
+    commit: z.ZodOptional<z.ZodString>;
+    paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    symbols: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    paths: string[];
+    symbols: string[];
+    commit?: string | undefined;
+}, {
+    commit?: string | undefined;
+    paths?: string[] | undefined;
+    symbols?: string[] | undefined;
+}>;
+/**
+ * An executable check derived from a memory — the "feedback computational" layer.
+ *
+ * A `gotcha`/`attempt` is normally feedforward (text the agent reads). A sensor turns
+ * that lesson into a deterministic check: when a touched file matches `pattern`, the
+ * memory's warning fires regardless of semantic ranking. This closes the harness loop —
+ * a documented mistake becomes a permanent guardrail.
+ *
+ * Phase 1 implements `kind: "regex"` only. `shell`/`test` are reserved for a later phase
+ * (they require I/O and must run from the CLI, not core).
+ */
+declare const SensorSchema: z.ZodObject<{
+    kind: z.ZodDefault<z.ZodEnum<["regex", "shell", "test"]>>;
+    /** Regex source (for kind=regex), matched against added diff lines / file content. */
+    pattern: z.ZodOptional<z.ZodString>;
+    /**
+     * Optional "correct-usage" regex (kind=regex). When `pattern` (the risky call) matches but this
+     * regex ALSO appears within a small window around the match, the catch is SUPPRESSED — the diff
+     * already includes the required companion. Encodes "X without Y": `pattern`=X (e.g. the API call),
+     * `absent`=Y (e.g. the required option). This is what lets an autogenerated sensor discriminate the
+     * faulty usage from the correct one instead of firing on every call — and makes it safe to promote.
+     */
+    absent: z.ZodOptional<z.ZodString>;
+    /** Regex flags (e.g. "i", "m"). Ignored for non-regex kinds. */
+    flags: z.ZodOptional<z.ZodString>;
+    /** Shell/test command to run (for kind=shell|test). Executed by the CLI, never by core. */
+    command: z.ZodOptional<z.ZodString>;
+    /** Glob-ish path prefixes the sensor applies to. Falls back to the memory's anchor paths when empty. */
+    paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** LLM-facing self-correction message: what was done wrong and what to do instead. */
+    message: z.ZodString;
+    /** `warn` surfaces in review; `block` can hard-block the commit (only when the gate opts in). */
+    severity: z.ZodDefault<z.ZodEnum<["warn", "block"]>>;
+    /** True when Hivelore generated this sensor automatically (vs. hand-authored). */
+    autogen: z.ZodDefault<z.ZodBoolean>;
+    /** ISO timestamp of the last time this sensor matched a diff. */
+    last_fired: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    message: string;
+    paths: string[];
+    kind: "regex" | "shell" | "test";
+    severity: "warn" | "block";
+    autogen: boolean;
+    last_fired: string | null;
+    pattern?: string | undefined;
+    absent?: string | undefined;
+    flags?: string | undefined;
+    command?: string | undefined;
+}, {
+    message: string;
+    paths?: string[] | undefined;
+    kind?: "regex" | "shell" | "test" | undefined;
+    pattern?: string | undefined;
+    absent?: string | undefined;
+    flags?: string | undefined;
+    command?: string | undefined;
+    severity?: "warn" | "block" | undefined;
+    autogen?: boolean | undefined;
+    last_fired?: string | null | undefined;
+}>;
+/**
+ * Progressive-disclosure activation triggers for a `skill` memory.
+ *
+ * A skill is a reusable playbook (feedforward harness guide). Injecting every skill
+ * on every briefing bloats the context and dilutes signal (the "instruction budget"
+ * problem). An `activation` block makes a skill surface ONLY when it is relevant:
+ * its keywords match the task, or its globs match the files being edited. A skill
+ * that defines `activation` and matches none of it is suppressed from the briefing;
+ * a skill with no `activation` block keeps the legacy always-eligible behavior.
+ */
+declare const ActivationSchema: z.ZodObject<{
+    /** Case-insensitive substrings matched against the task text. */
+    keywords: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Glob-ish path patterns matched against the files being edited. */
+    globs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Always activate (rare — for truly universal playbooks). */
+    always: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    keywords: string[];
+    globs: string[];
+    always: boolean;
+}, {
+    keywords?: string[] | undefined;
+    globs?: string[] | undefined;
+    always?: boolean | undefined;
+}>;
+declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
+    id: z.ZodString;
+    scope: z.ZodDefault<z.ZodEnum<["personal", "team", "module", "shared"]>>;
+    module: z.ZodOptional<z.ZodString>;
+    type: z.ZodEnum<["convention", "decision", "gotcha", "architecture", "glossary", "skill", "attempt", "session_recap"]>;
+    status: z.ZodDefault<z.ZodEnum<["draft", "proposed", "validated", "deprecated", "stale", "rejected"]>>;
+    anchor: z.ZodDefault<z.ZodObject<{
+        commit: z.ZodOptional<z.ZodString>;
+        paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        symbols: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        paths: string[];
+        symbols: string[];
+        commit?: string | undefined;
+    }, {
+        commit?: string | undefined;
+        paths?: string[] | undefined;
+        symbols?: string[] | undefined;
+    }>>;
+    /** Optional executable check derived from this memory (feedback computational layer). */
+    sensor: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodDefault<z.ZodEnum<["regex", "shell", "test"]>>;
+        /** Regex source (for kind=regex), matched against added diff lines / file content. */
+        pattern: z.ZodOptional<z.ZodString>;
+        /**
+         * Optional "correct-usage" regex (kind=regex). When `pattern` (the risky call) matches but this
+         * regex ALSO appears within a small window around the match, the catch is SUPPRESSED — the diff
+         * already includes the required companion. Encodes "X without Y": `pattern`=X (e.g. the API call),
+         * `absent`=Y (e.g. the required option). This is what lets an autogenerated sensor discriminate the
+         * faulty usage from the correct one instead of firing on every call — and makes it safe to promote.
+         */
+        absent: z.ZodOptional<z.ZodString>;
+        /** Regex flags (e.g. "i", "m"). Ignored for non-regex kinds. */
+        flags: z.ZodOptional<z.ZodString>;
+        /** Shell/test command to run (for kind=shell|test). Executed by the CLI, never by core. */
+        command: z.ZodOptional<z.ZodString>;
+        /** Glob-ish path prefixes the sensor applies to. Falls back to the memory's anchor paths when empty. */
+        paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /** LLM-facing self-correction message: what was done wrong and what to do instead. */
+        message: z.ZodString;
+        /** `warn` surfaces in review; `block` can hard-block the commit (only when the gate opts in). */
+        severity: z.ZodDefault<z.ZodEnum<["warn", "block"]>>;
+        /** True when Hivelore generated this sensor automatically (vs. hand-authored). */
+        autogen: z.ZodDefault<z.ZodBoolean>;
+        /** ISO timestamp of the last time this sensor matched a diff. */
+        last_fired: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+        paths: string[];
+        kind: "regex" | "shell" | "test";
+        severity: "warn" | "block";
+        autogen: boolean;
+        last_fired: string | null;
+        pattern?: string | undefined;
+        absent?: string | undefined;
+        flags?: string | undefined;
+        command?: string | undefined;
+    }, {
+        message: string;
+        paths?: string[] | undefined;
+        kind?: "regex" | "shell" | "test" | undefined;
+        pattern?: string | undefined;
+        absent?: string | undefined;
+        flags?: string | undefined;
+        command?: string | undefined;
+        severity?: "warn" | "block" | undefined;
+        autogen?: boolean | undefined;
+        last_fired?: string | null | undefined;
+    }>>;
+    /** Optional progressive-disclosure triggers — only meaningful for `type: skill`. */
+    activation: z.ZodOptional<z.ZodObject<{
+        /** Case-insensitive substrings matched against the task text. */
+        keywords: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /** Glob-ish path patterns matched against the files being edited. */
+        globs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /** Always activate (rare — for truly universal playbooks). */
+        always: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        keywords: string[];
+        globs: string[];
+        always: boolean;
+    }, {
+        keywords?: string[] | undefined;
+        globs?: string[] | undefined;
+        always?: boolean | undefined;
+    }>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    domain: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodString>;
+    created_at: z.ZodPipeline<z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodDate]>, string, string | Date>, z.ZodString>;
+    expires_when: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    verified_at: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    stale_reason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    related_ids: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    last_read_at: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    topic: z.ZodOptional<z.ZodString>;
+    revision_count: z.ZodDefault<z.ZodNumber>;
+    /**
+     * When true, the AI MUST NOT act on this memory autonomously.
+     * It must surface the information to the human developer and wait
+     * for explicit confirmation before modifying any code.
+     * Used for cross-repo breaking changes, dependency bumps, contract diffs.
+     */
+    requires_human_approval: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Provenance of the memory's `validated` status — who/what last trusted it:
+     *   "human"  — a person explicitly approved it (CLI `memory approve`)
+     *   "agent"  — an AI agent explicitly approved it (MCP `mem_approve`)
+     *   "auto"   — an automatic rule trusted it without review (auto-promotion by read
+     *              count/time, or `defaultStatus: validated` on creation)
+     * null when the memory is not yet validated, or on legacy memories written before this field.
+     * Lets a human distinguish reviewed knowledge from AI/auto-trusted knowledge.
+     */
+    validated_by: z.ZodDefault<z.ZodNullable<z.ZodEnum<["human", "agent", "auto"]>>>;
+}, "strip", z.ZodTypeAny, {
+    type: "convention" | "decision" | "gotcha" | "architecture" | "glossary" | "skill" | "attempt" | "session_recap";
+    status: "draft" | "proposed" | "validated" | "deprecated" | "stale" | "rejected";
+    id: string;
+    scope: "personal" | "team" | "module" | "shared";
+    anchor: {
+        paths: string[];
+        symbols: string[];
+        commit?: string | undefined;
+    };
+    tags: string[];
+    created_at: string;
+    expires_when: string | null;
+    verified_at: string | null;
+    stale_reason: string | null;
+    related_ids: string[];
+    last_read_at: string | null;
+    revision_count: number;
+    requires_human_approval: boolean;
+    validated_by: "human" | "agent" | "auto" | null;
+    module?: string | undefined;
+    sensor?: {
+        message: string;
+        paths: string[];
+        kind: "regex" | "shell" | "test";
+        severity: "warn" | "block";
+        autogen: boolean;
+        last_fired: string | null;
+        pattern?: string | undefined;
+        absent?: string | undefined;
+        flags?: string | undefined;
+        command?: string | undefined;
+    } | undefined;
+    activation?: {
+        keywords: string[];
+        globs: string[];
+        always: boolean;
+    } | undefined;
+    domain?: string | undefined;
+    author?: string | undefined;
+    topic?: string | undefined;
+}, {
+    type: "convention" | "decision" | "gotcha" | "architecture" | "glossary" | "skill" | "attempt" | "session_recap";
+    id: string;
+    created_at: string | Date;
+    module?: string | undefined;
+    status?: "draft" | "proposed" | "validated" | "deprecated" | "stale" | "rejected" | undefined;
+    scope?: "personal" | "team" | "module" | "shared" | undefined;
+    anchor?: {
+        commit?: string | undefined;
+        paths?: string[] | undefined;
+        symbols?: string[] | undefined;
+    } | undefined;
+    sensor?: {
+        message: string;
+        paths?: string[] | undefined;
+        kind?: "regex" | "shell" | "test" | undefined;
+        pattern?: string | undefined;
+        absent?: string | undefined;
+        flags?: string | undefined;
+        command?: string | undefined;
+        severity?: "warn" | "block" | undefined;
+        autogen?: boolean | undefined;
+        last_fired?: string | null | undefined;
+    } | undefined;
+    activation?: {
+        keywords?: string[] | undefined;
+        globs?: string[] | undefined;
+        always?: boolean | undefined;
+    } | undefined;
+    tags?: string[] | undefined;
+    domain?: string | undefined;
+    author?: string | undefined;
+    expires_when?: string | null | undefined;
+    verified_at?: string | null | undefined;
+    stale_reason?: string | null | undefined;
+    related_ids?: string[] | undefined;
+    last_read_at?: string | null | undefined;
+    topic?: string | undefined;
+    revision_count?: number | undefined;
+    requires_human_approval?: boolean | undefined;
+    validated_by?: "human" | "agent" | "auto" | null | undefined;
+}>, {
+    type: "convention" | "decision" | "gotcha" | "architecture" | "glossary" | "skill" | "attempt" | "session_recap";
+    status: "draft" | "proposed" | "validated" | "deprecated" | "stale" | "rejected";
+    id: string;
+    scope: "personal" | "team" | "module" | "shared";
+    anchor: {
+        paths: string[];
+        symbols: string[];
+        commit?: string | undefined;
+    };
+    tags: string[];
+    created_at: string;
+    expires_when: string | null;
+    verified_at: string | null;
+    stale_reason: string | null;
+    related_ids: string[];
+    last_read_at: string | null;
+    revision_count: number;
+    requires_human_approval: boolean;
+    validated_by: "human" | "agent" | "auto" | null;
+    module?: string | undefined;
+    sensor?: {
+        message: string;
+        paths: string[];
+        kind: "regex" | "shell" | "test";
+        severity: "warn" | "block";
+        autogen: boolean;
+        last_fired: string | null;
+        pattern?: string | undefined;
+        absent?: string | undefined;
+        flags?: string | undefined;
+        command?: string | undefined;
+    } | undefined;
+    activation?: {
+        keywords: string[];
+        globs: string[];
+        always: boolean;
+    } | undefined;
+    domain?: string | undefined;
+    author?: string | undefined;
+    topic?: string | undefined;
+}, {
+    type: "convention" | "decision" | "gotcha" | "architecture" | "glossary" | "skill" | "attempt" | "session_recap";
+    id: string;
+    created_at: string | Date;
+    module?: string | undefined;
+    status?: "draft" | "proposed" | "validated" | "deprecated" | "stale" | "rejected" | undefined;
+    scope?: "personal" | "team" | "module" | "shared" | undefined;
+    anchor?: {
+        commit?: string | undefined;
+        paths?: string[] | undefined;
+        symbols?: string[] | undefined;
+    } | undefined;
+    sensor?: {
+        message: string;
+        paths?: string[] | undefined;
+        kind?: "regex" | "shell" | "test" | undefined;
+        pattern?: string | undefined;
+        absent?: string | undefined;
+        flags?: string | undefined;
+        command?: string | undefined;
+        severity?: "warn" | "block" | undefined;
+        autogen?: boolean | undefined;
+        last_fired?: string | null | undefined;
+    } | undefined;
+    activation?: {
+        keywords?: string[] | undefined;
+        globs?: string[] | undefined;
+        always?: boolean | undefined;
+    } | undefined;
+    tags?: string[] | undefined;
+    domain?: string | undefined;
+    author?: string | undefined;
+    expires_when?: string | null | undefined;
+    verified_at?: string | null | undefined;
+    stale_reason?: string | null | undefined;
+    related_ids?: string[] | undefined;
+    last_read_at?: string | null | undefined;
+    topic?: string | undefined;
+    revision_count?: number | undefined;
+    requires_human_approval?: boolean | undefined;
+    validated_by?: "human" | "agent" | "auto" | null | undefined;
+}>;
+declare const CrossRepoProvenanceSchema: z.ZodOptional<z.ZodObject<{
+    source_name: z.ZodString;
+    source_path: z.ZodString;
+    source_id: z.ZodString;
+    imported_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    source_name: string;
+    source_path: string;
+    source_id: string;
+    imported_at: string;
+}, {
+    source_name: string;
+    source_path: string;
+    source_id: string;
+    imported_at: string;
+}>>;
+
+type MemoryScope = z.infer<typeof MemoryScopeSchema>;
+type MemoryStatus = z.infer<typeof MemoryStatusSchema>;
+type MemoryType = z.infer<typeof MemoryTypeSchema>;
+type Anchor = z.infer<typeof AnchorSchema>;
+type Sensor = z.infer<typeof SensorSchema>;
+type Activation = z.infer<typeof ActivationSchema>;
+type MemoryFrontmatter = z.infer<typeof MemoryFrontmatterSchema>;
+interface Memory {
+    frontmatter: MemoryFrontmatter;
+    body: string;
+}
+
+declare function stripPrivate(body: string): string;
+declare function parseMemory(raw: string): Memory;
+declare function serializeMemory(memory: Memory): string;
+declare function newMemoryId(type: string, slug: string, date?: Date): string;
+declare function buildFrontmatter(input: {
+    type: MemoryFrontmatter["type"];
+    slug: string;
+    scope?: MemoryFrontmatter["scope"];
+    module?: string;
+    tags?: string[];
+    domain?: string;
+    author?: string;
+    paths?: string[];
+    symbols?: string[];
+    commit?: string;
+    topic?: string;
+    status?: MemoryFrontmatter["status"];
+    relatedIds?: string[];
+    sensor?: Sensor;
+    activation?: Activation;
+}): MemoryFrontmatter;
+
+declare const HAIVE_DIR = ".ai";
+declare function findProjectRoot(startDir?: string): string;
+declare const PROJECT_CONTEXT_FILE = "project-context.md";
+declare const MEMORIES_DIR = "memories";
+interface HaivePaths {
+    root: string;
+    haiveDir: string;
+    /** Disposable local layer (session journal, caches). Not team truth — see `.ai/.runtime/` layout. */
+    runtimeDir: string;
+    projectContext: string;
+    memoriesDir: string;
+    personalDir: string;
+    teamDir: string;
+    sharedDir: string;
+    moduleDir: string;
+    modulesContextDir: string;
+}
+declare function resolveHaivePaths(projectRoot: string): HaivePaths;
+declare function memoryFilePath(paths: HaivePaths, scope: "personal" | "team" | "module" | "shared", id: string, module?: string): string;
+
+interface LoadedMemory {
+    memory: Memory;
+    filePath: string;
+}
+declare function listMarkdownFilesRecursive(dir: string): Promise<string[]>;
+declare function loadMemory(filePath: string): Promise<LoadedMemory>;
+declare function loadMemoriesFromDir(dir: string): Promise<LoadedMemory[]>;
+
+declare function tokenizeQuery(query: string): string[];
+declare function literalMatchesAllTokens(memory: Memory, tokens: string[]): boolean;
+/**
+ * OR-based fallback: returns true if the memory matches at least one token.
+ * Used when all-tokens (AND) search returns 0 results.
+ */
+declare function literalMatchesAnyToken(memory: Memory, tokens: string[]): boolean;
+declare function pickSnippetNeedle(query: string): string;
+declare function extractSnippet(body: string, needle: string, radius?: number): string;
+
+interface VerifyResult {
+    stale: boolean;
+    reason: string | null;
+    checkedPaths: string[];
+    checkedSymbols: string[];
+    possibleRenames: string[];
+}
+interface VerifyOptions {
+    /** Project root used to resolve relative anchor paths. */
+    projectRoot: string;
+}
+/**
+ * Verify that a memory's anchor still matches the current code.
+ * - Every anchor.paths entry must exist on disk
+ * - Every anchor.symbols entry must appear at least once across the anchor.paths
+ *   files (or any tracked file if no paths are recorded)
+ *
+ * Anchorless memories (no paths and no symbols) are always considered fresh —
+ * staleness only applies to memories that opted into anchoring.
+ */
+declare function verifyAnchor(memory: Memory, options: VerifyOptions): Promise<VerifyResult>;
+
+interface MemoryUsage {
+    read_count: number;
+    last_read_at: string | null;
+    rejected_count: number;
+    last_rejected_at: string | null;
+    rejection_reason: string | null;
+    /**
+     * Number of times the memory was explicitly confirmed *useful* — i.e. an agent
+     * or human recorded that it changed what they did (the closed-loop "applied"
+     * outcome, recorded via `mem_feedback`). A far stronger utility signal than a
+     * read: a memory can be surfaced many times and ignored, but `applied` means it
+     * demonstrably steered work. Drives impact scoring in {@link ./impact.js}.
+     */
+    applied_count: number;
+    last_applied_at: string | null;
+    /**
+     * Number of *prevention* events — times this memory's sensor actually fired on a scanned diff,
+     * intercepting a known mistake before it landed. This is an OUTCOME signal (defect prevented),
+     * the closest proxy Hivelore has to "did the knowledge stop a real problem?", distinct from
+     * retrieval (read) and self-reported usefulness (applied). Recorded by `hivelore sensors check`.
+     */
+    prevented_count: number;
+    last_prevented_at: string | null;
+}
+interface UsageIndex {
+    version: 1;
+    updated_at: string;
+    by_id: Record<string, MemoryUsage>;
+}
+declare const USAGE_FILE = "usage.json";
+declare function emptyUsage(): MemoryUsage;
+declare function emptyUsageIndex(): UsageIndex;
+declare function usagePath(paths: HaivePaths): string;
+declare function loadUsageIndex(paths: HaivePaths): Promise<UsageIndex>;
+declare function saveUsageIndex(paths: HaivePaths, index: UsageIndex): Promise<void>;
+declare function getUsage(index: UsageIndex, id: string): MemoryUsage;
+declare function bumpRead(index: UsageIndex, ids: string[]): UsageIndex;
+declare function recordRejection(index: UsageIndex, id: string, reason: string | null): UsageIndex;
+/**
+ * Record that a memory was *applied* — explicitly confirmed to have changed what
+ * the agent/human did. This is the closed-loop utility signal that distinguishes
+ * a memory that merely got surfaced from one that demonstrably steered work.
+ */
+declare function recordApplied(index: UsageIndex, id: string): UsageIndex;
+/** Debounce window so re-scanning the same diff within a few minutes doesn't inflate prevention
+ *  counts (a pre-commit hook can run the check several times for one commit). */
+declare const PREVENTION_DEBOUNCE_MS: number;
+/**
+ * Record a *prevention* event: a memory's sensor fired on a scanned diff, intercepting a known
+ * mistake before it landed. Outcome signal (defect prevented), stronger than a read. Debounced by
+ * {@link PREVENTION_DEBOUNCE_MS}. Returns true if a NEW event was recorded (false if debounced).
+ */
+declare function recordPrevention(index: UsageIndex, id: string, now?: number): boolean;
+declare const DECAY_DAYS = 90;
+declare function isDecaying(usage: MemoryUsage, createdAt: string): boolean;
+declare function trackReads(paths: HaivePaths, ids: string[]): Promise<UsageIndex>;
+
+/**
+ * Closed-loop memory-utility scoring — the "did this memory actually help?" layer.
+ *
+ * Hivelore already tracks reads ({@link ./usage.js}) and derives a trust level from
+ * status + read_count ({@link ./confidence.js}). But a read only means a memory was
+ * *surfaced*, not that it *helped* — a memory can be injected on every briefing and
+ * silently ignored. Harness engineering's core loop (Fowler / LangChain) is to
+ * measure what demonstrably steers work and let that feed back into recall.
+ *
+ * `computeImpact` combines the signals Hivelore already records but never correlated:
+ *   POSITIVE  reads · applied outcomes (mem_feedback) · a sensor that actually fired
+ *   NEGATIVE  rejections · stale/deprecated/rejected status · dormancy
+ * into a single 0..1 utility score, a tier, and a prune-candidate flag. It is a pure
+ * function (no I/O), unit-tested in `packages/core/test/impact.test.ts`.
+ */
+type ImpactTier = "high" | "medium" | "low" | "dormant";
+interface ImpactScore {
+    /** Normalized utility score in [0, 1]. */
+    score: number;
+    tier: ImpactTier;
+    /** Human-readable breakdown of the signals that produced the score. */
+    signals: string[];
+    /**
+     * True when the memory looks like dead weight worth reviewing/pruning:
+     * more rejections than reads, or never used with no guardrail, or already
+     * stale/deprecated/rejected. A memory carrying a `sensor` or with `applied`
+     * outcomes is never a prune candidate — it earns its keep as a guardrail.
+     */
+    pruneCandidate: boolean;
+}
+interface ImpactOptions {
+    /** Days with no read AND no applied outcome after which a memory is "dormant". */
+    dormantDays?: number;
+    now?: Date;
+}
+/** Default dormancy window — half the confidence hard-decay (365d), so impact reacts sooner. */
+declare const DEFAULT_DORMANT_DAYS = 120;
+/**
+ * Compute the demonstrated utility of a single memory from its frontmatter + usage.
+ * Pure and deterministic given `now`.
+ */
+declare function computeImpact(fm: MemoryFrontmatter, usage: MemoryUsage, options?: ImpactOptions): ImpactScore;
+/** Sort comparator: highest impact first, prune candidates last on ties. */
+declare function compareImpact(a: ImpactScore, b: ImpactScore): number;
+interface ImpactSummary {
+    total: number;
+    high: number;
+    medium: number;
+    low: number;
+    dormant: number;
+    prune_candidates: number;
+}
+/** Roll up a set of impact scores into tier counts. */
+declare function summarizeImpact(scores: ImpactScore[]): ImpactSummary;
+type FeedbackAdjustmentAction = "none" | "downgrade-block-sensor" | "deprecate-memory";
+interface FeedbackAdjustment {
+    action: FeedbackAdjustmentAction;
+    reason: string;
+}
+interface FeedbackAdjustmentOptions {
+    /** Rejections needed before deprecating a memory with no positive outcomes. Defaults to 2. */
+    rejectionThreshold?: number;
+}
+/**
+ * Turn explicit human rejection (`mem_feedback outcome=rejected`) into a deterministic
+ * noise-reduction action. Pure: callers decide whether to persist the returned change.
+ */
+declare function recommendFeedbackAdjustment(fm: MemoryFrontmatter, usage: MemoryUsage, options?: FeedbackAdjustmentOptions): FeedbackAdjustment;
+declare function applyFeedbackAdjustment(fm: MemoryFrontmatter, adjustment: FeedbackAdjustment, now?: Date): MemoryFrontmatter;
+
+type PreventionSource = "sensor" | "anti-pattern";
+interface PreventionEvent {
+    /** ISO timestamp of the catch. */
+    at: string;
+    /** Memory id whose lesson fired. */
+    id: string;
+    /** Which gate path recorded it. */
+    source: PreventionSource;
+}
+declare function preventionLogPath(paths: HaivePaths): string;
+/** Append one catch to the log. Best-effort, creates the dir on demand. */
+declare function appendPreventionEvent(paths: HaivePaths, event: PreventionEvent): Promise<void>;
+/**
+ * THE single recorder for "a documented lesson intercepted a real mistake". Every gate path —
+ * the installed git-hook gate (`enforce check`), the standalone `hivelore sensors check`, and the
+ * `anti_patterns_check` MCP tool — funnels its fired memory ids through here so prevention is
+ * recorded once and identically, not bolted onto each entry point (it used to leak: the git-hook
+ * gate blocked but never recorded — see the harness-positioning gotcha).
+ *
+ * Bumps `prevented_count` in usage.json (debounced per memory via {@link recordPrevention}) AND
+ * appends one timestamped event per NEW catch to the prevention log. Best-effort: a telemetry
+ * write must never break a commit, so failures are swallowed. Returns the ids actually recorded
+ * (i.e. not debounced), so callers can report "caught for you" without re-counting.
+ */
+declare function recordPreventionHits(paths: HaivePaths, firedIds: string[], source: PreventionSource, now?: Date): Promise<string[]>;
+/** Read all catch events (skips malformed lines). */
+declare function loadPreventionEvents(paths: HaivePaths): Promise<PreventionEvent[]>;
+interface PreventionTrend {
+    /** Catches in the last 7 days. */
+    last_7d: number;
+    /** Catches in the last 30 days. */
+    last_30d: number;
+    /** Catch counts per ISO week, oldest → newest, for the last N weeks (default 6). */
+    weekly: number[];
+}
+declare function computePreventionTrend(events: PreventionEvent[], now?: Date, weeks?: number): PreventionTrend;
+interface RecurrenceRow {
+    id: string;
+    /** Total catches for this memory. */
+    catches: number;
+    /** Number of distinct UTC days the lesson fired — the recurrence signal. */
+    distinct_days: number;
+    last_at: string;
+}
+interface RecurrenceReport {
+    /**
+     * Memories whose lesson was caught on >= 2 distinct days — i.e. the mistake was RE-INTRODUCED
+     * after it had already been captured and caught once. A high count means a recurring problem the
+     * team keeps reintroducing (the guardrail is earning its keep, and the root cause may need a
+     * stronger fix than a memory).
+     */
+    recurring_count: number;
+    top: RecurrenceRow[];
+}
+declare function computeRecurrence(events: PreventionEvent[]): RecurrenceReport;
+interface BriefingProofLineOptions {
+    /** End of the reporting window. Defaults to now. */
+    now?: Date;
+    /** Window size in days. Defaults to 30 ("this month" in product copy). */
+    days?: number;
+}
+/**
+ * Coordination point for Lot C: turn prevention events into one compact proof line
+ * suitable for get_briefing, without coupling this lot to the MCP tool.
+ */
+declare function briefingProofLine(events: PreventionEvent[], options?: BriefingProofLineOptions): string | null;
+interface CaughtForYouOptions {
+    /** Only include events at or after this instant. */
+    since?: string | Date;
+    /** Only include events at or before this instant. Defaults to now. */
+    now?: Date;
+    /** Max rows in the summary. Defaults to 5. */
+    limit?: number;
+}
+interface CaughtForYouRow {
+    id: string;
+    title: string;
+    source: PreventionSource;
+    catches: number;
+    previous_count: number;
+    current_count: number;
+    last_at: string;
+}
+interface CaughtForYouSummary {
+    total_catches: number;
+    since: string | null;
+    until: string;
+    rows: CaughtForYouRow[];
+}
+/** Build the end-of-session "caught for you" scene from prevention events. Pure. */
+declare function summarizeCaughtForYou(events: PreventionEvent[], memories: LoadedMemory[], usage: UsageIndex, options?: CaughtForYouOptions): CaughtForYouSummary;
+/** Render a compact human-readable block for CLI/session recaps. */
+declare function renderCaughtForYou(summary: CaughtForYouSummary): string | null;
+
+/** How long an emitted project context is considered "still fresh in the agent's context". */
+declare const PROJECT_CONTEXT_THROTTLE_MS: number;
+declare function hashProjectContext(content: string): string;
+/** True if an identical project-context body was already emitted within the throttle window. */
+declare function projectContextRecentlyEmitted(paths: HaivePaths, hash: string, now?: number): Promise<boolean>;
+/** Record that this exact project-context body was just emitted. Best-effort. */
+declare function recordProjectContextEmission(paths: HaivePaths, hash: string, now?: number): Promise<void>;
+
+/**
+ * A rigorous, model-free, repeatable evaluation of Hivelore's core promise: surfacing
+ * the right knowledge and guardrails at the right moment. Unlike the agent benchmark
+ * (which parses human-written reports), this is deterministic and CI-runnable — it
+ * produces a numeric quality score from labeled cases, so a regression in ranking or
+ * sensor coverage fails the build instead of silently degrading every agent session.
+ *
+ * Two case families:
+ *   - RETRIEVAL — given a task (+optional files/symbols), do the expected memories
+ *     surface in the briefing top-k? Measured by recall and mean reciprocal rank.
+ *   - SENSORS — given a known-bad diff, does the expected memory's sensor fire?
+ *     Measured by catch-rate.
+ *
+ * This module is pure: it defines the case/result types, the scoring math, and case
+ * synthesis from a repo's own anchored memories. Orchestration (calling get_briefing
+ * / anti_patterns_check) lives in the CLI, since core cannot depend on the MCP layer.
+ */
+interface RetrievalCase {
+    name: string;
+    task: string;
+    files?: string[];
+    symbols?: string[];
+    /** Memory ids that SHOULD surface in the briefing for this case. */
+    expect_ids: string[];
+}
+interface SensorCase {
+    name: string;
+    /** Unified diff (or added-line text) the sensors run against. */
+    diff: string;
+    paths?: string[];
+    /** Memory ids whose sensor SHOULD fire on this diff. */
+    expect_fire_ids: string[];
+}
+interface EvalSpec {
+    retrieval?: RetrievalCase[];
+    sensors?: SensorCase[];
+}
+interface RetrievalCaseResult {
+    name: string;
+    expect_ids: string[];
+    /** Surfaced memory ids, in ranked order, capped at k. */
+    surfaced_ids: string[];
+    hits: string[];
+    misses: string[];
+    precision: number;
+    recall: number;
+    /** 1-based rank of the first expected id among surfaced ids; null if none surfaced. */
+    best_rank: number | null;
+}
+interface SensorCaseResult {
+    name: string;
+    expect_fire_ids: string[];
+    fired_ids: string[];
+    hits: string[];
+    misses: string[];
+    recall: number;
+}
+interface RetrievalAggregate {
+    cases: RetrievalCaseResult[];
+    /**
+     * Top-k precision = expected hits ÷ surfaced results. Inherently LOW when only ~1 memory is
+     * expected per case but k results are surfaced (e.g. 1/8 ≈ 0.12) — this is a top-k artifact, not
+     * a quality defect. Retrieval quality is judged by `mean_recall` and `mrr`; precision is NOT part
+     * of the headline eval score (see `scoreEval`). Reported for completeness only.
+     */
+    mean_precision: number;
+    mean_recall: number;
+    /** Mean reciprocal rank of the first expected hit — rewards ranking the right memory high. */
+    mrr: number;
+}
+interface SensorAggregate {
+    cases: SensorCaseResult[];
+    catch_rate: number;
+}
+interface EvalReport {
+    retrieval: RetrievalAggregate | null;
+    sensors: SensorAggregate | null;
+    /** Overall quality score 0..100. */
+    score: number;
+}
+/**
+ * Score one retrieval case from the (ranked) ids the briefing surfaced.
+ * `surfacedRanked` should already be capped to the top-k the caller cares about.
+ */
+declare function scoreRetrievalCase(name: string, expectIds: string[], surfacedRanked: string[]): RetrievalCaseResult;
+declare function aggregateRetrieval(cases: RetrievalCaseResult[]): RetrievalAggregate;
+declare function scoreSensorCase(name: string, expectFireIds: string[], firedIds: string[]): SensorCaseResult;
+declare function aggregateSensors(cases: SensorCaseResult[]): SensorAggregate;
+/** Combine retrieval + sensor aggregates into a single 0..100 quality score. */
+declare function overallScore(retrieval: RetrievalAggregate | null, sensors: SensorAggregate | null): number;
+declare function buildReport(retrieval: RetrievalAggregate | null, sensors: SensorAggregate | null): EvalReport;
+/**
+ * Baseline / compare — makes the "Hivelore improves retrieval by N%" claim reproducible.
+ *
+ * `hivelore eval --baseline` snapshots a report; `--compare` re-runs and diffs against it,
+ * so a ranking/sensor regression is a number, not a vibe. Pure math here; the CLI does I/O.
+ */
+interface MetricDelta {
+    baseline: number;
+    current: number;
+    /** current − baseline (positive = improvement for all these metrics). */
+    delta: number;
+}
+interface EvalDelta {
+    score: MetricDelta;
+    mean_recall: MetricDelta | null;
+    mrr: MetricDelta | null;
+    catch_rate: MetricDelta | null;
+    /** True when the overall score dropped vs the baseline. */
+    regressed: boolean;
+    /** True when the overall score rose vs the baseline. */
+    improved: boolean;
+}
+/** Diff a current report against a baseline. Pure. */
+declare function compareEvalReports(baseline: EvalReport, current: EvalReport): EvalDelta;
+/** Extract a short task-like title from a memory body (first heading or first line). */
+declare function titleFromBody(body: string): string;
+interface SelfEvalOptions {
+    /** Include each memory's anchor paths as the case files (tests anchored retrieval). */
+    includeFiles?: boolean;
+    /** Skip memories with these statuses (default: stale/deprecated/rejected). */
+    skipStatuses?: string[];
+}
+/**
+ * Synthesize retrieval cases from a repo's own anchored memories — zero-setup eval.
+ * Each anchored, non-recap, non-dead memory becomes a case: "when working on the
+ * file(s) this memory anchors, with its title as the task, does Hivelore surface it?".
+ * With `includeFiles: false` it becomes a harder semantic-only probe (title alone).
+ */
+declare function synthesizeSelfEvalCases(memories: LoadedMemory[], options?: SelfEvalOptions): RetrievalCase[];
+
+type ConfidenceLevel = "unverified" | "low" | "trusted" | "authoritative" | "stale";
+interface ConfidenceThresholds {
+    trustedReads: number;
+    authoritativeReads: number;
+    /** Days without a read after which confidence drops one tier (authoritative → trusted). */
+    decayDays: number;
+    /** Days without a read after which confidence drops two tiers (e.g. authoritative → low). */
+    hardDecayDays: number;
+}
+declare const DEFAULT_CONFIDENCE_THRESHOLDS: ConfidenceThresholds;
+/**
+ * Compute the trust level of a memory.
+ *
+ * Base tier is derived from `status + read_count`:
+ *   - draft → unverified
+ *   - proposed (low reads) → low
+ *   - proposed (3+ reads) → trusted
+ *   - validated (low reads) → trusted
+ *   - validated (10+ reads) → authoritative
+ *   - stale / deprecated / rejected → stale
+ *
+ * On top of the base tier, a TIME DECAY is applied: a memory that has not been
+ * read in `decayDays` (default 180) drops one tier, and one not read in
+ * `hardDecayDays` (default 365) drops two tiers. The clock starts at
+ * `last_read_at` if any, otherwise `created_at` from the frontmatter.
+ *
+ * The decay never crosses into `stale` (we keep that signal reserved for the
+ * verifier). The intent is to surface "this used to be authoritative but
+ * nobody has touched it in a year — verify before quoting it" without
+ * pretending the memory is wrong.
+ */
+declare function deriveConfidence(fm: MemoryFrontmatter, usage: MemoryUsage, thresholds?: ConfidenceThresholds, now?: Date): ConfidenceLevel;
+interface AutoPromoteRule {
+    /** Minimum read_count to promote proposed → validated. */
+    minReads: number;
+    /** Maximum rejected_count tolerated (memories with more rejections never auto-promote). */
+    maxRejections: number;
+}
+declare const DEFAULT_AUTO_PROMOTE_RULE: AutoPromoteRule;
+declare function isAutoPromoteEligible(fm: MemoryFrontmatter, usage: MemoryUsage, rule?: AutoPromoteRule): boolean;
+
+/**
+ * Tag stamped on memories that were pre-seeded from a stack pack at `hivelore init`
+ * (generic framework knowledge the model already largely knows, not repo-specific
+ * institutional knowledge). Briefing ranking caps these at `background` priority so
+ * a generic seed never displaces a repo-specific memory — unless the seed has been
+ * anchored to a file the agent is actually editing.
+ */
+declare const STACK_PACK_TAG = "stack-pack";
+/** True when a memory was pre-seeded from a stack pack (carries {@link STACK_PACK_TAG}). */
+declare function isStackPackSeed(fm: {
+    tags?: string[];
+} | null | undefined): boolean;
+/**
+ * Tags that mark a memory as a *local dev-environment workaround* (hot-swap, nested node_modules,
+ * global-install quirks) rather than repo-specific team policy. These are real, but they describe
+ * tooling debt, not unguessable team knowledge — and because they get read on almost every session
+ * their read_count inflates and they crowd the briefing. Ranking caps them at `background` UNLESS
+ * they directly anchor a file being edited, so they stop displacing actual policy. The fix for a
+ * recurring one is to repair the environment, not to keep surfacing the note.
+ */
+declare const ENV_WORKAROUND_TAGS: Set<string>;
+/** True when a memory is tagged as a local dev-environment workaround (see {@link ENV_WORKAROUND_TAGS}). */
+declare function isEnvWorkaroundMemory(fm: {
+    tags?: string[];
+} | null | undefined): boolean;
+declare function extractReferencedPaths(text: string): string[];
+/**
+ * True when a memory carries any tag in `excludeTags` (case-insensitive) — used to keep
+ * strategy/positioning memories OUT of automatic briefing surfacing while leaving them searchable.
+ * See `HaiveConfig.briefingExcludeTags`. Empty/undefined list ⇒ never excluded.
+ */
+declare function memoryHasExcludedTag(fm: {
+    tags?: string[];
+} | null | undefined, excludeTags: string[] | null | undefined): boolean;
+/**
+ * Best-effort inference: given a list of file paths, infer module names from
+ * conventional layouts (packages/X/, apps/X/, modules/X/, src/X/).
+ */
+declare function inferModulesFromPaths(filePaths: string[]): string[];
+/**
+ * Path overlap: returns true if `a` and `b` refer to the same path or one is a
+ * parent of the other. Both inputs are treated as POSIX-style relative paths.
+ */
+declare function pathsOverlap(a: string, b: string): boolean;
+declare function memoryMatchesAnchorPaths(memory: LoadedMemory["memory"], inputPaths: string[]): boolean;
+declare function isGlobPath(p: string): boolean;
+declare function globToRegExp(pattern: string): RegExp;
+declare function relPathFrom(root: string, abs: string): string;
+
+/**
+ * Distinctive-token corroboration for the anti-pattern gate.
+ *
+ * The pre-commit gate used to hard-block whenever a diff shared ANY ≥4-char token
+ * with an anchored gotcha's body. That fires on ubiquitous domain words ("memory",
+ * "sensor", "scope", "input", "version") and on version-bump diffs — blocking agents
+ * for nothing. The fix: a `literal` overlap only corroborates a BLOCK when at least
+ * one shared token is *distinctive* to that gotcha — i.e. rare across the gotcha
+ * corpus (low document frequency), like `BigInt`, `open-in-view`, `rec_7`. Common
+ * words can still surface the warning for review; they just can't hard-block.
+ *
+ * Pure module (no I/O), TF-IDF-style. Unit-tested in `test/distinctive.test.ts`.
+ */
+/**
+ * Language keywords + ubiquitous code words that would match almost any memory body
+ * and so carry no distinguishing signal. Shared by the diff tokenizer and the
+ * distinctiveness check so "literal" stays meaningful.
+ */
+declare const CODE_STOPWORDS: Set<string>;
+/** Minimum token length kept for word-level matching (shorter tokens are too noisy). */
+declare const MIN_WORD_LEN = 4;
+/** Split text into lowercase word tokens (>= MIN_WORD_LEN, excluding code stopwords). */
+declare function tokenizeWords(text: string): string[];
+interface DocFrequency {
+    /** token -> number of documents (memory bodies) it appears in */
+    df: Map<string, number>;
+    /** total number of documents */
+    total: number;
+}
+/** Build per-token document frequency across a corpus of memory bodies. */
+declare function buildDocFrequency(bodies: string[]): DocFrequency;
+/**
+ * Document-frequency cap at/below which a token counts as distinctive. Deliberately
+ * strict — "distinctive" means *rare* (≈ the bottom 10% of the corpus), with a floor
+ * of 1 so a token appearing in a single memory is always distinctive. Strictness is
+ * intentional: blocking is the aggressive action, so we under-block rather than fire
+ * on a word that several gotchas happen to share.
+ */
+declare function distinctiveCap(total: number): number;
+/** True when `token` is distinctive (rare) within the corpus. */
+declare function isDistinctiveToken(token: string, freq: DocFrequency): boolean;
+/**
+ * True when the added diff text shares at least one *distinctive* word token with the
+ * memory body. This is the precise corroboration the block decision should require:
+ * "the change actually contains the specific thing this gotcha warns about", not
+ * "the change happens to mention a common domain word".
+ */
+declare function diffHasDistinctiveOverlap(addedDiffText: string, memoryBody: string, freq: DocFrequency): boolean;
+
+/**
+ * Progressive disclosure for `skill` memories.
+ *
+ * Skills are reusable playbooks. Surfacing all of them on every briefing wastes the
+ * instruction budget and buries the relevant one. A skill with an `activation` block
+ * is disclosed ONLY when it is relevant to the current task/files; a skill without
+ * one keeps the legacy always-eligible behavior. This module is pure (no I/O).
+ */
+interface ActivationContext {
+    task?: string;
+    files?: string[];
+}
+interface SkillActivation {
+    applicable: boolean;
+    activated: boolean;
+    reasons: string[];
+}
+declare function isSkill(fm: Pick<MemoryFrontmatter, "type">): boolean;
+/**
+ * Decide whether a skill should be disclosed for the given context.
+ * For non-skills, or skills with no `activation` block, returns `activated: true`
+ * (never suppress them). Otherwise activates on `always`, a keyword substring match
+ * against the task, or a glob match against the edited files.
+ */
+declare function evaluateSkillActivation(fm: Pick<MemoryFrontmatter, "type" | "activation">, ctx: ActivationContext): SkillActivation;
+/** Convenience: true when a skill defines activation triggers that the context does NOT satisfy. */
+declare function isSkillSuppressed(fm: Pick<MemoryFrontmatter, "type" | "activation">, ctx: ActivationContext): boolean;
+
+/**
+ * Specificity ("surprise") scoring for memories.
+ *
+ * Hivelore's measured value is preventing agents from reinventing — wrongly — the team's
+ * NON-OBVIOUS, arbitrary decisions (e.g. "public ids are internal id + 100000 prefixed AC-",
+ * "the status field must be 'OK'/'KO'"). A capable model already knows generic best practice
+ * ("use Decimal for money", "validate input"), so surfacing that is pure token overhead.
+ *
+ * `specificityScore` is a cheap, deterministic heuristic that estimates how *unguessable* a
+ * memory is: high when it contains concrete, arbitrary signal (string literals, code
+ * identifiers, magic numbers, paths, ALLCAPS constants), low when it is generic prose.
+ *
+ * It is intentionally a heuristic, not a model call — used to (1) bias briefing ranking toward
+ * unguessable knowledge, (2) keep a near-empty briefing cheap when nothing team-specific
+ * matches, (3) lint low-value memories, and (4) filter auto-capture candidates.
+ */
+/**
+ * Estimate how unguessable / team-specific a memory body is, in [0, 1].
+ * ~0  = generic advice a model already follows by default.
+ * ~1  = arbitrary, repo-specific knowledge no model can infer.
+ */
+declare function specificityScore(body: string): number;
+/**
+ * True when a body uses generic best-practice phrasing a capable model already follows.
+ * Used to SCOPE the LOW_VALUE lint: a low-density body is only "guessable noise" when it also
+ * reads like generic advice. An arbitrary team *policy* can be prose-y yet unguessable (e.g.
+ * "UI text in English, user content in any language") — that must NOT be flagged. Positive
+ * evidence (a generic phrase) keeps the lint high-precision and kills that false positive.
+ */
+declare function looksLikeGenericAdvice(body: string): boolean;
+/** Default threshold below which a memory is considered likely-guessable (low marginal value). */
+declare const GUESSABLE_THRESHOLD = 0.3;
+/** True when a memory body looks like generic knowledge a capable model already has. */
+declare function isLikelyGuessable(body: string, threshold?: number): boolean;
+/**
+ * Quality floor for SEEDED memories (stack packs, ingested findings) — the guard against shipping
+ * low-value "use const not var" starter content. A seed earns its place only if it is either:
+ *   - ENFORCEABLE: it carries a hand-authored sensor (its value is the gate, not its prose), or
+ *   - SPECIFIC: it reads as a concrete framework/repo trap (specificity >= floor) and is NOT
+ *     generic best-practice prose a capable model already follows.
+ * Used both at seed time (skip a memory that fails) and as a CI guard over the shipped pack library.
+ *
+ * The floor (0.2) is intentionally LOWER than {@link GUESSABLE_THRESHOLD} (0.3, used to lint claimed
+ * team knowledge): a seed is explicitly background-priority framework REFERENCE, not a claim of
+ * non-guessable team policy, so a concrete framework gotcha with a code example clears it — while
+ * genuine garbage ("use const", "write tests") still scores ~0 and/or trips looksLikeGenericAdvice.
+ */
+declare const SEED_QUALITY_FLOOR = 0.2;
+declare function meetsSeedQualityFloor(body: string, hasSensor: boolean, floor?: number): boolean;
+
+/**
+ * Token budgeting helpers. We use the standard heuristic of ~4 chars per token,
+ * which is conservative for English/code/markdown. Callers that need exact
+ * counts should plug in a real tokenizer; this module only ever over-estimates,
+ * so the user's hard limits are respected.
+ */
+declare const CHARS_PER_TOKEN = 4;
+declare function estimateTokens(text: string): number;
+interface TruncateOptions {
+    /** Maximum tokens allowed in the result (inclusive). */
+    maxTokens: number;
+    /** Marker inserted where content was dropped. */
+    marker?: string;
+    /** Where to keep characters from when truncating. Default: head. */
+    mode?: "head" | "tail" | "middle";
+}
+interface TruncateResult {
+    text: string;
+    truncated: boolean;
+    estimatedTokens: number;
+    originalTokens: number;
+}
+declare function truncateToTokens(input: string, options: TruncateOptions): TruncateResult;
+/**
+ * Allocate a global token budget across N parts with relative weights, then
+ * truncate each part to its share. Returns parts in input order, paired with
+ * truncate metadata.
+ */
+interface BudgetPart {
+    key: string;
+    text: string;
+    weight: number;
+    mode?: TruncateOptions["mode"];
+}
+interface BudgetSlice {
+    key: string;
+    text: string;
+    truncated: boolean;
+    estimatedTokens: number;
+    originalTokens: number;
+    allocatedTokens: number;
+}
+declare function allocateBudget(parts: BudgetPart[], maxTokens: number): BudgetSlice[];
+
+declare const CODE_MAP_FILE = "code-map.json";
+type CodeExportKind = "function" | "class" | "interface" | "type" | "const" | "enum" | "default";
+interface CodeExport {
+    name: string;
+    kind: CodeExportKind;
+    description?: string;
+    line: number;
+}
+interface CodeFileEntry {
+    summary?: string;
+    exports: CodeExport[];
+    loc: number;
+}
+interface CodeMap {
+    version: 1;
+    generated_at: string;
+    root: string;
+    files: Record<string, CodeFileEntry>;
+}
+interface BuildCodeMapOptions {
+    includeExtensions?: string[];
+    excludeDirs?: string[];
+    /** Include untracked files that are not ignored by git. Default: false when the root is a git repo. */
+    includeUntracked?: boolean;
+}
+declare function codeMapPath(paths: HaivePaths): string;
+declare function loadCodeMap(paths: HaivePaths): Promise<CodeMap | null>;
+declare function saveCodeMap(paths: HaivePaths, map: CodeMap): Promise<void>;
+declare function buildCodeMap(root: string, options?: BuildCodeMapOptions): Promise<CodeMap>;
+/**
+ * Count source files physically present on disk (FS walk, excluding node_modules/build/hidden dirs),
+ * regardless of git tracking. Used by `hivelore doctor` to detect a code-map that captured far fewer
+ * files than the repo actually holds (untracked source, or a structure the indexer missed).
+ */
+declare function countSourceFilesOnDisk(root: string, options?: {
+    excludeDirs?: string[];
+}): Promise<number>;
+interface CodeMapQueryOptions {
+    file?: string;
+    symbol?: string;
+}
+declare function queryCodeMap(map: CodeMap, options: CodeMapQueryOptions): {
+    files: Array<{
+        path: string;
+        entry: CodeFileEntry;
+    }>;
+};
+
+interface AstExport {
+    name: string;
+    kind: CodeExportKind;
+    /** 1-based line of the declaration (or the `export`/assignment that introduces it). */
+    line: number;
+}
+/**
+ * Parse a source file into its exported symbols using a real AST. Returns null when AST parsing is
+ * unavailable for this file (unsupported extension, runtime init failure, or grammar load failure),
+ * which signals the caller to use the regex fallback. An empty array means "parsed fine, no exports".
+ */
+declare function parseFileAst(source: string, ext: string): Promise<AstExport[] | null>;
+
+declare const CONFIG_FILE = "haive.config.json";
+/** A remote or local repo to pull shared memories from. */
+interface CrossRepoSource {
+    /** Human-readable name for this source (used in imported memory tags). */
+    name: string;
+    /** Local filesystem path to the other project's root (relative or absolute). */
+    path?: string;
+    /** Git URL — clone/fetch performed automatically. */
+    git?: string;
+    /** Only import memories matching all of these filters. */
+    filter?: {
+        /** Only import memories with these tags. */
+        tags?: string[];
+        /** Only import memories of these types. */
+        types?: string[];
+    };
+}
+/** An API contract file to snapshot and monitor for breaking changes. */
+interface ContractFile {
+    /** Human-readable name for this contract. */
+    name: string;
+    /** Path to the contract file, relative to the project root. */
+    path: string;
+    /** Format of the contract file. */
+    format: "openapi" | "graphql" | "proto" | "typescript" | "json-schema";
+}
+interface HaiveConfig {
+    /** Autopilot mode: maximum autonomy, minimum human intervention. Default: false. */
+    autopilot?: boolean;
+    /**
+     * Adaptive briefing: when get_briefing finds no team-specific (unguessable) memory for the
+     * task/files, trim the auto-generated project context so the call stays near-zero-cost.
+     * A capable model needs nothing extra in that case. Curated context is never trimmed.
+     * Default: true.
+     */
+    adaptiveBriefing?: boolean;
+    /**
+     * Memory tags that are EXCLUDED from automatic surfacing in `get_briefing` / `mem_relevant_to`.
+     * Purpose: break the self-reinforcing bias loop where strategy/positioning memories get auto-injected
+     * into every agent's context and shape its *opinions* (not just its facts). Excluded memories are
+     * still fully searchable via explicit `mem_search` / `memory search` — they just don't auto-load.
+     * Matching is case-insensitive on frontmatter tags. Default targets clearly-meta tags; override
+     * (set to `[]` to disable). Note: this filters by TAG, so tag strategy notes accordingly.
+     */
+    briefingExcludeTags?: string[];
+    /** Default scope for new memories. Default: "personal". Autopilot sets "team". */
+    defaultScope?: "personal" | "team";
+    /**
+     * Default status for new memories saved via mem_save.
+     * Autopilot sets "validated" — skips the approval cycle entirely.
+     * Default: "draft".
+     */
+    defaultStatus?: "draft" | "validated";
+    /** Auto-approve proposed memories after N hours without rejection. Default: null (disabled). */
+    autoApproveDelayHours?: number | null;
+    /**
+     * Auto-promote proposed→validated after N reads (overrides DEFAULT_AUTO_PROMOTE_RULE).
+     * Autopilot sets 1 (immediate on first use).
+     */
+    autoPromoteMinReads?: number;
+    /** Auto-save session recap on MCP server exit. Default: true in autopilot, false otherwise. */
+    autoSessionEnd?: boolean;
+    /**
+     * Persist an auto-generated `session_recap` MEMORY into the `.ai/` corpus on automatic
+     * session end (MCP exit / SessionEnd hook). Default: true (preserves historical behavior).
+     * Set false to stop the low-signal recap dump from accumulating in — and biasing — the corpus;
+     * pair with `sessionHandoff` for an ephemeral NEXT.md handoff instead. Has no effect on a
+     * manual `hivelore session end --goal ...` (an explicit recap is always honored).
+     */
+    autoSessionRecap?: boolean;
+    /**
+     * On automatic session end, write/overwrite an ephemeral `NEXT.md` handoff at the repo root
+     * (open threads + next steps). Default: false. Meant to be gitignored — one overwritten file,
+     * not an accumulating corpus memory. Surfaced as `last_session` when no recap memory exists.
+     */
+    sessionHandoff?: boolean;
+    /**
+     * Auto-generate a minimal project context from code-map when project-context.md is still
+     * the template. Default: true in autopilot, false otherwise.
+     */
+    autoContext?: boolean;
+    /**
+     * Safe self-maintenance performed automatically in autopilot mode.
+     * These repairs are intentionally conservative: no guessed anchor is applied
+     * without strong evidence, but headings/tags/indexes/context metadata can be
+     * kept fresh by the tool itself.
+     */
+    autoRepair?: {
+        /** Keep .ai/project-context.md version metadata aligned with package.json. */
+        context?: boolean;
+        /** Apply safe memory lint fixes: headings and `needs_anchor` tags. */
+        corpus?: boolean;
+        /** Refresh .ai/code-map.json during sync when needed. */
+        codeMap?: boolean;
+        /** Best-effort build of code-search embeddings when @hivelore/embeddings is available. */
+        codeSearch?: boolean;
+    };
+    /**
+     * Other repos to pull `shared`-scoped memories from during `hivelore sync`.
+     * Each source must have either `path` (local) or `git` (remote URL).
+     *
+     * Example:
+     *   { "name": "backend", "path": "../repo-backend", "filter": { "tags": ["api-contract"] } }
+     */
+    crossRepoSources?: CrossRepoSource[];
+    /**
+     * API contract files to snapshot and watch for breaking changes.
+     * `hivelore sync` compares the current file against `.ai/contracts/<name>.lock`
+     * and creates a `gotcha` memory if a breaking change is detected.
+     *
+     * Example:
+     *   { "name": "payment-api", "path": "docs/openapi.yaml", "format": "openapi" }
+     */
+    contractFiles?: ContractFile[];
+    /**
+     * Local path to a shared team-knowledge hub repo.
+     * Used by `hivelore hub pull` and `hivelore hub push`.
+     * Can be relative (resolved from project root) or absolute.
+     */
+    hubPath?: string;
+    /**
+     * Lock file paths to watch for dependency version changes.
+     * Auto-detected if not specified (package.json, pom.xml, go.mod, etc.).
+     * Set to [] to disable dependency tracking entirely.
+     */
+    dependencyFiles?: string[];
+    /**
+     * Agent-enforcement settings. Enabled by default so initialized projects
+     * treat Hivelore as infrastructure, not an optional convention.
+     */
+    enforcement?: {
+        /** Enforcement posture: advisory reports only, warn in hooks, or block workflow gates. */
+        mode?: "off" | "advisory" | "strict";
+        /** Require get_briefing / mem_relevant_to before state-changing MCP tools. */
+        requireBriefingFirst?: boolean;
+        /**
+         * Pre-edit (PreToolUse) behaviour when a file's anchored policy was not yet surfaced:
+         *   - "advise" (default): inject the relevant memory content into the agent's context and record
+         *     it in the briefing marker, then ALLOW the edit — no round-trip, no separate briefing command.
+         *   - "block": hard-block the edit until a briefing covers the file (the legacy strict behaviour).
+         * The commit-time decision-coverage gate and CI enforcement remain the hard backstops either way.
+         */
+        preEditGate?: "advise" | "block";
+        /** Require a session recap before pre-push / CI gates pass. */
+        requireSessionRecap?: boolean;
+        /** Require memory anchor verification before pre-commit / CI gates pass. */
+        requireMemoryVerify?: boolean;
+        /** Block changes when anchored decisions/gotchas have become stale. */
+        blockStaleDecisionChanges?: boolean;
+        /** Require changed files to be covered by relevant surfaced decisions/policies. */
+        requireDecisionCoverage?: boolean;
+        /**
+         * How hard the pre-commit anti-pattern gate blocks a matching attempt/gotcha:
+         *   - off:      never block on anti-patterns (report only)
+         *   - review:   block only on a very strong semantic match (score ≥ 0.75) — soft, legacy default
+         *   - anchored: ALSO block when a high-confidence anti-pattern is anchored to a touched file
+         *               and corroborated by the diff (literal token or semantic ≥ 0.45). High precision.
+         *   - strict:   block on any high-confidence anti-pattern match (anchor, literal, or semantic)
+         * Config/docs-only commits are always downgraded regardless of this setting.
+         * Default: "anchored" — makes "known bad approaches are blocked" true for the precise case.
+         */
+        antiPatternGate?: "off" | "review" | "anchored" | "strict";
+        /**
+         * First-agent bootstrap gate. The trigger is the COLD STATE of the corpus, not a command or flag:
+         * when the knowledge layer is empty, the very first agent is forced to fill the baseline — a filled
+         * project-context, a module context per component, an anchored memory per main code area, and a
+         * sensor per main code area — before its commit / `enforce finish` can pass. Once the baseline
+         * exists the gate is silent for every later agent, so only the first agent ever pays.
+         *   - off:   never gate on bootstrap completeness
+         *   - warn:  surface the missing baseline as a warning (advisory)
+         *   - block: hard-fail commit/finish until the baseline exists (default)
+         * Config/docs-only commits (no production code changed) are downgraded to a warning regardless.
+         */
+        bootstrapGate?: "off" | "warn" | "block";
+        /**
+         * Pre-commit/pre-push decision-coverage behaviour. When true (default), the gate SURFACES the
+         * relevant anchored decisions/policies itself and records them in the session marker at commit
+         * time — no separate `hivelore briefing` step required. Set false for the strict legacy behaviour
+         * where the commit is blocked until a prior briefing covered those decisions.
+         */
+        autoBrief?: boolean;
+        /**
+         * Execute `kind: "shell" | "test"` memory sensors during `hivelore sensors check`.
+         * These run arbitrary repo-authored commands, so they are OFF by default; turn on per repo
+         * (or pass `--commands`) once the team trusts the sensors. Regex sensors always run. Default false.
+         */
+        runCommandSensors?: boolean;
+        /**
+         * How `hivelore enforce finish` reacts to hard failures observed this session that were never
+         * captured as a lesson (`mem_tried`):
+         *   - off:   ignore
+         *   - warn:  surface them as an info finding (default — failure detection has false positives)
+         *   - block: hard-block finish until each is captured
+         * Default: "warn".
+         */
+        failureCaptureGate?: "off" | "warn" | "block";
+        /**
+         * How `hivelore eval --ci` reacts to a harness-quality regression vs the recorded baseline:
+         *   - off:   never block
+         *   - warn:  report the drop (default)
+         *   - block: exit non-zero on any score drop
+         * Default: "warn".
+         */
+        evalRegressionGate?: "off" | "warn" | "block";
+        /**
+         * Default unread-age window (in days) for `hivelore memory archive` corpus decay.
+         * A noisy or stale corpus is actively harmful — it makes the agent follow outdated policy.
+         * Default: 180.
+         */
+        decayAfterDays?: number;
+        /** Minimum score required for strict enforcement gates. */
+        scoreThreshold?: number;
+        /** Remove generated Hivelore runtime/cache files during cleanup gates. */
+        cleanupGeneratedArtifacts?: boolean;
+        /**
+         * MCP tool surface:
+         * - enforcement: compact default harness for coding agents
+         * - maintenance: corpus/admin tools for humans and team stewards
+         * - experimental: research/diagnostic tools that are not core product surface
+         * - full: legacy alias for experimental
+         */
+        toolProfile?: "enforcement" | "maintenance" | "experimental" | "full";
+        /** Named memory/policy families enabled for this project. */
+        policyPacks?: string[];
+        /**
+         * Branch on which `enforce finish` enforces the release discipline (lockstep version bump +
+         * matching pushed tag) as a HARD gate. On any other branch — feature/* or an integration branch
+         * like `develop` — those same checks are advisory (warn), since the version/tag are produced when
+         * releasing from this branch, not on every integration commit. Default: "main".
+         */
+        releaseBranch?: string;
+    };
+}
+/**
+ * Tags excluded from automatic briefing surfacing by default. These are "meta" tags — strategy,
+ * positioning, competitive analysis, roadmaps — whose memories bias an agent's opinions rather than
+ * inform a concrete coding task. Still searchable via explicit mem_search.
+ */
+declare const DEFAULT_BRIEFING_EXCLUDE_TAGS: string[];
+declare const DEFAULT_CONFIG: HaiveConfig;
+declare const AUTOPILOT_DEFAULTS: HaiveConfig;
+/** The pre-commit anti-pattern gate hardness levels. */
+type AntiPatternGate = "off" | "review" | "anchored" | "strict";
+/**
+ * Single source of truth mapping a configured `antiPatternGate` to the
+ * `pre_commit_check` parameters that implement it. Both the git-hook path
+ * (`hivelore enforce check`) and the standalone `hivelore precommit` command derive
+ * their behavior from this so the two surfaces can never drift apart.
+ */
+declare function antiPatternGateParams(gate: AntiPatternGate): {
+    block_on: "any" | "high-confidence" | "never";
+    anchored_blocks: boolean;
+};
+declare function configPath(paths: HaivePaths): string;
+declare function loadConfig(paths: HaivePaths): Promise<HaiveConfig>;
+declare function loadConfigSync(paths: HaivePaths): HaiveConfig;
+declare function saveConfig(paths: HaivePaths, config: HaiveConfig): Promise<void>;
+
+interface CrossRepoReport {
+    source: string;
+    imported: string[];
+    updated: string[];
+    skipped: string[];
+    errors: string[];
+}
+/**
+ * Pull shared memories from all configured cross-repo sources.
+ * Returns one report per source.
+ */
+declare function pullCrossRepoSources(paths: HaivePaths, config: HaiveConfig, projectRoot: string): Promise<CrossRepoReport[]>;
+
+interface DependencySnapshot {
+    file: string;
+    format: string;
+    captured_at: string;
+    deps: Record<string, string>;
+}
+interface DepChange {
+    name: string;
+    from: string;
+    to: string;
+    /** true if the major version number changed */
+    isMajorBump: boolean;
+}
+interface DepTrackResult {
+    file: string;
+    changes: DepChange[];
+}
+/**
+ * Resolve which manifest files to track.
+ * Uses config.dependencyFiles if set, otherwise auto-detects from KNOWN_MANIFESTS.
+ */
+declare function resolveManifestFiles(projectRoot: string, configuredFiles?: string[]): string[];
+/**
+ * Check all manifest files for version changes since last snapshot.
+ * Returns one result per file that has changes.
+ */
+declare function trackDependencies(projectRoot: string, haiveDir: string, manifestFiles: string[]): Promise<DepTrackResult[]>;
+
+interface ContractSnapshot {
+    name: string;
+    path: string;
+    format: string;
+    captured_at: string;
+    hash: string;
+    endpoints?: string[];
+    types?: string[];
+    fields?: Record<string, string[]>;
+    raw_lines?: string[];
+}
+interface BreakingChange {
+    kind: "endpoint_removed" | "endpoint_added" | "type_removed" | "type_added" | "field_removed" | "field_added" | "content_changed";
+    description: string;
+    severity: "breaking" | "additive" | "unknown";
+}
+interface ContractDiffResult {
+    contract: string;
+    file: string;
+    changes: BreakingChange[];
+    unchanged: boolean;
+}
+declare function contractLockPath(haiveDir: string, name: string): string;
+/**
+ * Take a snapshot of a contract file and save it to .ai/contracts/<name>.lock.
+ * Returns the snapshot.
+ */
+declare function snapshotContract(projectRoot: string, haiveDir: string, contract: ContractFile): Promise<ContractSnapshot>;
+/**
+ * Compare a contract file against its stored snapshot.
+ * Returns the diff result. If no snapshot exists, creates one and returns unchanged.
+ */
+declare function diffContract(projectRoot: string, haiveDir: string, contract: ContractFile): Promise<ContractDiffResult>;
+/**
+ * Check all configured contract files for changes.
+ */
+declare function watchContracts(projectRoot: string, haiveDir: string, contractFiles: ContractFile[]): Promise<ContractDiffResult[]>;
+
+declare const USAGE_LOG_FILE = "tool-usage.jsonl";
+declare const USAGE_LOG_DIR = ".usage";
+interface UsageEvent {
+    /** ISO timestamp */
+    at: string;
+    /** Tool name (MCP tool or CLI command) */
+    tool: string;
+    /** Truncated, non-sensitive snapshot of the input */
+    summary?: string;
+}
+declare function usageLogPath(paths: HaivePaths): string;
+/**
+ * Append a single usage event to the rolling log. Best-effort: failures are
+ * swallowed since logging must never block tool execution.
+ */
+declare function appendUsageEvent(paths: HaivePaths, event: UsageEvent): Promise<void>;
+/**
+ * Read all usage events from disk. Skips malformed lines silently.
+ * For very large logs (>50k lines), prefer `streamUsageEvents` (not implemented yet).
+ */
+declare function readUsageEvents(paths: HaivePaths): Promise<UsageEvent[]>;
+interface UsageAggregate {
+    total: number;
+    by_tool: Array<{
+        tool: string;
+        count: number;
+        last_used: string;
+    }>;
+    /** Most-frequently called tools first */
+    top: Array<{
+        tool: string;
+        count: number;
+    }>;
+    window_start: string | null;
+    window_end: string | null;
+}
+/**
+ * Bucket events by tool, optionally filtered by a since cutoff (ISO date or relative like '7d').
+ */
+declare function aggregateUsage(events: UsageEvent[], since?: Date): UsageAggregate;
+/**
+ * Parse a since string: ISO date, or relative like '7d', '24h', '30m'.
+ * Returns null when input is empty/undefined.
+ */
+declare function parseSince(input: string | undefined): Date | null;
+declare function usageLogSize(paths: HaivePaths): Promise<{
+    exists: boolean;
+    size_bytes: number;
+    lines: number;
+}>;
+
+/**
+ * Named budgets for get_briefing so agents choose quality vs token cost intentionally.
+ */
+type BriefingBudgetPreset = "quick" | "balanced" | "deep";
+interface BriefingBudgetNumbers {
+    max_tokens: number;
+    max_memories: number;
+    include_module_contexts: boolean;
+}
+declare const BRIEFING_PRESET_DEFAULTS: Record<BriefingBudgetPreset, BriefingBudgetNumbers>;
+/**
+ * Merge preset-derived numbers with caller overrides when no preset was selected.
+ */
+declare function resolveBriefingBudget(preset: BriefingBudgetPreset | undefined, overrides: BriefingBudgetNumbers): BriefingBudgetNumbers;
+
+/**
+ * Strip memory markdown down to actionable bullet lines — cheaper for briefing payloads.
+ */
+/**
+ * Prefer markdown list lines; fall back to the first substantive paragraph block.
+ */
+declare function extractActionsBriefBody(markdown: string, maxChars?: number): string;
+
+interface ResolveProjectInfo {
+    cwd: string;
+    resolved_root: string;
+    haive_project_root_env: string | null;
+    explicit_root: boolean;
+    haive_dir_exists: boolean;
+    memories_dir_exists: boolean;
+    runtime_dir: string;
+    /** Which of `.ai`, `.git`, `package.json` exist at `resolved_root`. */
+    markers_found: string[];
+}
+/**
+ * Resolve the Hivelore project root for diagnostics (MCP / CLI). Never throws.
+ */
+declare function resolveProjectInfo(opts?: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): ResolveProjectInfo;
+
+/**
+ * Suggest a stable `topic` frontmatter key (topic-upsert) from type + title.
+ */
+declare function suggestTopicKey(type: string, titleOrPhrase: string): {
+    topic_key: string;
+    family: string;
+};
+
+interface LexicalRankResult {
+    ranked: LoadedMemory[];
+    scores: number[];
+}
+/**
+ * Okapi-BM25–style ranking over a small in-memory corpus (no extra index file).
+ */
+declare function rankMemoriesLexical(loadedMemories: LoadedMemory[], query: string, limit: number): LexicalRankResult;
+
+declare function firstMemoryOneLine(body: string): string;
+interface TimelineEntry {
+    id: string;
+    type: string;
+    scope: string;
+    created_at: string;
+    one_line: string;
+    topic?: string;
+}
+interface CollectTimelineOpts {
+    memoryId?: string;
+    topic?: string;
+    limit: number;
+}
+/**
+ * Memories related by id seed (related_ids, shared topic, anchor overlap) or by topic alone.
+ */
+declare function collectTimelineEntries(all: LoadedMemory[], opts: CollectTimelineOpts): {
+    entries: TimelineEntry[];
+    notice?: string;
+};
+
+interface ConflictCandidatesOpts {
+    sinceDays: number;
+    types: string[];
+    minJaccard: number;
+    maxPairs: number;
+    /** Hard cap on memories considered ( avoids O(n²) explosions). */
+    maxScan: number;
+}
+interface ConflictCandidatePair {
+    id_a: string;
+    id_b: string;
+    jaccard: number;
+}
+interface TopicStatusPair {
+    id_a: string;
+    id_b: string;
+    topic: string;
+    status_a: string;
+    status_b: string;
+}
+/**
+ * Same `topic` key with opposed trust (validated vs rejected) — advisory; use `mem_conflicts_with` per id next.
+ */
+declare function findTopicStatusConflictPairs(memories: LoadedMemory[], maxPairs: number): TopicStatusPair[];
+/**
+ * Bulk heuristic: lexical similarity pairs for human review → often followed by `mem_conflicts_with`.
+ */
+declare function findLexicalConflictPairs(memories: LoadedMemory[], opts: ConflictCandidatesOpts): {
+    pairs: ConflictCandidatePair[];
+    scanned: number;
+    truncated: boolean;
+};
+
+declare const RUNTIME_JOURNAL_FILENAME = "session-journal.ndjson";
+interface RuntimeJournalEntry {
+    ts: string;
+    kind: "note" | "session_end" | "mcp";
+    /** Short human or agent message */
+    message: string;
+    /** Optional MCP tool name for kind=mcp */
+    tool?: string;
+    /** Arbitrary JSON-serializable metadata */
+    meta?: Record<string, unknown>;
+}
+declare function runtimeJournalPath(paths: HaivePaths): string;
+/**
+ * Append one NDJSON line under `.ai/.runtime/` (untracked by default).
+ * Never throws to callers of shutdown hooks — wraps internally.
+ */
+declare function appendRuntimeJournalEntry(paths: HaivePaths, entry: Omit<RuntimeJournalEntry, "ts"> & {
+    ts?: string;
+}): Promise<void>;
+/** Read last N valid JSON lines (oldest-first in returned array). */
+declare function readRuntimeJournalTail(paths: HaivePaths, limit: number): Promise<RuntimeJournalEntry[]>;
+
+declare const BRIEFING_MARKER_TTL_MS: number;
+declare const SESSION_RECAP_TTL_MS: number;
+interface BriefingMarker {
+    session_id: string;
+    task?: string;
+    source: string;
+    created_at: string;
+    root: string;
+    memory_ids?: string[];
+    files?: string[];
+}
+declare function enforcementDir(paths: HaivePaths): string;
+declare function briefingMarkersDir(paths: HaivePaths): string;
+declare function normalizeSessionId(sessionId?: string): string;
+declare function briefingMarkerPath(paths: HaivePaths, sessionId?: string): string;
+declare function writeBriefingMarker(paths: HaivePaths, input: {
+    sessionId?: string;
+    task?: string;
+    source: string;
+    memoryIds?: string[];
+    files?: string[];
+    /**
+     * Accumulate memory_ids/files with the existing fresh marker for THIS session instead of
+     * overwriting (default true). This is what lets decision-coverage build up as the agent works:
+     * every get_briefing call, every pre-edit injection, every `hivelore briefing` ADDS to the
+     * session's consulted set — so a broad commit no longer requires one giant briefing covering
+     * every relevant decision at once. Pass false to replace (e.g. starting a brand-new session).
+     */
+    accumulate?: boolean;
+}): Promise<BriefingMarker>;
+declare function hasRecentBriefingMarker(paths: HaivePaths, sessionId?: string, ttlMs?: number): Promise<boolean>;
+declare function readRecentBriefingMarker(paths: HaivePaths, sessionId?: string, ttlMs?: number): Promise<BriefingMarker | null>;
+declare function isFreshIsoDate(value: string | Date, ttlMs: number, now?: number): boolean;
+
+interface RetirementSignal {
+    retired: boolean;
+    reason?: string;
+}
+/**
+ * Explicit lifecycle gate for records that should not be fed back to agents as active policy.
+ *
+ * `status=deprecated/rejected/stale` is already the hard lifecycle signal. This helper covers
+ * softer signals that teams naturally write while curating a corpus: an `expires_when` date,
+ * a `superseded`/`obsolete` tag, or a short body note saying the attempt is now obsolete.
+ *
+ * Note: a plain `fixed` tag is intentionally NOT retired by itself. Many teams keep fixed
+ * gotchas active as regression guards. To retire one, mark it deprecated, set expires_when,
+ * use `obsolete`/`superseded`, or write that the fixed record is kept for audit/history only.
+ */
+declare function retirementSignal(fm: MemoryFrontmatter, body?: string, now?: Date): RetirementSignal;
+declare function isRetiredMemory(fm: MemoryFrontmatter, body?: string, now?: Date): boolean;
+
+/**
+ * Is a regex sensor pattern brittle — over-fit to incident-specific literals that rot when code
+ * shifts (hardcoded line numbers / ranges like `1131-1186`)? High-precision by design: digits that
+ * live inside a character class (`[0-9]`) or quantifier (`{2,}`) generalize and are NOT flagged, so
+ * durable patterns like `v[0-9]+\.[0-9]+` or `:\s*any\b` stay clean. Returns a short reason or null.
+ *
+ * Used to keep brittle legacy sensors from being counted as real protection or promoted to `block`.
+ */
+declare function sensorPatternBrittleness(pattern: string): string | null;
+/**
+ * Sensors — the feedback *computational* layer of the harness.
+ *
+ * A memory's `sensor` turns a documented lesson (gotcha/attempt) into a deterministic
+ * check. Unlike semantic anti-pattern matching (probabilistic, warmup-sensitive), a
+ * regex sensor fires the same way every time, so a known mistake becomes a permanent
+ * guardrail. Phase 1 supports `kind: "regex"` only — pure, no I/O. `shell`/`test`
+ * sensors are recognized but not executed here (they must run from the CLI).
+ */
+interface SensorHit {
+    /** The memory id whose sensor matched. */
+    memory_id: string;
+    /** The sensor that matched. */
+    sensor: Sensor;
+    /** Project-relative file the match was found in (when known). */
+    file?: string;
+    /** The matched line (trimmed, capped) — useful for review output. */
+    matched_line?: string;
+    /** LLM-facing self-correction message carried from the sensor. */
+    message: string;
+    severity: Sensor["severity"];
+}
+/** A unit of code to scan: a file path plus the text to match against. */
+interface SensorTarget {
+    /** Project-relative path (used for path scoping and reporting). */
+    path: string;
+    /**
+     * Text to scan. For a diff, pass only the added lines (callers should pre-filter)
+     * so a sensor fires on "you introduced the bad pattern", not "you touched a file
+     * that merely mentions it".
+     */
+    content: string;
+}
+/**
+ * Does this sensor apply to `path`? A sensor with no explicit `paths` (and whose
+ * memory has no anchor paths) applies everywhere. Otherwise it applies only to the
+ * exact file or directory prefix. Use an explicit directory path (`src/foo/`) when a
+ * sensor should cover a whole subtree.
+ */
+declare function sensorAppliesToPath(sensor: Sensor, anchorPaths: string[], path: string): boolean;
+/**
+ * Window (in added lines) searched for the `absent` (correct-usage) marker around a trigger match.
+ *
+ * FORWARD-biased on purpose: a risky call's required companion (e.g. an option object) is part of the
+ * call's ARGUMENTS, which follow the call across the next few lines — so we look mostly ahead.
+ * The lookback is tiny (catches an options-object hoisted to the line just above) but small enough
+ * that a *separate* correct call sitting above a faulty one does NOT mask the faulty one (the live
+ * failure that a symmetric window caused). Asymmetry > a single big symmetric window.
+ */
+declare const SENSOR_ABSENT_WINDOW = 6;
+declare const SENSOR_ABSENT_LOOKBACK = 2;
+/**
+ * Compile a regex sensor. Returns null when the sensor is not a runnable regex
+ * (wrong kind, missing/invalid pattern) so callers can skip it safely.
+ */
+declare function compileRegexSensor(sensor: Sensor): RegExp | null;
+/**
+ * Run a single regex sensor over one target. Returns the first matching line as a hit,
+ * or null. Deterministic and side-effect-free.
+ */
+declare function runRegexSensor(memoryId: string, sensor: Sensor, target: SensorTarget): SensorHit | null;
+/**
+ * Run every memory's regex sensor against every applicable target.
+ *
+ * Memories without a sensor, or with a non-regex sensor, are skipped (non-regex kinds
+ * are the CLI's responsibility). At most one hit per (memory, file) pair is returned.
+ */
+declare function runSensors(memories: Memory[], targets: SensorTarget[]): SensorHit[];
+/**
+ * A shell/test sensor selected for execution — the feedback *computational* layer that a regex
+ * can't express. The schema reserves `kind: "shell" | "test"`; this picks the ones whose memory
+ * applies to the changed paths so the CLI can run `command` (core stays pure — it never executes).
+ */
+interface CommandSensorSpec {
+    memory_id: string;
+    /** Command to execute (shell or test runner invocation). */
+    command: string;
+    kind: "shell" | "test";
+    severity: Sensor["severity"];
+    /** LLM-facing self-correction message carried from the sensor. */
+    message: string;
+    /** Anchor/scoped paths this sensor cares about (for reporting). */
+    paths: string[];
+}
+/**
+ * Select the shell/test sensors that apply to `changedPaths`. With no changed paths (or a sensor
+ * scoped to everywhere) the sensor is selected unconditionally. Pure: the caller executes commands.
+ */
+declare function selectCommandSensors(memories: Memory[], changedPaths: string[]): CommandSensorSpec[];
+/** Split a unified diff into per-file targets containing only added lines. */
+declare function sensorTargetsFromDiff(diff: string): SensorTarget[];
+/**
+ * Files Hivelore itself owns/generates — scanning them with sensors self-matches the very memories
+ * they mirror (a memory body documenting a bad pattern literally contains that pattern, and a
+ * generated bridge re-states the block sensors). Mirrors `isHaiveOwnedPath` in the MCP
+ * anti-pattern check; centralized here so the git-hook gate (`enforce check`) and the standalone
+ * `sensors check` CLI can never drift apart on what counts as scannable code.
+ */
+declare const HAIVE_OWNED_FILES: ReadonlySet<string>;
+/**
+ * A diff target is scannable by sensors only when it is real source — never the `.ai/` knowledge
+ * base or a Hivelore-generated bridge/config file. Without this guard, staging an `.ai/memories/*.md`
+ * file (whose body quotes the bad pattern) makes the sensor fire on itself — a false positive.
+ */
+declare function isSensorScannablePath(p: string): boolean;
+/**
+ * Filter raw diff targets down to scannable source files. Falls back to scanning the whole diff as
+ * one anonymous blob ONLY when the diff carried no file headers at all (e.g. a hand-fed `--diff-file`
+ * with bare content) — never when every header was a Hivelore-owned path, so `.ai/`-only diffs scan nothing.
+ */
+declare function scannableSensorTargets(diff: string): SensorTarget[];
+interface SensorSelfCheck {
+    /** The sensor stays SILENT on the current, presumed-correct code — i.e. it won't false-positive. */
+    silent_on_current: boolean;
+    /** Did it fire on a known-bad example from the lesson? null when no example was available. */
+    fires_on_bad: boolean | null;
+    /** Files whose CURRENT content the sensor matched — evidence of a false positive. */
+    fired_on: string[];
+    /**
+     * Safe to hard-block: silent on the current code AND (fires on the bad example, or there was no
+     * example to test). A sensor that fires on correct code is exactly what trains agents to ignore the
+     * gate — this is the gate that keeps the auto-generation layer honest.
+     */
+    passed: boolean;
+}
+/**
+ * Validate a sensor before it is trusted to hard-block. Pure: the caller supplies the CURRENT
+ * (presumed-correct) file contents and any bad examples lifted from the lesson body.
+ *
+ *   - silent_on_current: the sensor must NOT match the current code (else it false-positives).
+ *   - fires_on_bad: if the lesson carried a bad code example, the sensor SHOULD match it.
+ */
+declare function sensorSelfCheck(sensor: Sensor, input: {
+    currentTargets: SensorTarget[];
+    badExamples: string[];
+}): SensorSelfCheck;
+interface ProposedSensorVerdict {
+    /** Safe to store at the requested severity. */
+    accepted: boolean;
+    /** Why a block proposal was rejected (so the agent can revise and re-propose). */
+    reason?: "fires-on-current" | "missed-bad-example" | "brittle";
+    self_check: SensorSelfCheck;
+    /** Brittleness reason (hardcoded line numbers, etc.) or null. */
+    brittle: string | null;
+}
+/**
+ * Decide whether a PROPOSED sensor may be trusted at its severity. This is the deterministic gate
+ * behind "the agent (LLM) proposes the sensor, core validates it": a `block` sensor is accepted only
+ * if it is NOT brittle, stays SILENT on the current (presumed-correct) code, and FIRES on the bad
+ * example (when one is available). A `warn` sensor is always accepted (advisory). Pure.
+ */
+declare function judgeProposedSensor(sensor: Sensor, input: {
+    currentTargets: SensorTarget[];
+    badExamples: string[];
+}): ProposedSensorVerdict;
+/**
+ * Pull candidate bad-code examples from a lesson body: fenced code blocks and inline code spans that
+ * look like code (contain a call/dot/assignment). Used to confirm a generated sensor actually fires
+ * on the mistake it describes.
+ */
+declare function extractSensorExamples(body: string): string[];
+/**
+ * Extract the added lines from a unified diff (lines starting with a single `+`,
+ * excluding the `+++` file header). Mirrors the diff-handling already used by the
+ * anti-pattern tokenizer so sensors fire on introductions, not mere mentions.
+ */
+declare function addedLinesFromDiff(diff: string): string;
+
+interface SensorSuggestionOptions {
+    /** Extra paths to put on the sensor. Defaults to the memory anchor paths. */
+    paths?: string[];
+}
+/**
+ * A non-persisted sensor *seed*: a candidate pattern (and optional discriminating `absent` companion)
+ * extracted heuristically from a lesson body, handed to the agent to PRE-FILL a `propose_sensor` call.
+ *
+ * A seed is NOT a live guardrail. The agent-in-the-loop write paths no longer persist heuristic
+ * sensors onto frontmatter; instead they surface this seed so the agent can refine it and let
+ * `propose_sensor` validate it (silent on current code, fires on the bad example) before it is trusted
+ * to block. This is the "generate-then-validate via the LLM" pipeline — the heuristic only proposes.
+ */
+interface SensorSeed {
+    /** Regex matching the faulty usage. */
+    pattern: string;
+    /** Regex for the correct-usage marker (discriminating sensor) — present for "X without Y" lessons. */
+    absent?: string;
+    /** LLM-facing fix message derived from the lesson. */
+    message: string;
+    /** Scope paths for the eventual sensor (the lesson's anchor paths). */
+    paths: string[];
+}
+/**
+ * Conservatively extract a sensor SEED from a gotcha/attempt body — a candidate pattern for the agent
+ * to validate via `propose_sensor`, never a persisted live sensor.
+ *
+ * This helper intentionally returns null more often than it guesses: a wrong seed wastes an agent's
+ * attention, so when no distinctive token / discriminating companion is found it yields nothing and
+ * the agent is simply told to author the pattern itself.
+ */
+declare function suggestSensorSeed(body: string, anchorPaths: string[], options?: SensorSuggestionOptions): SensorSeed | null;
+/**
+ * @deprecated The agent-in-the-loop write paths no longer persist heuristic sensors — they surface a
+ * {@link SensorSeed} for `propose_sensor` to validate instead. This wrapper remains only for
+ * back-compat (and the scanner-ingestion draft path, where the sensor lands on a human-reviewed
+ * `proposed` draft and can never hard-block). It builds the old `autogen: true, severity: "warn"`
+ * sensor from a seed. Prefer {@link suggestSensorSeed}.
+ */
+declare function suggestSensorFromMemory(body: string, anchorPaths: string[], options?: SensorSuggestionOptions): Sensor | null;
+
+/**
+ * First-agent bootstrap state — is the repo's knowledge layer filled enough for later agents to rely on?
+ *
+ * The trigger for forcing a bootstrap is NOT an agent identity or a flag: it is the COLD STATE of the
+ * corpus itself. The very first agent on a fresh `hivelore init` faces an empty knowledge layer; this
+ * assessment turns "fill everything that must be filled" into a FINITE, repo-derived checklist so the
+ * gate has a precise, reachable DONE state. Once the baseline exists the assessment returns `ready`
+ * and every gate that consults it goes silent — so only the first agent ever pays the cost.
+ *
+ * Pure domain logic: no I/O. Callers load memories / code-map / module dirs and pass them in.
+ */
+
+type BootstrapGate = "off" | "warn" | "block";
+type BootstrapState = "cold" | "partial" | "ready";
+interface BootstrapGap {
+    kind: "project-context" | "module-context" | "memory-coverage" | "sensor-coverage" | "index-code";
+    /** Human/agent-readable description of what is missing. */
+    detail: string;
+    /** Concrete items the gap applies to (component names / areas). */
+    items: string[];
+    /** Exact tool/command call that closes the gap. */
+    fix: string;
+}
+interface BootstrapMetrics {
+    projectContextFilled: boolean;
+    components: string[];
+    modulesCovered: number;
+    modulesRequired: number;
+    memoryCoveredAreas: number;
+    sensorCoveredAreas: number;
+    mainAreas: number;
+    teamMemories: number;
+    sensors: number;
+}
+interface BootstrapAssessment {
+    state: BootstrapState;
+    /** Empty exactly when state === "ready". */
+    gaps: BootstrapGap[];
+    metrics: BootstrapMetrics;
+}
+interface BootstrapStateInput {
+    /** Raw project-context.md content ("" if absent). */
+    projectContextRaw: string;
+    /** All memories loaded from .ai/memories. */
+    memories: LoadedMemory[];
+    /** Code file paths from the code-map (raw; this module filters out non-production files). */
+    codeFiles: string[];
+    /** Module names present under .ai/modules/<name>/ (directory names). */
+    existingModules: string[];
+}
+/**
+ * project-context is still the auto-generated template / stub rather than real content.
+ * Matches the canonical detection used in briefing.ts / get-briefing: the auto-context marker counts
+ * ONLY when the unfilled `TODO —` placeholders are still present (>=2). A filled context that merely
+ * mentions "auto-generated by `hivelore init`" in prose (e.g. a glossary line) is NOT a template.
+ */
+declare function isTemplateProjectContext(raw: string): boolean;
+/** Derive the component (main code area) a file belongs to. */
+declare function componentOf(file: string): string;
+/** The module-context directory name for a component (its last path segment). */
+declare function moduleNameOf(component: string): string;
+/**
+ * Assess whether the repo knowledge layer is filled enough (the EXHAUSTIVE bar):
+ *  1. project-context.md is filled (not the template, and substantial)
+ *  2. every detected component (≥2) has a module context
+ *  3. every main code area has at least one anchored memory  (knowledge coverage)
+ *  4. every main code area has at least one memory carrying a sensor (guardrail coverage)
+ */
+declare function assessBootstrapState(input: BootstrapStateInput): BootstrapAssessment;
+/** Render the assessment's gaps as a numbered checklist for an agent (action_required / gate message). */
+declare function renderBootstrapChecklist(assessment: BootstrapAssessment): string;
+
+/**
+ * Findings ingestion — the self-feeding half of the sensors story (feature B).
+ *
+ * Phase 1/2 turned a documented mistake into an executable `sensor`. But someone still has
+ * to *document* the mistake. Findings ingestion closes the review↔memory loop: a real defect
+ * reported by a scanner (SonarQube, or any SARIF-emitting tool like ESLint/Semgrep/CodeQL)
+ * becomes an anchored `gotcha`/`convention` memory, pre-filled with a conservative autogen
+ * sensor, so the *next* agent is steered away from it before it writes the same code.
+ *
+ * This module is pure: parsers + draft synthesis, no I/O. The CLI (`hivelore ingest`) and the
+ * MCP tool (`ingest_findings`) read files / write memories around these functions.
+ *
+ * Safety: every draft is `status: proposed` and every suggested sensor is `severity: warn`
+ * + `autogen: true`. Ingestion never auto-validates and never auto-blocks (safety rules +
+ * `2026-05-07-attempt-strict-precommit-gate-on-haive`). A human promotes both.
+ */
+type FindingSeverity = "info" | "minor" | "major" | "critical" | "blocker";
+interface Finding {
+    /** Source tool, e.g. "sonar", "eslint", "semgrep". */
+    tool: string;
+    /** Rule key, e.g. "typescript:S1234" or "no-unused-vars". */
+    ruleId: string;
+    /** Human-readable description of the problem. */
+    message: string;
+    severity: FindingSeverity;
+    /** Project-relative file path. */
+    path: string;
+    /** 1-based line number, when known. */
+    line?: number;
+    /** Offending source snippet, when the report provides one. */
+    snippet?: string;
+    /**
+     * Stable dedup key: `tool:ruleId:path`. Deliberately excludes the line so re-running a
+     * scan after unrelated edits (which shift line numbers) does not re-propose the same memory.
+     */
+    key: string;
+}
+interface MemoryDraft {
+    key: string;
+    /** `ingest:<key>` — used as the memory `topic` so re-ingestion upserts instead of duplicating. */
+    topic: string;
+    frontmatter: MemoryFrontmatter;
+    body: string;
+    finding: Finding;
+    /** True when a conservative sensor could be derived from the finding. */
+    has_sensor: boolean;
+}
+interface DraftOptions {
+    /** Memory type for the draft. Default "gotcha". */
+    type?: "gotcha" | "convention";
+    /** Scope for the draft. Default "team". */
+    scope?: "personal" | "team" | "module";
+    module?: string;
+    author?: string;
+}
+interface DraftsOptions extends DraftOptions {
+    /** Cap on number of drafts produced (after in-batch dedup). */
+    limit?: number;
+    /** Only ingest findings at or above this severity. Default: none (all). */
+    minSeverity?: FindingSeverity;
+    /** Include auto-fixable stylistic rules (semi/quotes/indent/prefer-const…). Default false — they are
+     *  linter-autofix noise, not lessons worth a memory. */
+    includeStylistic?: boolean;
+}
+/** True when a finding's rule is pure auto-fixable formatting / naming convention (no lesson value as a seed). */
+declare function isStylisticRule(ruleId: string): boolean;
+/** Normalize a tool-specific severity string to the shared scale. */
+declare function normalizeFindingSeverity(raw: string | undefined | null): FindingSeverity;
+/**
+ * Parse SARIF 2.1.0 (`runs[].results[]`). Works for any SARIF emitter (ESLint, Semgrep,
+ * CodeQL, etc.). The tool name comes from `runs[].tool.driver.name`.
+ */
+declare function parseSarif(input: string | unknown): Finding[];
+/**
+ * Parse the SonarQube issues payload (`issues[]` from `/api/issues/search`). The file path
+ * lives in `component` as `projectKey:relative/path`; we strip the project key.
+ */
+declare function parseSonar(input: string | unknown): Finding[];
+/**
+ * Parse the ESLint JSON formatter output (`eslint --format json`): an array of
+ * `{ filePath, messages: [{ ruleId, severity, message, line }] }`. No SARIF formatter
+ * package needed — this is ESLint's built-in format. `severity` is 2=error, 1=warning.
+ * `opts.cwd`, when given, makes absolute `filePath`s project-relative so anchoring works.
+ */
+declare function parseEslintJson(input: string | unknown, opts?: {
+    cwd?: string;
+}): Finding[];
+/**
+ * Parse `npm audit --json` output (`vulnerabilities` map). Each vulnerable package becomes one
+ * finding anchored to `package.json` (vulnerabilities are dependency-level, not file-level), so
+ * the next agent is warned before re-introducing or ignoring the advisory.
+ */
+declare function parseNpmAudit(input: string | unknown): Finding[];
+type FindingFormat = "sarif" | "sonar" | "eslint" | "npm-audit";
+/** Dispatch to the right parser by declared format. */
+declare function parseFindings(format: FindingFormat, input: string | unknown, opts?: {
+    cwd?: string;
+}): Finding[];
+/** Build the markdown body for a finding-derived memory. */
+declare function findingBody(finding: Finding): string;
+/** Convert one finding into a proposed memory draft (with a conservative sensor when derivable). */
+declare function findingToDraft(finding: Finding, options?: DraftOptions): MemoryDraft;
+/** Convert a batch of findings into drafts, deduped within the batch and capped/filtered. */
+declare function draftsFromFindings(findings: Finding[], options?: DraftsOptions): MemoryDraft[];
+/** Drop drafts whose topic already exists in the corpus (cross-run dedup). */
+declare function filterNewDrafts(drafts: MemoryDraft[], existingTopics: Iterable<string>): MemoryDraft[];
+
+/**
+ * Gate signal-quality — is the inferential (anti-pattern) gate earning trust or crying wolf?
+ *
+ * Hivelore's anti-pattern gate is probabilistic and warmup-sensitive, so it is deliberately calibrated
+ * NOT to hard-block on weak matches. But a team needs to SEE whether the gate's signal is precise:
+ * are its catches turning out to be real (prevented mistakes, applied lessons) or noise (rejected by
+ * humans via `mem_feedback`)? This module turns the signals Hivelore already records — prevention events
+ * (by source) and per-memory rejection counts — into a precision indicator and an actionable tuning
+ * suggestion for `enforcement.antiPatternGate`. Pure: no I/O.
+ */
+
+interface GatePrecision {
+    /** Catches recorded by deterministic regex/command sensors. */
+    sensor_catches: number;
+    /** Catches recorded by the inferential anti-pattern gate. */
+    anti_pattern_catches: number;
+    /** Total "useful" outcomes (catches + human-applied lessons). */
+    useful: number;
+    /** Total human rejections (mem_feedback "not useful"). Proxy for false positives. */
+    rejections: number;
+    /** useful / (useful + rejections), 0..1. Null when there is no signal yet. */
+    precision: number | null;
+    /** A tuning recommendation for enforcement.antiPatternGate, or null when current looks right. */
+    suggestion: GateTuningSuggestion | null;
+}
+interface GateTuningSuggestion {
+    recommended: AntiPatternGate;
+    reason: string;
+}
+interface GatePrecisionMetricDelta {
+    baseline: number | null;
+    current: number | null;
+    delta: number | null;
+}
+interface GatePrecisionDelta {
+    precision: GatePrecisionMetricDelta;
+    rejections: GatePrecisionMetricDelta;
+    /** True when humans rejected more gate output than the baseline run. */
+    false_positives_increased: boolean;
+    /** True when precision is known on both sides and dropped. */
+    precision_regressed: boolean;
+    /** CI-friendly rollup: either more false positives or lower known precision. */
+    regressed: boolean;
+}
+/**
+ * Compute the gate's signal quality from prevention events + usage.
+ * @param currentGate the configured antiPatternGate, used to decide whether to suggest a change.
+ */
+declare function computeGatePrecision(events: PreventionEvent[], usage: UsageIndex, currentGate?: AntiPatternGate): GatePrecision;
+/**
+ * Suggest loosening the gate when it is noisy (low precision with real rejection volume), or
+ * tightening it when it is precise but currently soft. Returns null when current looks right or
+ * there isn't enough signal to act on.
+ */
+declare function suggestGate(precision: number | null, rejections: number, currentGate: AntiPatternGate): GateTuningSuggestion | null;
+/** Compare gate signal quality against a baseline for CI regression gates. Pure. */
+declare function compareGatePrecision(baseline: GatePrecision, current: GatePrecision): GatePrecisionDelta;
+
+interface DashboardOptions {
+    /** How many rows to include in each "top" list. Default 10. */
+    top?: number;
+    /** Dormancy window for impact scoring. Defaults to impact's own default. */
+    dormantDays?: number;
+    now?: Date;
+    /** Prevention event log (from `loadPreventionEvents`) — powers the trend + recurrence rollups. */
+    preventionEvents?: PreventionEvent[];
+    /** Configured anti-pattern gate — lets the gate-precision rollup suggest tightening/loosening. */
+    antiPatternGate?: AntiPatternGate;
+}
+interface ImpactRow {
+    id: string;
+    score: number;
+    tier: ImpactScore["tier"];
+    signals: string[];
+    prune_candidate: boolean;
+}
+interface SensorRow {
+    id: string;
+    severity: "warn" | "block";
+    last_fired: string;
+}
+interface DormantRow {
+    id: string;
+    last_read_at: string | null;
+    age_days: number;
+}
+interface PreventionRow {
+    id: string;
+    type: string;
+    prevented_count: number;
+    last_prevented_at: string | null;
+}
+interface DashboardReport {
+    generated_at: string;
+    inventory: {
+        /** Policy corpus size (excludes session_recap). */
+        total: number;
+        session_recaps: number;
+        active: number;
+        retired: number;
+        by_scope: Record<string, number>;
+        by_type: Record<string, number>;
+        by_status: Record<string, number>;
+    };
+    /** OUTCOME measurement: prevention events = times a memory's sensor/anti-pattern fired on a real
+     *  diff, intercepting a known mistake. Distinct from retrieval (reads) — demonstrated value. */
+    prevention: {
+        total_events: number;
+        memories_with_catches: number;
+        top: PreventionRow[];
+        /** Catch volume over time (from the prevention event log). */
+        trend: PreventionTrend;
+        /** Lessons re-introduced after capture (caught on >= 2 distinct days). */
+        recurrence: RecurrenceReport;
+    };
+    /** Inferential-gate signal quality: are catches real (useful) or noise (rejected)? + tuning hint. */
+    gate_precision: GatePrecision;
+    impact: ImpactSummary & {
+        top: ImpactRow[];
+    };
+    sensors: {
+        total: number;
+        warn: number;
+        block: number;
+        autogen: number;
+        fired: number;
+        recently_fired: SensorRow[];
+    };
+    health: {
+        stale: number;
+        retired: number;
+        /** Validated decision/gotcha/architecture memories with no anchor paths or symbols. */
+        anchorless: number;
+        /** Memories awaiting review (draft/proposed). */
+        pending: number;
+        prune_candidates: number;
+    };
+    decay: {
+        decay_days: number;
+        decaying: number;
+        top_dormant: DormantRow[];
+    };
+    corpus: {
+        /** Number of memory files (policy corpus, excludes session_recap). */
+        memory_files: number;
+        body_chars: number;
+        /** Rough token estimate (~chars/4) — how heavy the corpus is to inject. */
+        est_tokens: number;
+    };
+}
+/** Build the full observability rollup from the loaded corpus + usage index. Pure. */
+declare function buildDashboard(memories: LoadedMemory[], usage: UsageIndex, options?: DashboardOptions): DashboardReport;
+
+/**
+ * Failure-capture coverage — the gate behind Hivelore's "never silently fix the same mistake" loop.
+ *
+ * `hivelore observe` (the PostToolUse hook) appends an observation per tool call to
+ * `.ai/.cache/observations.jsonl`, tagging hard failures with `failure_hint: true`
+ * (non-zero Bash exit, `error TSxxxx`, ENOENT, …). Those failures are exactly the
+ * `mem_tried` candidates the harness wants captured — otherwise the next session repeats them.
+ *
+ * This module is the pure decision layer: given the failure observations and the corpus's
+ * `attempt`/`gotcha` memories, which failures look UNCAPTURED (no lesson recorded after them)?
+ * The CLI reads the files and turns the result into an `enforce finish` finding. No I/O here.
+ */
+interface FailureObservation {
+    /** ISO timestamp of the observation. */
+    ts: string;
+    /** Tool that failed (Bash / Edit / …). */
+    tool: string;
+    /** Short human-readable summary of what was attempted. */
+    summary: string;
+}
+interface UncapturedFailure {
+    ts: string;
+    tool: string;
+    summary: string;
+}
+interface FailureCoverageOptions {
+    /** Only consider failures newer than this many hours (avoid stale observations blocking forever). Default 24. */
+    windowHours?: number;
+    /** Collapse near-identical failures (same normalized summary) to one row. Default true. */
+    dedupe?: boolean;
+    now?: Date;
+}
+/**
+ * A failure is CAPTURED when an `attempt`/`gotcha` lesson was recorded at or after it
+ * (within the window) — the agent stopped and wrote the lesson down. Failures that pre-date
+ * every recent capture are uncaptured: the gate should nudge (or block) on those.
+ *
+ * @param failures     failure-tagged observations (any order)
+ * @param captureTimes ISO created_at of every attempt/gotcha memory in the corpus
+ */
+declare function findUncapturedFailures(failures: FailureObservation[], captureTimes: string[], options?: FailureCoverageOptions): UncapturedFailure[];
+
+/**
+ * Harness coverage-gap detection — "which churny files have NO team knowledge on them?".
+ *
+ * Hivelore's `eval` synthesizes cases from the memories that EXIST (does the corpus surface
+ * correctly?). It cannot tell you what knowledge is MISSING. This module answers the inverse,
+ * proactive question Fowler frames as an open challenge: of the files the team edits most, which
+ * carry no covering decision/convention/gotcha/architecture memory? Those are the blind spots
+ * where a confident agent is most likely to violate an unwritten rule.
+ *
+ * Pure: the caller supplies hot files (from git history / briefing-radar) and the loaded corpus.
+ */
+
+/** Where a file's "heat" came from: committed git churn, agent edits this/recent sessions, or both. */
+type HotFileSource = "git" | "agent" | "both";
+interface HotFile {
+    path: string;
+    /** Number of times the file changed in the lookback window (the "heat"). */
+    changes: number;
+    /** Provenance of the heat. Optional for back-compat with git-only callers. */
+    source?: HotFileSource;
+}
+interface CoverageGap {
+    path: string;
+    changes: number;
+    /** Provenance of the heat that made this file a blind spot. */
+    source?: HotFileSource;
+}
+interface CoverageOptions {
+    /** Only flag files with at least this many changes. Default 3. */
+    minChanges?: number;
+    /** Memory types that count as "covering" a file. Default decision/convention/gotcha/architecture. */
+    coveringTypes?: string[];
+    /** Cap on returned gaps. Default 20. */
+    limit?: number;
+}
+/**
+ * Build the set of path prefixes the corpus covers: every anchor path of a non-dead,
+ * non-recap covering memory. A file is covered if it equals, or sits under, one of them.
+ */
+declare function buildCoverageIndex(memories: LoadedMemory[], coveringTypes?: string[]): Set<string>;
+/** True when `file` equals or is nested under any covered path prefix. */
+declare function isCovered(file: string, coverage: Set<string>): boolean;
+/**
+ * Cross hot files with the coverage index → the uncovered, frequently-edited files.
+ * Highest heat first. These are the highest-value places to add a memory or sensor.
+ */
+declare function findCoverageGaps(hotFiles: HotFile[], memories: LoadedMemory[], options?: CoverageOptions): CoverageGap[];
+/**
+ * Tally a flat list of edited file paths into HotFiles — the agent-edit heat signal from the
+ * PostToolUse observation log (files agents actually touch), complementary to committed git churn.
+ * Pure: the caller reads/normalizes the observation paths.
+ */
+declare function tallyHotFiles(paths: string[], source?: HotFileSource): HotFile[];
+/**
+ * Merge two HotFile lists, summing heat per path. A file hot in both lists is tagged `both` so the
+ * report can show that agents AND git churn both point at the same uncovered file (the strongest gap).
+ */
+declare function mergeHotFiles(a: HotFile[], b: HotFile[]): HotFile[];
+
+interface EvalHistoryEntry {
+    /** ISO timestamp of the eval run. */
+    at: string;
+    /** Overall 0..100 score. */
+    score: number;
+    /** Optional component metrics for richer trend views. */
+    mean_recall?: number;
+    mrr?: number;
+    catch_rate?: number;
+    /** Optional version/commit the run was taken at. */
+    ref?: string;
+}
+declare function evalHistoryPath(paths: HaivePaths): string;
+/** Append one eval run to the history. Best-effort, creates the dir on demand. */
+declare function appendEvalHistory(paths: HaivePaths, entry: EvalHistoryEntry): Promise<void>;
+/** Read all eval runs (skips malformed lines). */
+declare function loadEvalHistory(paths: HaivePaths): Promise<EvalHistoryEntry[]>;
+interface EvalTrend {
+    /** Most recent score, or null when there is no history. */
+    latest: number | null;
+    /** Score before the latest, or null. */
+    previous: number | null;
+    /** latest − previous (positive = improving). */
+    delta: number | null;
+    /** Best score ever recorded. */
+    best: number | null;
+    /** Number of runs recorded. */
+    runs: number;
+    /** Last N scores oldest → newest for a sparkline. */
+    recent: number[];
+    /** True when the latest run dropped vs the previous one. */
+    regressed: boolean;
+}
+/** Pure trend over the history (chronological order is enforced internally). */
+declare function computeEvalTrend(entries: EvalHistoryEntry[], recentN?: number): EvalTrend;
+
+/**
+ * Contradiction resolution planning — turns "two memories conflict" into "do THIS".
+ *
+ * `conflict-candidates.ts` surfaces pairs (same topic with opposed status, or lexically near-
+ * duplicate). That's detection, not resolution — and Fowler lists incoherence-at-scale (a harness
+ * full of contradictory guides) as a core open challenge. This module decides, deterministically,
+ * which memory of a pair should WIN and which should be superseded (deprecated), so the CLI can
+ * apply it. Pure: no I/O, unit-tested.
+ *
+ * Decision order (strongest signal first):
+ *   1. status     — a `validated` memory beats a `rejected`/`deprecated`/`stale` one.
+ *   2. revision   — higher `revision_count` (more refined via topic-upsert) wins.
+ *   3. recency    — newer `created_at` wins (the team's latest word).
+ */
+
+interface ConflictResolution {
+    /** Memory id to keep authoritative. */
+    keep_id: string;
+    /** Memory id to deprecate (superseded). */
+    supersede_id: string;
+    /** Human-readable reason the winner was chosen. */
+    reason: string;
+    /** stale_reason to stamp on the superseded memory. */
+    stale_reason: string;
+}
+/** Compare two memories; returns the one that should WIN plus the reason. Pure. */
+declare function planConflictResolution(a: LoadedMemory, b: LoadedMemory): ConflictResolution;
+interface AppliedConflictResolution {
+    /** Updated frontmatter for the memory to keep (promoted). */
+    winner: MemoryFrontmatter;
+    /** Updated frontmatter for the memory to supersede (deprecated). */
+    loser: MemoryFrontmatter;
+    /** Topic the winner now carries — the consolidation target for future `mem_save` upserts. Null when neither carried one. */
+    topic: string | null;
+    /** True when the winner adopted the loser's topic because it had none. */
+    topic_adopted: boolean;
+}
+/**
+ * Turn a {@link ConflictResolution} plan into the two concrete frontmatter updates — the guided
+ * supersede the backlog called for, wired into topic-upsert/revision_count:
+ *   - loser  → deprecated, stamped with stale_reason + a related_ids link to the winner.
+ *   - winner → revision_count++ (it absorbed a contradiction), verified now, linked to the loser,
+ *     and it ADOPTS the loser's topic when it had none — so the next `mem_save` on this subject
+ *     upserts into the winner instead of spawning a third conflicting memory. An existing winner
+ *     topic is never overwritten. Pure: the caller persists both.
+ */
+declare function applyConflictResolution(winner: LoadedMemory, loser: LoadedMemory, plan: ConflictResolution, now?: Date): AppliedConflictResolution;
+
+/**
+ * Cold-start seeding from git history — the harness has value only once the corpus is populated,
+ * and a fresh repo starts empty (Fowler's "harnessability": greenfield is easy, legacy is hard).
+ *
+ * Reverts and fixups are the cheapest signal of a real, repo-specific mistake: a commit that had to
+ * be undone or hot-fixed encodes a lesson the team already paid for. This module parses a list of
+ * commits (the CLI runs `git log`) and proposes DRAFT `attempt` seeds — never validated, always
+ * human-reviewed. Pure: the caller does the git I/O and the memory writes.
+ */
+interface GitCommit {
+    sha: string;
+    subject: string;
+    /** Files touched by the commit (optional — improves anchoring). */
+    files?: string[];
+}
+interface SeedProposal {
+    /** Kebab-ish slug derived from the reverted subject. */
+    slug: string;
+    /** What was tried (the thing that had to be reverted/fixed). */
+    what: string;
+    /** Why it failed (inferred from the revert/fixup). */
+    why_failed: string;
+    /** Suggested anchor paths (from the commit's files). */
+    paths: string[];
+    /** The source commit, for provenance. */
+    source_sha: string;
+    /** Detected signal kind. */
+    kind: "revert" | "fixup" | "workaround";
+}
+/** True when a reverted/fixed subject is mechanical noise (merge/bump/deps/wip/format), not a lesson. */
+declare function isNoiseSubject(subject: string): boolean;
+/**
+ * Turn commits into seed proposals. A `Revert "X"` commit proposes an attempt about X; an obvious
+ * hotfix/fixup commit proposes an attempt about the fixed area. Deduped by slug. Pure.
+ */
+declare function proposeSeedsFromCommits(commits: GitCommit[], limit?: number): SeedProposal[];
+
+/**
+ * Pure stack-detection helpers for cold-start seeding.
+ *
+ * Multi-language: reads package.json deps (JS/TS), requirements.txt (Python),
+ * go.mod (Go), and pom.xml (Java/Spring) to produce the list of detected stacks.
+ * No I/O — the caller reads the files and passes contents in, making this fully testable.
+ */
+interface DetectStacksInput {
+    /** Merged deps from package.json (dependencies + devDependencies). */
+    packageJsonDeps?: Record<string, string>;
+    /** Raw text of requirements.txt (or any requirements file). */
+    requirementsTxt?: string;
+    /** Raw text of go.mod. */
+    goMod?: string;
+    /** Raw text of pom.xml. */
+    pomXml?: string;
+    /** Raw text of composer.json (PHP). */
+    composerJson?: string;
+    /** Raw text of Gemfile (Ruby). */
+    gemfile?: string;
+    /** True when at least one .csproj/.sln file is present (.NET). */
+    hasCsproj?: boolean;
+    /** True when a Dockerfile is present. */
+    hasDockerfile?: boolean;
+    /** True when turbo.json is present (Turborepo). */
+    hasTurboJson?: boolean;
+    /** True when nx.json is present (Nx). */
+    hasNxJson?: boolean;
+}
+type DetectableStack = "nestjs" | "nextjs" | "remix" | "react" | "express" | "fastify" | "prisma" | "drizzle" | "zustand" | "redux" | "reactquery" | "trpc" | "mongoose" | "graphql" | "vue" | "tailwind" | "vite" | "sveltekit" | "astro" | "typescript" | "monorepo" | "fastapi" | "django" | "flask" | "go" | "spring" | "laravel" | "rails" | "dotnet" | "docker";
+/**
+ * Detect stacks present in a project from the raw contents of its manifest files.
+ * Pure — no I/O. Pass what you have; omit what you don't.
+ */
+declare function detectStacksFromManifests(input: DetectStacksInput): DetectableStack[];
+
+interface MergeResult {
+    /** The chosen file content. */
+    content: string;
+    /** Which side won. */
+    winner: "ours" | "theirs";
+    /** Why (for logging). */
+    reason: string;
+}
+/**
+ * Resolve two versions of the same memory file. Returns the winning content and the rationale.
+ * Falls back to "ours" when either side can't be parsed (never throws — a merge driver must not).
+ */
+declare function mergeMemoryVersions(ours: string, theirs: string): MergeResult;
+
+/**
+ * Recap compaction — keep the auto-generated session recap from dominating the briefing head.
+ *
+ * The MCP server auto-saves a minimal recap on exit (goal = "Auto-captured session (N tool calls)",
+ * body = a raw tool-call/file dump). It's low signal, yet get_briefing shows the freshest recap's
+ * full body at the very top of every briefing. A human/post_task recap (with a real Discoveries
+ * section) is far richer. This module detects an auto recap and compresses it to its useful core
+ * (the Discoveries, if any) so it informs without crowding. Pure, unit-tested.
+ */
+/**
+ * True when a recap body looks auto-generated (vs. a human/post_task recap). Auto recaps come in a
+ * couple of shapes, all low-signal: the session-tracker's "Auto-captured session (N tool calls)" and
+ * the run-wrapper's "Edited N files across M tool calls". The common tell is a raw tool-call count.
+ */
+declare function isAutoRecap(body: string): boolean;
+/**
+ * Return a compact version of an auto recap body: a one-line header (the Goal line) plus the
+ * Discoveries section when it carries real content (e.g. detected failures). Non-auto recaps are
+ * returned unchanged.
+ */
+declare function compactAutoRecapBody(body: string, maxChars?: number): string;
+
+/** Filename of the ephemeral handoff at the repo root. */
+declare const HANDOFF_FILENAME = "NEXT.md";
+/** Absolute path to the handoff file for a given project root. */
+declare function handoffFilePath(root: string): string;
+interface SessionHandoffData {
+    /** One-line focus of the session that just ended. */
+    goal: string;
+    /** Short work summary (e.g. tool/file rollup) — optional. */
+    summary?: string;
+    /** Unresolved items the next session should pick up (failures, attempts, TODOs). */
+    openThreads?: string[];
+    /** Files touched during the session. */
+    filesTouched?: string[];
+    /** What should happen next, free text. */
+    nextSteps?: string;
+    /** Optional `git diff --stat` style block to show what is uncommitted. */
+    diffStat?: string;
+    /** Timestamp; defaults to now. */
+    at?: Date;
+}
+/**
+ * Build the markdown body of the ephemeral handoff. Pure — no I/O.
+ * Deliberately compact: focus + open threads + next steps are the load-bearing parts.
+ */
+declare function buildHandoffMarkdown(data: SessionHandoffData): string;
+/** Write (overwrite) the ephemeral handoff. Returns the file path. Best-effort caller should catch. */
+declare function writeSessionHandoff(root: string, data: SessionHandoffData): Promise<string>;
+/** Read the handoff body if present, else null. */
+declare function readSessionHandoff(root: string): Promise<string | null>;
+/** Age of the handoff file in milliseconds (by mtime), or null if it does not exist. */
+declare function handoffAgeMs(root: string, now?: Date): Promise<number | null>;
+
+type MemoryPriority = "must_read" | "useful" | "background";
+/**
+ * Normalized priority evidence. A caller fills only the signals it can compute; unknown ones default
+ * to false (see {@link DEFAULT_PRIORITY_SIGNALS}). The MCP path has semantic scores; the CLI path has
+ * lexical scores — both reduce to these booleans.
+ */
+interface PrioritySignals {
+    /** Memory type (attempt, gotcha, skill, decision, …). */
+    type: string;
+    /** Memory tags — used for the stack-pack / env-workaround down-rank. */
+    tags: string[];
+    /** The memory demands explicit human approval — always surface first. */
+    requiresHumanApproval: boolean;
+    /** Anchored to a file the agent is editing. */
+    directAnchor: boolean;
+    /** Anchored to a symbol the agent requested. */
+    directSymbol: boolean;
+    /** Exact/literal task match (semantic match_quality "exact", or an exact lexical task hit). */
+    exactTaskMatch: boolean;
+    /** Strong semantic relevance (cosine ≥ 0.65). CLI has no embeddings → passes false. */
+    strongSemantic: boolean;
+    /** Useful-level relevance: semantic ≥ 0.35, a partial task hit, or a high lexical score. */
+    usefulSemantic: boolean;
+    /** Matched an inferred module or domain from the touched files. */
+    moduleOrDomainMatch: boolean;
+    /** A memory tag matched a task token. */
+    tagTaskMatch: boolean;
+}
+declare const DEFAULT_PRIORITY_SIGNALS: PrioritySignals;
+/** Convenience: build a full signal set from a partial one. */
+declare function prioritySignals(partial: Partial<PrioritySignals>): PrioritySignals;
+/**
+ * Classify a memory's briefing priority from its signals. Order matters:
+ *   1. must_read — human-approval gates, direct anchor/symbol matches, and exact/strong hits on
+ *      negative (attempt) or skill memories: the things an agent must not miss.
+ *   2. background (down-rank) — generic stack-pack seeds and local dev-environment workarounds never
+ *      claim `useful` on a semantic/tag match alone; they'd crowd out repo-specific knowledge. (A
+ *      direct anchor already promoted them to must_read above, so genuinely-relevant ones still rank.)
+ *   3. useful — skills, module/domain matches, exact hits, and useful-level relevance.
+ *   4. background — everything else.
+ */
+declare function classifyMemoryPriority(signals: PrioritySignals): MemoryPriority;
+declare function priorityRank(priority: MemoryPriority): number;
+
+/**
+ * Native bridge generator — produces agent-harness-specific config files
+ * from the Hivelore corpus (validated memories + block sensors).
+ *
+ * One pure formatter per target; no I/O.
+ * The CLI command (cli/commands/bridges.ts) handles file writes and
+ * idempotent marker-based updates.
+ *
+ * Exposed for Lot A (init.ts): call generateBridges() from hivelore init
+ * to seed all bridges at initialisation time.
+ */
+
+type BridgeTarget = "claude" | "cursor" | "cline" | "windsurf" | "continue" | "cody" | "zed" | "roo" | "gemini" | "aider" | "agents" | "copilot";
+/** Canonical relative path from project root for each target. */
+declare const BRIDGE_TARGET_PATH: Record<BridgeTarget, string>;
+declare const BRIDGE_TARGETS: BridgeTarget[];
+/**
+ * Condensed sensor shape for bridge injection.
+ * Callers extract this from Memory.frontmatter.sensor — no sensor-module import needed.
+ */
+interface BridgeSensor {
+    id: string;
+    severity: "block" | "warn";
+    message: string;
+    /** Regex pattern, present when sensor.kind === "regex". */
+    pattern?: string;
+    /** Scoped file paths (sensor.paths ?? anchor.paths). */
+    paths: string[];
+}
+interface BridgeMemoryEntry {
+    id: string;
+    scope: string;
+    type: string;
+    summary: string;
+    /** Anchor paths the memory applies to (for path-scoped display / Cursor globs). */
+    paths: string[];
+}
+interface GenerateBridgesOptions {
+    /** Max memories to inject per bridge (default: 8). */
+    maxMemories?: number;
+    /** Restrict generation to these targets. Defaults to all BRIDGE_TARGETS. */
+    targets?: BridgeTarget[];
+}
+interface BridgeFileOutput {
+    target: BridgeTarget;
+    /** Relative path from project root. */
+    path: string;
+    content: string;
+}
+declare const BRIDGE_MARKERS: {
+    readonly bridgeStart: "<!-- haive:bridge-start -->";
+    readonly bridgeEnd: "<!-- haive:bridge-end -->";
+    readonly memoriesStart: "<!-- haive:memories-start -->";
+    readonly memoriesEnd: "<!-- haive:memories-end -->";
+    readonly sensorsStart: "<!-- haive:sensors-start -->";
+    readonly sensorsEnd: "<!-- haive:sensors-end -->";
+};
+/** First meaningful line of a memory body, condensed for bridge display. */
+declare function bridgeMemorySummary(body: string): string;
+/**
+ * Filter and rank memories + sensors for bridge injection.
+ * Pure — callers load data; this function does not read files.
+ */
+declare function prepareBridgeData(memories: Memory[], sensors: BridgeSensor[], opts?: Pick<GenerateBridgesOptions, "maxMemories">): {
+    topMemories: BridgeMemoryEntry[];
+    blockSensors: BridgeSensor[];
+};
+/**
+ * Generate bridge file content for the requested targets.
+ *
+ * Pure: accepts loaded memories + sensors, returns file content strings.
+ * The CLI command handles I/O and idempotent marker-based updates.
+ *
+ * **Lot A integration point**: call this from `hivelore init` to seed bridges at initialisation.
+ * Signature is intentionally stable — init.ts should call:
+ *   `generateBridges(memories, sensors, { targets: BRIDGE_TARGETS })`
+ */
+declare function generateBridges(memories: Memory[], sensors: BridgeSensor[], opts?: GenerateBridgesOptions): BridgeFileOutput[];
+
+export { AUTOPILOT_DEFAULTS, type Activation, type ActivationContext, ActivationSchema, type Anchor, AnchorSchema, type AntiPatternGate, type AppliedConflictResolution, type AstExport, type AutoPromoteRule, BRIDGE_MARKERS, BRIDGE_TARGETS, BRIDGE_TARGET_PATH, BRIEFING_MARKER_TTL_MS, BRIEFING_PRESET_DEFAULTS, type BootstrapAssessment, type BootstrapGap, type BootstrapGate, type BootstrapMetrics, type BootstrapState, type BootstrapStateInput, type BreakingChange, type BridgeFileOutput, type BridgeMemoryEntry, type BridgeSensor, type BridgeTarget, type BriefingBudgetNumbers, type BriefingBudgetPreset, type BriefingMarker, type BriefingProofLineOptions, type BudgetPart, type BudgetSlice, type BuildCodeMapOptions, CHARS_PER_TOKEN, CODE_MAP_FILE, CODE_STOPWORDS, CONFIG_FILE, type CaughtForYouOptions, type CaughtForYouRow, type CaughtForYouSummary, type CodeExport, type CodeExportKind, type CodeFileEntry, type CodeMap, type CodeMapQueryOptions, type CollectTimelineOpts, type CommandSensorSpec, type ConfidenceLevel, type ConfidenceThresholds, type ConflictCandidatePair, type ConflictCandidatesOpts, type ConflictResolution, type ContractDiffResult, type ContractFile, type ContractSnapshot, type CoverageGap, type CoverageOptions, CrossRepoProvenanceSchema, type CrossRepoReport, type CrossRepoSource, DECAY_DAYS, DEFAULT_AUTO_PROMOTE_RULE, DEFAULT_BRIEFING_EXCLUDE_TAGS, DEFAULT_CONFIDENCE_THRESHOLDS, DEFAULT_CONFIG, DEFAULT_DORMANT_DAYS, DEFAULT_PRIORITY_SIGNALS, type DashboardOptions, type DashboardReport, type DepChange, type DepTrackResult, type DependencySnapshot, type DetectStacksInput, type DetectableStack, type DocFrequency, type DormantRow, type DraftOptions, type DraftsOptions, ENV_WORKAROUND_TAGS, type EvalDelta, type EvalHistoryEntry, type EvalReport, type EvalSpec, type EvalTrend, type FailureCoverageOptions, type FailureObservation, type FeedbackAdjustment, type FeedbackAdjustmentAction, type FeedbackAdjustmentOptions, type Finding, type FindingFormat, type FindingSeverity, GUESSABLE_THRESHOLD, type GatePrecision, type GatePrecisionDelta, type GatePrecisionMetricDelta, type GateTuningSuggestion, type GenerateBridgesOptions, type GitCommit, HAIVE_DIR, HAIVE_OWNED_FILES, HANDOFF_FILENAME, type HaiveConfig, type HaivePaths, type HotFile, type HotFileSource, type ImpactOptions, type ImpactRow, type ImpactScore, type ImpactSummary, type ImpactTier, type LexicalRankResult, type LoadedMemory, MEMORIES_DIR, MIN_WORD_LEN, type Memory, type MemoryDraft, type MemoryFrontmatter, MemoryFrontmatterSchema, type MemoryPriority, type MemoryScope, MemoryScopeSchema, type MemoryStatus, MemoryStatusSchema, type MemoryType, MemoryTypeSchema, type MemoryUsage, type MergeResult, type MetricDelta, PREVENTION_DEBOUNCE_MS, PROJECT_CONTEXT_FILE, PROJECT_CONTEXT_THROTTLE_MS, type PreventionEvent, type PreventionRow, type PreventionSource, type PreventionTrend, type PrioritySignals, type ProposedSensorVerdict, RUNTIME_JOURNAL_FILENAME, type RecurrenceReport, type RecurrenceRow, type ResolveProjectInfo, type RetirementSignal, type RetrievalAggregate, type RetrievalCase, type RetrievalCaseResult, type RuntimeJournalEntry, SEED_QUALITY_FLOOR, SENSOR_ABSENT_LOOKBACK, SENSOR_ABSENT_WINDOW, SESSION_RECAP_TTL_MS, STACK_PACK_TAG, type SeedProposal, type SelfEvalOptions, type Sensor, type SensorAggregate, type SensorCase, type SensorCaseResult, type SensorHit, type SensorRow, SensorSchema, type SensorSeed, type SensorSelfCheck, type SensorSuggestionOptions, type SensorTarget, type SessionHandoffData, type SkillActivation, type TimelineEntry, type TopicStatusPair, type TruncateOptions, type TruncateResult, USAGE_FILE, USAGE_LOG_DIR, USAGE_LOG_FILE, type UncapturedFailure, type UsageAggregate, type UsageEvent, type UsageIndex, type VerifyOptions, type VerifyResult, addedLinesFromDiff, aggregateRetrieval, aggregateSensors, aggregateUsage, allocateBudget, antiPatternGateParams, appendEvalHistory, appendPreventionEvent, appendRuntimeJournalEntry, appendUsageEvent, applyConflictResolution, applyFeedbackAdjustment, assessBootstrapState, bridgeMemorySummary, briefingMarkerPath, briefingMarkersDir, briefingProofLine, buildCodeMap, buildCoverageIndex, buildDashboard, buildDocFrequency, buildFrontmatter, buildHandoffMarkdown, buildReport, bumpRead, classifyMemoryPriority, codeMapPath, collectTimelineEntries, compactAutoRecapBody, compareEvalReports, compareGatePrecision, compareImpact, compileRegexSensor, componentOf, computeEvalTrend, computeGatePrecision, computeImpact, computePreventionTrend, computeRecurrence, configPath, contractLockPath, countSourceFilesOnDisk, deriveConfidence, detectStacksFromManifests, diffContract, diffHasDistinctiveOverlap, distinctiveCap, draftsFromFindings, emptyUsage, emptyUsageIndex, enforcementDir, estimateTokens, evalHistoryPath, evaluateSkillActivation, extractActionsBriefBody, extractReferencedPaths, extractSensorExamples, extractSnippet, filterNewDrafts, findCoverageGaps, findLexicalConflictPairs, findProjectRoot, findTopicStatusConflictPairs, findUncapturedFailures, findingBody, findingToDraft, firstMemoryOneLine, generateBridges, getUsage, globToRegExp, handoffAgeMs, handoffFilePath, hasRecentBriefingMarker, hashProjectContext, inferModulesFromPaths, isAutoPromoteEligible, isAutoRecap, isCovered, isDecaying, isDistinctiveToken, isEnvWorkaroundMemory, isFreshIsoDate, isGlobPath, isLikelyGuessable, isNoiseSubject, isRetiredMemory, isSensorScannablePath, isSkill, isSkillSuppressed, isStackPackSeed, isStylisticRule, isTemplateProjectContext, judgeProposedSensor, listMarkdownFilesRecursive, literalMatchesAllTokens, literalMatchesAnyToken, loadCodeMap, loadConfig, loadConfigSync, loadEvalHistory, loadMemoriesFromDir, loadMemory, loadPreventionEvents, loadUsageIndex, looksLikeGenericAdvice, meetsSeedQualityFloor, memoryFilePath, memoryHasExcludedTag, memoryMatchesAnchorPaths, mergeHotFiles, mergeMemoryVersions, moduleNameOf, newMemoryId, normalizeFindingSeverity, normalizeSessionId, overallScore, parseEslintJson, parseFileAst, parseFindings, parseMemory, parseNpmAudit, parseSarif, parseSince, parseSonar, pathsOverlap, pickSnippetNeedle, planConflictResolution, prepareBridgeData, preventionLogPath, priorityRank, prioritySignals, projectContextRecentlyEmitted, proposeSeedsFromCommits, pullCrossRepoSources, queryCodeMap, rankMemoriesLexical, readRecentBriefingMarker, readRuntimeJournalTail, readSessionHandoff, readUsageEvents, recommendFeedbackAdjustment, recordApplied, recordPrevention, recordPreventionHits, recordProjectContextEmission, recordRejection, relPathFrom, renderBootstrapChecklist, renderCaughtForYou, resolveBriefingBudget, resolveHaivePaths, resolveManifestFiles, resolveProjectInfo, retirementSignal, runRegexSensor, runSensors, runtimeJournalPath, saveCodeMap, saveConfig, saveUsageIndex, scannableSensorTargets, scoreRetrievalCase, scoreSensorCase, selectCommandSensors, sensorAppliesToPath, sensorPatternBrittleness, sensorSelfCheck, sensorTargetsFromDiff, serializeMemory, snapshotContract, specificityScore, stripPrivate, suggestGate, suggestSensorFromMemory, suggestSensorSeed, suggestTopicKey, summarizeCaughtForYou, summarizeImpact, synthesizeSelfEvalCases, tallyHotFiles, titleFromBody, tokenizeQuery, tokenizeWords, trackDependencies, trackReads, truncateToTokens, usageLogPath, usageLogSize, usagePath, verifyAnchor, watchContracts, writeBriefingMarker, writeSessionHandoff };