@hivelore/core 0.35.1 → 0.37.0

package/dist/index.d.ts

@@ -49,6 +49,13 @@ 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). */
@@ -74,6 +81,7 @@ declare const SensorSchema: z.ZodObject<{
     flags?: string | undefined;
     command?: string | undefined;
     timeout_ms?: number | undefined;
+    incident?: string | undefined;
     promoted_at?: string | undefined;
 }, {
     message: string;
@@ -84,6 +92,7 @@ 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;
@@ -157,6 +166,13 @@ 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). */
@@ -182,6 +198,7 @@ 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;
@@ -192,6 +209,7 @@ 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;
@@ -275,6 +293,7 @@ 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?: {
@@ -306,6 +325,7 @@ 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;
@@ -361,6 +381,7 @@ 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?: {
@@ -392,6 +413,7 @@ 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;
@@ -705,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;
@@ -722,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 {
@@ -1929,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.
@@ -2121,6 +2166,67 @@ declare function suggestSensorSeed(body: string, anchorPaths: string[], options?
  */
 declare function suggestSensorFromMemory(body: string, anchorPaths: string[], options?: SensorSuggestionOptions): Sensor | null;
 
+/**
+ * Post-incident test scaffolding — turn a captured lesson (`mem_tried` / attempt / gotcha) into a
+ * PENDING test file the team fills in, then arms as a command-sensor oracle.
+ *
+ * This is the behaviour-harness bridge's on-ramp: `mem_tried` records *what* failed and *why*, but a
+ * command sensor needs the team's own test as the oracle — and someone has to write it. This module
+ * removes that friction by generating the test skeleton (header provenance + a pending test + a
+ * commented example derived from the lesson) plus the exact `sensors propose --kind test` line.
+ *
+ * DOCTRINE: this NEVER arms a sensor. It only writes a stub and prints the wiring command. Arming
+ * stays with `propose_sensor`, the sole validated writer of live sensors (silent-on-current /
+ * fires-on-bad). The generated test is deliberately PENDING (todo/skip) so the suite stays green and
+ * an empty stub can't masquerade as a passing oracle. Pure: no I/O — the caller writes the file.
+ */
+type TestFramework = "vitest" | "jest" | "pytest" | "gotest";
+declare const TEST_FRAMEWORKS: readonly TestFramework[];
+interface PostIncidentLesson {
+    /** Memory id the scaffold is generated from. */
+    memoryId: string;
+    /** Short "what was tried / what failed" title (the lesson's heading). */
+    title: string;
+    /** Why it failed / must not be used. */
+    whyFailed?: string;
+    /** The correct approach / expected behaviour. */
+    instead?: string;
+    /** Incident provenance (ticket/prod ref) carried into the sensor when armed. */
+    incident?: string;
+    /** Anchor paths — used to scope the sensor and to place the test near the code. */
+    paths?: string[];
+}
+interface TestScaffold {
+    framework: TestFramework;
+    /** Suggested project-relative path for the generated test file. */
+    relPath: string;
+    /** File contents (a pending test with provenance + a commented example). */
+    content: string;
+    /** Command that runs ONLY this test — becomes the sensor's oracle command once filled in. */
+    runCommand: string;
+    /** Ready-to-run wiring command: arms the test as a deterministic gate AFTER it is written. */
+    proposeCommand: string;
+}
+interface ScaffoldOptions {
+    framework: TestFramework;
+    /** Override the generated file path (project-relative). */
+    outPath?: string;
+}
+/** Strip the `YYYY-MM-DD-<type>-` id prefix to the descriptive slug (`importing-momentjs`). */
+declare function lessonShortName(memoryId: string): string;
+/**
+ * Parse the "what / why / instead" fields out of an attempt/gotcha memory body — the shape written
+ * by `mem_tried` (`# <what>`, `**Why it failed / do NOT use:** …`, `**Instead, use:** …`). Pure so
+ * the CLI can hand it a loaded body without re-implementing the parse.
+ */
+declare function parseLessonFields(body: string): {
+    title?: string;
+    whyFailed?: string;
+    instead?: string;
+};
+/** Build a scaffold for the given lesson + framework. Pure — the caller writes `content` to `relPath`. */
+declare function scaffoldPostIncidentTest(lesson: PostIncidentLesson, options: ScaffoldOptions): TestScaffold;
+
 /**
  * First-agent bootstrap state — is the repo's knowledge layer filled enough for later agents to rely on?
  *
@@ -2969,4 +3075,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, 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 };
+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 PostIncidentLesson, 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 ScaffoldOptions, 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, TEST_FRAMEWORKS, type TestFramework, type TestScaffold, 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, lessonShortName, 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, parseLessonFields, 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, scaffoldPostIncidentTest, 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,6 +49,13 @@ 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). */
@@ -943,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);
@@ -967,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 [];
@@ -3719,8 +3758,8 @@ var BRIDGE_MARKERS = {
 };
 function bridgeMemorySummary(body) {
   const firstLine = body.split("\n").map((l) => l.replace(/^#+\s*/, "").trim()).find((l) => l.length > 0) ?? "";
-  const oneLine = firstLine.replace(/\s+/g, " ");
-  return oneLine.length > 140 ? oneLine.slice(0, 137) + "\u2026" : oneLine;
+  const oneLine2 = firstLine.replace(/\s+/g, " ");
+  return oneLine2.length > 140 ? oneLine2.slice(0, 137) + "\u2026" : oneLine2;
 }
 function prepareBridgeData(memories, sensors, opts) {
   const max = opts?.maxMemories ?? 8;
@@ -3919,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) {
@@ -3936,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 } : {}
     });
@@ -4442,6 +4486,119 @@ function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
+// src/test-scaffold.ts
+var TEST_FRAMEWORKS = ["vitest", "jest", "pytest", "gotest"];
+function lessonShortName(memoryId) {
+  const stripped = memoryId.replace(
+    /^\d{4}-\d{2}-\d{2}-(?:attempt|gotcha|decision|convention|architecture|glossary|skill|session_recap)-/,
+    ""
+  );
+  const slug = (stripped || memoryId).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug || "incident";
+}
+function snake(slug) {
+  return slug.replace(/-/g, "_").replace(/[^a-z0-9_]/gi, "").replace(/^_+|_+$/g, "") || "incident";
+}
+function pascal(slug) {
+  return slug.split(/[^a-z0-9]+/i).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join("") || "Incident";
+}
+function oneLine(text) {
+  return (text ?? "").replace(/\s+/g, " ").trim();
+}
+function parseLessonFields(body) {
+  const title = body.match(/^#\s+(.+?)\s*$/m)?.[1]?.trim();
+  const whyFailed = body.match(/\*\*Why it failed[^:]*:\*\*\s*([^\n]+)/i)?.[1]?.trim();
+  const instead = body.match(/\*\*Instead,\s*use:\*\*\s*([^\n]+)/i)?.[1]?.trim();
+  return { title, whyFailed, instead };
+}
+function proposeCommand(lesson, runCommand) {
+  const parts = [
+    `hivelore sensors propose ${lesson.memoryId}`,
+    "--kind test",
+    `--command ${JSON.stringify(runCommand)}`
+  ];
+  if (lesson.incident) parts.push(`--incident ${JSON.stringify(lesson.incident)}`);
+  const scope = (lesson.paths ?? []).filter(Boolean);
+  if (scope.length > 0) parts.push(`--paths ${JSON.stringify(scope.join(","))}`);
+  return parts.join(" ");
+}
+function header(lesson, comment) {
+  const lines = [
+    `Post-incident guard generated by Hivelore from ${lesson.memoryId}.`,
+    ...lesson.incident ? [`Incident: ${lesson.incident}`] : [],
+    `What failed: ${oneLine(lesson.title)}`,
+    ...lesson.whyFailed ? [`Why: ${oneLine(lesson.whyFailed)}`] : [],
+    ...lesson.instead ? [`Expected / fix: ${oneLine(lesson.instead)}`] : [],
+    "",
+    "TODO: replace the pending test with a real check that FAILS on the incident and",
+    "PASSES once the fix is in place. Then arm it as a deterministic gate:"
+  ];
+  return lines.map(comment).join("\n");
+}
+function scaffoldPostIncidentTest(lesson, options) {
+  const framework = options.framework;
+  const short = lessonShortName(lesson.memoryId);
+  const desc = oneLine(lesson.title) || short;
+  let relPath;
+  let runCommand;
+  let content;
+  if (framework === "vitest" || framework === "jest") {
+    relPath = options.outPath ?? `tests/incidents/${short}.test.ts`;
+    runCommand = framework === "vitest" ? `npx vitest run ${relPath}` : `npx jest ${relPath}`;
+    const hc = (l) => l ? `// ${l}` : "//";
+    const importLine = framework === "vitest" ? `import { describe, it, expect } from "vitest";
+
+` : "";
+    content = `${header(lesson, hc)}
+//   ${proposeCommand(lesson, runCommand)}
+
+` + importLine + `describe(${JSON.stringify(desc)}, () => {
+  it.todo("reproduces ${lesson.memoryId} and stays fixed");
+
+  // it("guards the incident", () => {
+  //   // Arrange the state that caused the incident, then assert the fixed behaviour.
+  //   expect(subjectUnderTest()).toBe(/* expected */);
+  // });
+});
+`;
+  } else if (framework === "pytest") {
+    const fn = snake(short);
+    relPath = options.outPath ?? `tests/incidents/test_${fn}.py`;
+    runCommand = `pytest ${relPath}`;
+    const hc = (l) => l ? `# ${l}` : "#";
+    content = `${header(lesson, hc)}
+#   ${proposeCommand(lesson, runCommand)}
+
+import pytest
+
+
+@pytest.mark.skip(reason="TODO: write the post-incident assertion, then arm the sensor")
+def test_${fn}():
+    # Arrange the state that caused the incident, then assert the fixed behaviour.
+    assert subject_under_test() == expected
+`;
+  } else {
+    const fn = pascal(short);
+    const dir = options.outPath ? options.outPath.replace(/\/[^/]+$/, "") : "incidents";
+    relPath = options.outPath ?? `incidents/incident_${snake(short)}_test.go`;
+    runCommand = `go test ./${dir}/`;
+    const hc = (l) => l ? `// ${l}` : "//";
+    content = `${header(lesson, hc)}
+//   ${proposeCommand(lesson, runCommand)}
+
+package incidents
+
+import "testing"
+
+func Test${fn}(t *testing.T) {
+	t.Skip("TODO: write the post-incident assertion, then arm the sensor")
+	// Arrange the state that caused the incident, then assert the fixed behaviour.
+}
+`;
+  }
+  return { framework, relPath, content, runCommand, proposeCommand: proposeCommand(lesson, runCommand) };
+}
+
 // src/bootstrap-state.ts
 var CONTAINER_DIRS = /* @__PURE__ */ new Set([
   "packages",
@@ -5518,17 +5675,17 @@ function compactAutoRecapBody(body, maxChars = 600) {
   if (!isAutoRecap(body)) return body;
   const goalMatch = body.match(/##+\s*Goal[^\n]*\n+([^\n]+)/i);
   const callsMatch = body.match(/Auto-captured session \(([^)]+)\)/i);
-  const header = goalMatch?.[1]?.trim() ? `_${goalMatch[1].trim()}_` : callsMatch ? `_Auto-captured session (${callsMatch[1]})._` : "_Auto-captured session._";
+  const header2 = goalMatch?.[1]?.trim() ? `_${goalMatch[1].trim()}_` : callsMatch ? `_Auto-captured session (${callsMatch[1]})._` : "_Auto-captured session._";
   const discMatch = body.match(/##+\s*Discoveries[^\n]*\n([\s\S]*?)(?=\n##+\s|\n*$)/i);
   const discovery = discMatch?.[1]?.trim() ?? "";
   const trivialDiscovery = discovery === "" || /^no (new memories|surprising)/i.test(discovery) || /No new memories saved this session\.?$/i.test(discovery);
   if (trivialDiscovery) {
-    return `${header}
+    return `${header2}
 
 _No notable discoveries captured. Run post_task / \`mem_session_end\` for a richer recap._`;
   }
   const trimmed = discovery.length > maxChars ? discovery.slice(0, maxChars) + "\u2026" : discovery;
-  return `${header}
+  return `${header2}
 
 **Discoveries:**
 ${trimmed}`;
@@ -5688,6 +5845,7 @@ export {
   HAIVE_DIR,
   HAIVE_OWNED_FILES,
   HANDOFF_FILENAME,
+  HIVELORE_ATTRIBUTION,
   MEMORIES_DIR,
   MIN_WORD_LEN,
   MemoryFrontmatterSchema,
@@ -5704,6 +5862,7 @@ export {
   SESSION_RECAP_TTL_MS,
   STACK_PACK_TAG,
   SensorSchema,
+  TEST_FRAMEWORKS,
   USAGE_FILE,
   USAGE_LOG_DIR,
   USAGE_LOG_FILE,
@@ -5788,6 +5947,7 @@ export {
   handoffFilePath,
   hasRecentBriefingMarker,
   hashProjectContext,
+  incidentSuffix,
   inferModulesFromPaths,
   isAutoPromoteEligible,
   isAutoRecap,
@@ -5807,6 +5967,7 @@ export {
   isStylisticRule,
   isTemplateProjectContext,
   judgeProposedSensor,
+  lessonShortName,
   listMarkdownFilesRecursive,
   literalMatchesAllTokens,
   literalMatchesAnyToken,
@@ -5835,6 +5996,7 @@ export {
   parseEslintJson,
   parseFileAst,
   parseFindings,
+  parseLessonFields,
   parseMemory,
   parseNpmAudit,
   parseSarif,
@@ -5869,6 +6031,7 @@ export {
   renderBootstrapChecklist,
   renderCaughtForYou,
   renderPreventionReceipt,
+  renderPreventionReceiptShare,
   resolveBriefingBudget,
   resolveHaivePaths,
   resolveManifestFiles,
@@ -5881,6 +6044,7 @@ export {
   saveCodeMap,
   saveConfig,
   saveUsageIndex,
+  scaffoldPostIncidentTest,
   scannableSensorTargets,
   scoreRetrievalCase,
   scoreSensorCase,