@hivelore/core 0.35.0 → 0.36.0

package/dist/index.d.ts

@@ -49,12 +49,26 @@ declare const SensorSchema: z.ZodObject<{
     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;
+    /**
+     * Optional provenance: the real incident this sensor guards against — a ticket ref, a prod
+     * incident id, a date ("prod #442", "INC-1029", "2026-06 refund overcharge"). This is the
+     * behaviour-harness link a plain test can't carry: it turns "a test failed" into "this reproduces
+     * the incident the test exists to prevent". Surfaced in the block message and the prevention receipt.
+     */
+    incident: z.ZodOptional<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>>;
+    /**
+     * ISO timestamp of the last manual `sensors promote` back to block. Health assessment ignores
+     * ledger evaluations older than this — without it, a promoted sensor whose oracle was FIXED is
+     * re-quarantined on the next commit for up to 30 days (the stale flaps are still in the window),
+     * making the promotion promised by the quarantine note a no-op.
+     */
+    promoted_at: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     message: string;
     paths: string[];
@@ -67,6 +81,8 @@ declare const SensorSchema: z.ZodObject<{
     flags?: string | undefined;
     command?: string | undefined;
     timeout_ms?: number | undefined;
+    incident?: string | undefined;
+    promoted_at?: string | undefined;
 }, {
     message: string;
     paths?: string[] | undefined;
@@ -76,9 +92,11 @@ declare const SensorSchema: z.ZodObject<{
     flags?: string | undefined;
     command?: string | undefined;
     timeout_ms?: number | undefined;
+    incident?: string | undefined;
     severity?: "warn" | "block" | undefined;
     autogen?: boolean | undefined;
     last_fired?: string | null | undefined;
+    promoted_at?: string | undefined;
 }>;
 /**
  * Progressive-disclosure activation triggers for a `skill` memory.
@@ -148,12 +166,26 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
         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;
+        /**
+         * Optional provenance: the real incident this sensor guards against — a ticket ref, a prod
+         * incident id, a date ("prod #442", "INC-1029", "2026-06 refund overcharge"). This is the
+         * behaviour-harness link a plain test can't carry: it turns "a test failed" into "this reproduces
+         * the incident the test exists to prevent". Surfaced in the block message and the prevention receipt.
+         */
+        incident: z.ZodOptional<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>>;
+        /**
+         * ISO timestamp of the last manual `sensors promote` back to block. Health assessment ignores
+         * ledger evaluations older than this — without it, a promoted sensor whose oracle was FIXED is
+         * re-quarantined on the next commit for up to 30 days (the stale flaps are still in the window),
+         * making the promotion promised by the quarantine note a no-op.
+         */
+        promoted_at: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         message: string;
         paths: string[];
@@ -166,6 +198,8 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
         flags?: string | undefined;
         command?: string | undefined;
         timeout_ms?: number | undefined;
+        incident?: string | undefined;
+        promoted_at?: string | undefined;
     }, {
         message: string;
         paths?: string[] | undefined;
@@ -175,9 +209,11 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
         flags?: string | undefined;
         command?: string | undefined;
         timeout_ms?: number | undefined;
+        incident?: string | undefined;
         severity?: "warn" | "block" | undefined;
         autogen?: boolean | undefined;
         last_fired?: string | null | undefined;
+        promoted_at?: string | undefined;
     }>>;
     /** Optional progressive-disclosure triggers — only meaningful for `type: skill`. */
     activation: z.ZodOptional<z.ZodObject<{
@@ -257,6 +293,8 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
         flags?: string | undefined;
         command?: string | undefined;
         timeout_ms?: number | undefined;
+        incident?: string | undefined;
+        promoted_at?: string | undefined;
     } | undefined;
     activation?: {
         keywords: string[];
@@ -287,9 +325,11 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
         flags?: string | undefined;
         command?: string | undefined;
         timeout_ms?: number | undefined;
+        incident?: string | undefined;
         severity?: "warn" | "block" | undefined;
         autogen?: boolean | undefined;
         last_fired?: string | null | undefined;
+        promoted_at?: string | undefined;
     } | undefined;
     activation?: {
         keywords?: string[] | undefined;
@@ -341,6 +381,8 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
         flags?: string | undefined;
         command?: string | undefined;
         timeout_ms?: number | undefined;
+        incident?: string | undefined;
+        promoted_at?: string | undefined;
     } | undefined;
     activation?: {
         keywords: string[];
@@ -371,9 +413,11 @@ declare const MemoryFrontmatterSchema: z.ZodEffects<z.ZodObject<{
         flags?: string | undefined;
         command?: string | undefined;
         timeout_ms?: number | undefined;
+        incident?: string | undefined;
         severity?: "warn" | "block" | undefined;
         autogen?: boolean | undefined;
         last_fired?: string | null | undefined;
+        promoted_at?: string | undefined;
     } | undefined;
     activation?: {
         keywords?: string[] | undefined;
@@ -683,6 +727,8 @@ interface PreventionReceiptRow {
     stage: "pre-commit" | "pre-push" | "ci" | "manual" | null;
     exit_code: number | null;
     message: string | null;
+    /** Incident provenance from the sensor frontmatter — the behaviour-harness link, when present. */
+    incident: string | null;
 }
 interface PreventionReceipt {
     generated_at: string;
@@ -700,6 +746,19 @@ declare function buildPreventionReceipt(events: PreventionEvent[], memories: Loa
     now?: Date;
 }): PreventionReceipt;
 declare function renderPreventionReceipt(receipt: PreventionReceipt): string;
+/**
+ * Attribution footer for shared receipts — the growth loop. Every time a team pastes proof of
+ * prevented mistakes into Slack or a PR, the artifact names the tool that produced it. Kept as one
+ * constant so the CLI `--share` output and the CI PR comment carry identical wording.
+ */
+declare const HIVELORE_ATTRIBUTION = "\uD83D\uDEE1\uFE0F Generated by [Hivelore](https://github.com/Doucs91/hivelore) \u2014 the deterministic policy gate for agent-written code.";
+/**
+ * Markdown rendering of the receipt for `hivelore stats receipt --share` and the CI PR comment —
+ * ready to paste into Slack or a review. Includes incident provenance and the attribution footer.
+ * An empty window is NOT a dead end: it renders a forward CTA (turn an incident into a guardrail),
+ * so the receipt is useful on day one, before any prevention has been recorded.
+ */
+declare function renderPreventionReceiptShare(receipt: PreventionReceipt): string;
 /** Read all catch events (skips malformed lines). */
 declare function loadPreventionEvents(paths: HaivePaths): Promise<PreventionEvent[]>;
 interface PreventionTrend {
@@ -1907,11 +1966,19 @@ interface CommandSensorSpec {
     severity: Sensor["severity"];
     /** LLM-facing self-correction message carried from the sensor. */
     message: string;
+    /** Optional incident provenance carried from the sensor (ticket/prod ref this test guards). */
+    incident?: string;
     /** Anchor/scoped paths this sensor cares about (for reporting). */
     paths: string[];
     /** Max runtime in ms (executor default applies when unset). */
     timeout_ms?: number;
 }
+/**
+ * Render the incident-provenance suffix appended to a fired sensor's message. Empty when the sensor
+ * carries no `incident` — so the behaviour-harness link ("guards the incident this test exists for")
+ * shows up wherever a sensor speaks, without every call site re-deriving the copy.
+ */
+declare function incidentSuffix(incident?: string): 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.
@@ -2036,7 +2103,22 @@ declare function computeScopeHash(root: string, scopedFiles: string[]): string;
  * Deterministic health assessment. A flap is an adjacent fired/silent outcome change for the same
  * memory and identical scope hash inside the 30-day window. `unrunnable` rows never participate.
  */
-declare function assessSensorHealth(evaluations: SensorEvaluation[], now?: Date): SensorHealth[];
+declare function assessSensorHealth(evaluations: SensorEvaluation[], now?: Date, opts?: {
+    /**
+     * memory_id → ISO timestamp of the sensor's last manual promotion back to block
+     * (sensor.promoted_at). Evaluations at or before it are ignored: the promotion is the
+     * human's assertion that the oracle was fixed, so pre-promotion flaps must not
+     * re-quarantine it.
+     */
+    promotedAt?: ReadonlyMap<string, string>;
+}): SensorHealth[];
+/** Build the promoted_at map for {@link assessSensorHealth} from memory frontmatters. */
+declare function sensorPromotedAtMap(frontmatters: Iterable<{
+    id: string;
+    sensor?: {
+        promoted_at?: string;
+    } | null;
+}>): Map<string, string>;
 declare function quarantineNote(at: string, flapCount: number): string;
 /** Add or replace the single quarantine note. */
 declare function withQuarantineNote(body: string, at: string, flapCount: number): string;
@@ -2671,7 +2753,15 @@ declare function revertedShaFromCommit(commit: GitCommit): string | null;
 declare function existingGateMissShas(memories: LoadedMemory[]): Set<string>;
 declare function gatePassedShas(evaluations: SensorEvaluation[]): Set<string>;
 /** Build proposed, never-validated lessons from incremental revert/hotfix signals. */
-declare function proposeGateMissDrafts(commits: GitCommit[], existingRevertedShas: Set<string>, passedShas: Set<string>): GateMissProposal[];
+declare function proposeGateMissDrafts(commits: GitCommit[], existingRevertedShas: Set<string>, passedShas: Set<string>, opts?: {
+    /**
+     * Returns true when a repo-relative path still exists on disk. Anchor candidates come from
+     * the REVERT commit's file list — files the revert often just deleted. Anchoring a draft to
+     * a deleted path makes the very next `sync` mark it stale, so the learning loop eats its own
+     * drafts before anyone reviews them. When omitted, paths are kept (pure callers/tests).
+     */
+    pathExists?: (rel: string) => boolean;
+}): GateMissProposal[];
 
 /**
  * Pure stack-detection helpers for cold-start seeding.
@@ -2924,4 +3014,4 @@ interface AgentContext {
 }
 declare function detectAgentContext(env?: Record<string, string | undefined>): AgentContext;
 
-export { AUTOPILOT_DEFAULTS, type Activation, type ActivationContext, ActivationSchema, type AgentContext, 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_DEFAULT_EXCLUDE, CODE_MAP_DEFAULT_INCLUDE, 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 GateMissProposal, type GatePrecision, type GatePrecisionDelta, type GatePrecisionMetricDelta, type GateTuningSuggestion, type GenerateBridgesOptions, type GitCommit, type GitWatchPlan, type GitWatchState, 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 InvalidMemoryFile, 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 PreventionEventDetail, type PreventionReceipt, type PreventionReceiptRow, 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 SensorEvaluation, type SensorEvaluationOutcome, type SensorEvaluationStage, type SensorFlap, type SensorHealth, 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, appendSensorEvaluations, appendUsageEvent, applyConflictResolution, applyFeedbackAdjustment, assessBootstrapState, assessSensorHealth, bridgeMemorySummary, briefingMarkerPath, briefingMarkersDir, briefingProofLine, buildCodeMap, buildCoverageIndex, buildDashboard, buildDocFrequency, buildFrontmatter, buildHandoffMarkdown, buildPreventionReceipt, buildReport, bumpRead, classifyMemoryPriority, codeMapPath, collectTimelineEntries, compactAutoRecapBody, compareEvalReports, compareGatePrecision, compareImpact, compileRegexSensor, componentOf, computeEvalTrend, computeGatePrecision, computeImpact, computePreventionTrend, computeRecurrence, computeScopeHash, configPath, contractLockPath, countSourceFilesOnDisk, deriveConfidence, detectAgentContext, detectStacksFromManifests, diffContract, diffHasDistinctiveOverlap, distinctiveCap, draftsFromFindings, emptyUsage, emptyUsageIndex, enforcementDir, estimateTokens, evalHistoryPath, evaluateSkillActivation, existingGateMissShas, extractActionsBriefBody, extractReferencedPaths, extractSensorExamples, extractSnippet, filterNewDrafts, findCoverageGaps, findLexicalConflictPairs, findProjectRoot, findTopicStatusConflictPairs, findUncapturedFailures, findingBody, findingToDraft, firstMemoryOneLine, gatePassedShas, 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, loadMemoriesFromDirDetailed, loadMemory, loadPreventionEvents, loadSensorLedger, loadUsageIndex, looksLikeGenericAdvice, meetsSeedQualityFloor, memoryFilePath, memoryHasExcludedTag, memoryMatchesAnchorPaths, mergeHotFiles, mergeMemoryVersions, moduleNameOf, newMemoryId, normalizeFindingSeverity, normalizeSessionId, overallScore, parseEslintJson, parseFileAst, parseFindings, parseMemory, parseNpmAudit, parseSarif, parseSince, parseSonar, pathsOverlap, pickSnippetNeedle, planConflictResolution, planGitWatch, prepareBridgeData, preventionLogPath, priorityRank, prioritySignals, projectContextRecentlyEmitted, proposeGateMissDrafts, proposeSeedsFromCommits, pullCrossRepoSources, quarantineNote, queryCodeMap, rankMemoriesLexical, readRecentBriefingMarker, readRuntimeJournalTail, readSessionHandoff, readUsageEvents, recommendFeedbackAdjustment, recordApplied, recordPrevention, recordPreventionHits, recordProjectContextEmission, recordRejection, relPathFrom, renderBootstrapChecklist, renderCaughtForYou, renderPreventionReceipt, resolveBriefingBudget, resolveHaivePaths, resolveManifestFiles, resolveProjectInfo, retirementSignal, revertedShaFromCommit, runRegexSensor, runSensors, runtimeJournalPath, saveCodeMap, saveConfig, saveUsageIndex, scannableSensorTargets, scoreRetrievalCase, scoreSensorCase, selectCommandSensors, sensorAppliesToPath, sensorLedgerPath, 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, withQuarantineNote, withoutQuarantineNote, writeBriefingMarker, writeSessionHandoff };
+export { AUTOPILOT_DEFAULTS, type Activation, type ActivationContext, ActivationSchema, type AgentContext, 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_DEFAULT_EXCLUDE, CODE_MAP_DEFAULT_INCLUDE, 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 GateMissProposal, type GatePrecision, type GatePrecisionDelta, type GatePrecisionMetricDelta, type GateTuningSuggestion, type GenerateBridgesOptions, type GitCommit, type GitWatchPlan, type GitWatchState, HAIVE_DIR, HAIVE_OWNED_FILES, HANDOFF_FILENAME, HIVELORE_ATTRIBUTION, type HaiveConfig, type HaivePaths, type HotFile, type HotFileSource, type ImpactOptions, type ImpactRow, type ImpactScore, type ImpactSummary, type ImpactTier, type InvalidMemoryFile, 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 PreventionEventDetail, type PreventionReceipt, type PreventionReceiptRow, 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 SensorEvaluation, type SensorEvaluationOutcome, type SensorEvaluationStage, type SensorFlap, type SensorHealth, 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, appendSensorEvaluations, appendUsageEvent, applyConflictResolution, applyFeedbackAdjustment, assessBootstrapState, assessSensorHealth, bridgeMemorySummary, briefingMarkerPath, briefingMarkersDir, briefingProofLine, buildCodeMap, buildCoverageIndex, buildDashboard, buildDocFrequency, buildFrontmatter, buildHandoffMarkdown, buildPreventionReceipt, buildReport, bumpRead, classifyMemoryPriority, codeMapPath, collectTimelineEntries, compactAutoRecapBody, compareEvalReports, compareGatePrecision, compareImpact, compileRegexSensor, componentOf, computeEvalTrend, computeGatePrecision, computeImpact, computePreventionTrend, computeRecurrence, computeScopeHash, configPath, contractLockPath, countSourceFilesOnDisk, deriveConfidence, detectAgentContext, detectStacksFromManifests, diffContract, diffHasDistinctiveOverlap, distinctiveCap, draftsFromFindings, emptyUsage, emptyUsageIndex, enforcementDir, estimateTokens, evalHistoryPath, evaluateSkillActivation, existingGateMissShas, extractActionsBriefBody, extractReferencedPaths, extractSensorExamples, extractSnippet, filterNewDrafts, findCoverageGaps, findLexicalConflictPairs, findProjectRoot, findTopicStatusConflictPairs, findUncapturedFailures, findingBody, findingToDraft, firstMemoryOneLine, gatePassedShas, generateBridges, getUsage, globToRegExp, handoffAgeMs, handoffFilePath, hasRecentBriefingMarker, hashProjectContext, incidentSuffix, 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, loadMemoriesFromDirDetailed, loadMemory, loadPreventionEvents, loadSensorLedger, loadUsageIndex, looksLikeGenericAdvice, meetsSeedQualityFloor, memoryFilePath, memoryHasExcludedTag, memoryMatchesAnchorPaths, mergeHotFiles, mergeMemoryVersions, moduleNameOf, newMemoryId, normalizeFindingSeverity, normalizeSessionId, overallScore, parseEslintJson, parseFileAst, parseFindings, parseMemory, parseNpmAudit, parseSarif, parseSince, parseSonar, pathsOverlap, pickSnippetNeedle, planConflictResolution, planGitWatch, prepareBridgeData, preventionLogPath, priorityRank, prioritySignals, projectContextRecentlyEmitted, proposeGateMissDrafts, proposeSeedsFromCommits, pullCrossRepoSources, quarantineNote, queryCodeMap, rankMemoriesLexical, readRecentBriefingMarker, readRuntimeJournalTail, readSessionHandoff, readUsageEvents, recommendFeedbackAdjustment, recordApplied, recordPrevention, recordPreventionHits, recordProjectContextEmission, recordRejection, relPathFrom, renderBootstrapChecklist, renderCaughtForYou, renderPreventionReceipt, renderPreventionReceiptShare, resolveBriefingBudget, resolveHaivePaths, resolveManifestFiles, resolveProjectInfo, retirementSignal, revertedShaFromCommit, runRegexSensor, runSensors, runtimeJournalPath, saveCodeMap, saveConfig, saveUsageIndex, scannableSensorTargets, scoreRetrievalCase, scoreSensorCase, selectCommandSensors, sensorAppliesToPath, sensorLedgerPath, sensorPatternBrittleness, sensorPromotedAtMap, 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, withQuarantineNote, withoutQuarantineNote, writeBriefingMarker, writeSessionHandoff };

package/dist/index.js

@@ -49,12 +49,26 @@ var SensorSchema = z.object({
   paths: z.array(z.string()).default([]),
   /** LLM-facing self-correction message: what was done wrong and what to do instead. */
   message: z.string().min(1),
+  /**
+   * Optional provenance: the real incident this sensor guards against — a ticket ref, a prod
+   * incident id, a date ("prod #442", "INC-1029", "2026-06 refund overcharge"). This is the
+   * behaviour-harness link a plain test can't carry: it turns "a test failed" into "this reproduces
+   * the incident the test exists to prevent". Surfaced in the block message and the prevention receipt.
+   */
+  incident: z.string().optional(),
   /** `warn` surfaces in review; `block` can hard-block the commit (only when the gate opts in). */
   severity: z.enum(["warn", "block"]).default("warn"),
   /** True when Hivelore generated this sensor automatically (vs. hand-authored). */
   autogen: z.boolean().default(false),
   /** ISO timestamp of the last time this sensor matched a diff. */
-  last_fired: z.string().nullable().default(null)
+  last_fired: z.string().nullable().default(null),
+  /**
+   * ISO timestamp of the last manual `sensors promote` back to block. Health assessment ignores
+   * ledger evaluations older than this — without it, a promoted sensor whose oracle was FIXED is
+   * re-quarantined on the next commit for up to 30 days (the stale flaps are still in the window),
+   * making the promotion promised by the quarantine note a no-op.
+   */
+  promoted_at: z.string().optional()
 });
 var ActivationSchema = z.object({
   /** Case-insensitive substrings matched against the task text. */
@@ -936,7 +950,8 @@ function buildPreventionReceipt(events, memories, usage, options) {
       kind: event.kind ?? sensor?.kind ?? (event.source === "sensor" ? "regex" : null),
       stage: event.stage ?? null,
       exit_code: event.exit_code ?? null,
-      message: sensor?.message ?? null
+      message: sensor?.message ?? null,
+      incident: sensor?.incident ?? null
     };
   }).sort((a, b) => b.at.localeCompare(a.at));
   const preventedCountTotal = Object.values(usage.by_id).reduce((sum, item) => sum + item.prevented_count, 0);
@@ -960,13 +975,44 @@ function renderPreventionReceipt(receipt) {
     const kind = row.kind ? `${row.kind} sensor` : row.source;
     const exit = row.exit_code === null ? "" : `, exit ${row.exit_code}`;
     const stage = row.stage ? ` \u2014 caught at ${row.stage}` : "";
-    lines.push(`  \u2717\u2192\u2713 ${row.at.slice(0, 10)}  ${row.id.padEnd(32)} (${kind}${exit}${stage})`);
+    const incident = row.incident ? `  \u21A9 incident: ${row.incident}` : "";
+    lines.push(`  \u2717\u2192\u2713 ${row.at.slice(0, 10)}  ${row.id.padEnd(32)} (${kind}${exit}${stage})${incident}`);
   }
   lines.push(
     `  Trend: ${receipt.total} this window vs ${receipt.previous_total} previous window (${receipt.total <= receipt.previous_total ? "recurrences declining" : "recurrences rising"}).`
   );
   return lines.join("\n");
 }
+var HIVELORE_ATTRIBUTION = "\u{1F6E1}\uFE0F Generated by [Hivelore](https://github.com/Doucs91/hivelore) \u2014 the deterministic policy gate for agent-written code.";
+function renderPreventionReceiptShare(receipt) {
+  const lines = [`### \u{1F6E1}\uFE0F Hivelore prevention receipt \u2014 last ${receipt.window_days} days`, ""];
+  if (receipt.total === 0) {
+    lines.push(
+      "No repeat mistakes reached review in this window.",
+      "",
+      "Turn a past incident into a guardrail so it can never come back:",
+      '`hivelore memory tried \u2026 --sensor-command "<your test>"` (add `--incident <ref>` to link the incident it guards).'
+    );
+  } else {
+    lines.push(
+      `**${receipt.total} repeat mistake${receipt.total === 1 ? "" : "s"} refused before ${receipt.total === 1 ? "it" : "they"} reached review.**`,
+      ""
+    );
+    for (const row of receipt.events) {
+      const kind = row.kind ? `${row.kind} sensor` : row.source;
+      const exit = row.exit_code === null ? "" : `, exit ${row.exit_code}`;
+      const stage = row.stage ? ` \u2014 caught at ${row.stage}` : "";
+      const incident = row.incident ? ` \u21A9 incident: ${row.incident}` : "";
+      lines.push(`- \u2717\u2192\u2713 \`${row.at.slice(0, 10)}\` **${row.title}** (${kind}${exit}${stage})${incident}`);
+    }
+    lines.push(
+      "",
+      `_Trend: ${receipt.total} this window vs ${receipt.previous_total} previous window (${receipt.total <= receipt.previous_total ? "recurrences declining" : "recurrences rising"})._`
+    );
+  }
+  lines.push("", `<sub>${HIVELORE_ATTRIBUTION}</sub>`);
+  return lines.join("\n");
+}
 async function loadPreventionEvents(paths) {
   const file = preventionLogPath(paths);
   if (!existsSync4(file)) return [];
@@ -3912,6 +3958,10 @@ function runSensors(memories, targets) {
   }
   return hits;
 }
+function incidentSuffix(incident) {
+  const ref = incident?.trim();
+  return ref ? `  \u21A9 guards incident: ${ref}` : "";
+}
 function selectCommandSensors(memories, changedPaths) {
   const specs = [];
   for (const memory of memories) {
@@ -3929,6 +3979,7 @@ function selectCommandSensors(memories, changedPaths) {
       kind: sensor.kind,
       severity: sensor.severity,
       message: sensor.message,
+      ...sensor.incident ? { incident: sensor.incident } : {},
       paths: sensor.paths.length > 0 ? sensor.paths : anchorPaths,
       ...sensor.timeout_ms ? { timeout_ms: sensor.timeout_ms } : {}
     });
@@ -4113,11 +4164,16 @@ function computeScopeHash(root, scopedFiles) {
     return "";
   }
 }
-function assessSensorHealth(evaluations, now = /* @__PURE__ */ new Date()) {
+function assessSensorHealth(evaluations, now = /* @__PURE__ */ new Date(), opts = {}) {
   const cutoff = now.getTime() - 30 * DAY_MS;
   const byMemory = /* @__PURE__ */ new Map();
   for (const e of evaluations) {
     if (e.memory_id === "__gate__" || e.kind !== "shell" && e.kind !== "test") continue;
+    const promotedAtIso = opts.promotedAt?.get(e.memory_id);
+    if (promotedAtIso) {
+      const promoted = Date.parse(promotedAtIso);
+      if (Number.isFinite(promoted) && Date.parse(e.at) <= promoted) continue;
+    }
     const list = byMemory.get(e.memory_id) ?? [];
     list.push(e);
     byMemory.set(e.memory_id, list);
@@ -4157,6 +4213,13 @@ function assessSensorHealth(evaluations, now = /* @__PURE__ */ new Date()) {
   }
   return out.sort((a, b) => a.memory_id.localeCompare(b.memory_id));
 }
+function sensorPromotedAtMap(frontmatters) {
+  const out = /* @__PURE__ */ new Map();
+  for (const fm of frontmatters) {
+    if (fm.sensor?.promoted_at) out.set(fm.id, fm.sensor.promoted_at);
+  }
+  return out;
+}
 function quarantineNote(at, flapCount) {
   return `> Quarantined ${at}: oracle flapped ${flapCount}\xD7 on identical inputs \u2014 demoted block\u2192warn. Fix the test, then re-promote with \`hivelore sensors promote <id>\`.`;
 }
@@ -5349,7 +5412,7 @@ function shaMatches(set, sha) {
   }
   return false;
 }
-function proposeGateMissDrafts(commits, existingRevertedShas, passedShas) {
+function proposeGateMissDrafts(commits, existingRevertedShas, passedShas, opts = {}) {
   const seeds = proposeSeedsFromCommits(commits, commits.length);
   const bySha = new Map(commits.map((commit) => [commit.sha, commit]));
   const seen = new Set(existingRevertedShas);
@@ -5361,7 +5424,7 @@ function proposeGateMissDrafts(commits, existingRevertedShas, passedShas) {
     if (shaMatches(seen, failedSha)) continue;
     seen.add(failedSha);
     const gatePassed = shaMatches(passedShas, failedSha);
-    const paths = (commit.files ?? []).slice(0, 8);
+    const paths = (commit.files ?? []).filter((p) => !p.startsWith(".ai/")).filter((p) => opts.pathExists?.(p) ?? true).slice(0, 8);
     const base = `# Gate miss: ${seed.what}
 
 A git ${seed.kind} indicates that a change escaped the existing harness. This is a proposed lesson only; review the actual regression before validating it.
@@ -5374,7 +5437,7 @@ Subject: ${seed.what}
 **Why it failed / do NOT use:** ${seed.why_failed}
 `;
     const gateLine = gatePassed ? "\nThe gate PASSED this commit \u2014 a validated sensor here upgrades the harness.\n" : "";
-    const candidate = suggestSensorSeed(base, paths);
+    const candidate = suggestSensorSeed(seed.what, paths);
     const sensorHint = candidate ? `
 proposed_sensor_seed: ${JSON.stringify(candidate)}
 ` : "\nproposed_sensor_seed: inspect the revert diff, then author a deterministic candidate with `hivelore sensors propose <id>`.\n";
@@ -5669,6 +5732,7 @@ export {
   HAIVE_DIR,
   HAIVE_OWNED_FILES,
   HANDOFF_FILENAME,
+  HIVELORE_ATTRIBUTION,
   MEMORIES_DIR,
   MIN_WORD_LEN,
   MemoryFrontmatterSchema,
@@ -5769,6 +5833,7 @@ export {
   handoffFilePath,
   hasRecentBriefingMarker,
   hashProjectContext,
+  incidentSuffix,
   inferModulesFromPaths,
   isAutoPromoteEligible,
   isAutoRecap,
@@ -5850,6 +5915,7 @@ export {
   renderBootstrapChecklist,
   renderCaughtForYou,
   renderPreventionReceipt,
+  renderPreventionReceiptShare,
   resolveBriefingBudget,
   resolveHaivePaths,
   resolveManifestFiles,
@@ -5869,6 +5935,7 @@ export {
   sensorAppliesToPath,
   sensorLedgerPath,
   sensorPatternBrittleness,
+  sensorPromotedAtMap,
   sensorSelfCheck,
   sensorTargetsFromDiff,
   serializeMemory,