@hivelore/core 0.43.2 → 0.46.0

package/dist/index.d.ts

@@ -2356,7 +2356,32 @@ interface PostIncidentLesson {
     incident?: string;
     /** Anchor paths — used to scope the sensor and to place the test near the code. */
     paths?: string[];
-}
+    /**
+     * Optional facts derived from the incident's fix diff (red_ref..HEAD). When present, the scaffold
+     * names the actual symbols the fix touched and pre-fills the commented example around them, so the
+     * human's "fill the assertion" step is a targeted edit rather than a blank page. Deterministic and
+     * green-preserving: the enriched example stays commented (no live imports that might not resolve).
+     */
+    incidentHints?: IncidentHints;
+}
+/** Facts extracted from an incident's fix diff to make a scaffold concrete rather than generic. */
+interface IncidentHints {
+    /** The pre-fix ref the hints were derived against (for provenance in the header). */
+    redRef?: string;
+    /** Files the fix changed (within the lesson's anchor scope). */
+    changedFiles: string[];
+    /** Symbols the fix added/changed (exported functions/consts/classes; def/func for py/go). */
+    changedSymbols: string[];
+}
+/**
+ * Extract the symbols and files a fix touched from its unified diff (`git diff red_ref..HEAD`).
+ * Pure: the caller produces the diff (I/O). Scans ADDED lines for definitions across JS/TS, Python,
+ * and Go — the frameworks the scaffolder targets — so the generated test can name the real subject.
+ */
+declare function incidentHintsFromDiff(diff: string, opts?: {
+    redRef?: string;
+    limitSymbols?: number;
+}): IncidentHints;
 interface TestScaffold {
     framework: TestFramework;
     /** Suggested project-relative path for the generated test file. */
@@ -2510,10 +2535,19 @@ interface BootstrapStateInput {
  * mentions "auto-generated by `hivelore init`" in prose (e.g. a glossary line) is NOT a template.
  */
 declare function isTemplateProjectContext(raw: string): boolean;
+declare function isProductionCodeFile(file: string): boolean;
+/**
+ * The canonical set of "main code areas" for a repo, derived from the code-map's production files.
+ * A container-based component (packages/x, apps/x) is a DECLARED component and always counts; a bare
+ * top-level dir needs {@link MIN_COMPONENT_FILES} files so trivial folders aren't treated as areas.
+ * Shared so bootstrap, behaviour-coverage, and doctor all report the SAME area set and count.
+ */
+declare function deriveMainAreas(codeFiles: string[]): string[];
 /** 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;
+declare function anchorMatchesComponent(anchorPath: string, component: string): boolean;
 /**
  * Assess whether the repo knowledge layer is filled enough (the EXHAUSTIVE bar):
  *  1. project-context.md is filled (not the template, and substantial)
@@ -2525,6 +2559,73 @@ declare function assessBootstrapState(input: BootstrapStateInput): BootstrapAsse
 /** Render the assessment's gaps as a numbered checklist for an agent (action_required / gate message). */
 declare function renderBootstrapChecklist(assessment: BootstrapAssessment): string;
 
+/**
+ * Behaviour-harness coverage — the missing MEASURE for the branch Hivelore leads.
+ *
+ * The maintainability harness has a visible metric (anchor coverage in `doctor`), and the bootstrap
+ * gate reports memory/sensor coverage per area. But the *behaviour* harness — command/test sensors
+ * that route a real oracle to a lesson, optionally proven RED on the incident — had no coverage
+ * number, so its progress was invisible. This module answers three questions per main code area:
+ *   1. Is there ANY behavioural oracle (a `kind: shell|test` sensor) guarding it?
+ *   2. Is that oracle ARMED (severity `block`, so it actually refuses the repeat)?
+ *   3. Is it PROVEN (red_proven — the oracle demonstrably fails on the incident state)?
+ *
+ * Pure domain logic: no I/O. The caller loads memories + the code-map and passes them in. Area
+ * derivation is shared with the bootstrap gate ({@link deriveMainAreas}) so the "N main areas" count
+ * is identical everywhere it is reported.
+ */
+
+/** One behavioural oracle sensor (kind shell|test) and the main areas it reaches. */
+interface BehaviourOracleInfo {
+    memory_id: string;
+    kind: "shell" | "test";
+    /** `block` = armed (refuses the repeat); `warn` = advisory only. */
+    severity: "block" | "warn";
+    /** The oracle demonstrably failed on the recorded incident state at arming time. */
+    red_proven: boolean;
+    /** Main code areas this oracle guards (by anchor or by sensor scope). */
+    areas: string[];
+}
+/** A concrete "how to guard this area" pointer — closes the loop from measure to action. */
+interface UncoveredAreaSuggestion {
+    area: string;
+    /**
+     * An existing lesson (attempt/gotcha anchored into the area, not yet a behavioural oracle) that a
+     * test can be scaffolded from. Absent → no lesson exists there yet; capture the incident first.
+     */
+    candidateLessonId?: string;
+}
+interface BehaviourCoverageMetrics {
+    /** Canonical main code areas (same set the bootstrap gate uses). */
+    mainAreas: string[];
+    /** Areas guarded by at least one behavioural oracle of any severity. */
+    areasWithOracle: string[];
+    /** Areas guarded by at least one ARMED (block) behavioural oracle. */
+    areasWithArmedOracle: string[];
+    /** Areas guarded by at least one red-proven behavioural oracle. */
+    areasWithRedProven: string[];
+    /** Main areas with NO behavioural oracle at all. */
+    uncoveredAreas: string[];
+    /** Per uncovered area: the concrete lesson to scaffold a behavioural oracle from (when one exists). */
+    uncoveredAreaSuggestions: UncoveredAreaSuggestion[];
+    /** Every behavioural oracle sensor found, with the areas it reaches. */
+    oracles: BehaviourOracleInfo[];
+    totalOracles: number;
+    /** Oracles at `block` severity. */
+    armedOracles: number;
+    /** Oracles with red_proven === true. */
+    redProvenOracles: number;
+}
+interface BehaviourCoverageInput {
+    memories: LoadedMemory[];
+    /** Raw code file paths from the code-map (this module filters to production files). */
+    codeFiles: string[];
+}
+/** Assess how much of the repo's behaviour surface is guarded by armed, proven oracles. */
+declare function assessBehaviourCoverage(input: BehaviourCoverageInput): BehaviourCoverageMetrics;
+/** One-line human summary for a receipt / status line (no leading label). */
+declare function renderBehaviourCoverageLine(m: BehaviourCoverageMetrics): string;
+
 /**
  * Findings ingestion — the self-feeding half of the sensors story (feature B).
  *
@@ -3312,4 +3413,4 @@ interface ReviewDraftOptions {
 /** Template review learnings into proposed-memory drafts (reuses the scanner-ingest draft shape). */
 declare function reviewLearningsToDrafts(learnings: ReviewLearning[], options?: ReviewDraftOptions): MemoryDraft[];
 
-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 DistilledFailureLesson, 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 ProposedEvalSpec, type ProposedSensorVerdict, REVIEW_LEARNING_MARKER, RUNTIME_JOURNAL_FILENAME, type RecurrenceReport, type RecurrenceRow, type ResolveProjectInfo, type RetirementSignal, type RetrievalAggregate, type RetrievalCase, type RetrievalCaseResult, type ReviewDraftOptions, type ReviewLearning, type RuntimeJournalEntry, SCAFFOLD_MARKER_RE, SEED_QUALITY_FLOOR, SENSOR_ABSENT_LOOKBACK, SENSOR_ABSENT_WINDOW, SESSION_RECAP_TTL_MS, STACK_PACK_TAG, type ScaffoldLoopGap, 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 SensorWeakening, type SessionHandoffData, type SkillActivation, TEST_FRAMEWORKS, type TestFramework, type TestScaffold, type TierContractCheck, 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, addedLineNumbersFromDiff, addedLinesFromDiff, aggregateRetrieval, aggregateSensors, aggregateUsage, allocateBudget, antiPatternGateParams, appendEvalHistory, appendPreventionEvent, appendProposedRetrievalCases, appendRuntimeJournalEntry, appendSensorEvaluations, appendUsageEvent, applyConflictResolution, applyFeedbackAdjustment, approveProposedCases, assessBootstrapState, assessScaffoldLoop, assessSensorHealth, bridgeMemorySummary, briefingMarkerPath, briefingMarkersDir, briefingProofLine, buildCodeMap, buildCoverageIndex, buildDashboard, buildDocFrequency, buildFrontmatter, buildHandoffMarkdown, buildPreventionReceipt, buildProposeCommand, buildReport, bumpRead, classifyMemoryPriority, codeMapPath, collectTimelineEntries, compactAutoRecapBody, compareEvalReports, compareGatePrecision, compareImpact, compileRegexSensor, componentOf, computeEvalTrend, computeGatePrecision, computeImpact, computePreventionTrend, computeRecurrence, computeScopeHash, configPath, contractLockPath, countSourceFilesOnDisk, deriveConfidence, detectAgentContext, detectSensorWeakening, detectStacksFromManifests, diffContract, diffHasDistinctiveOverlap, distillFailureObservations, distinctiveCap, draftsFromFindings, emptyUsage, emptyUsageIndex, enforcementDir, estimateTokens, evalHistoryPath, evaluateSkillActivation, existingGateMissShas, extractActionsBriefBody, extractReferencedPaths, extractReviewLearnings, extractSensorExamples, extractSnippet, extractTestFilePathsFromCommand, filterNewDrafts, findCoverageGaps, findLexicalConflictPairs, findProjectRoot, findTopicStatusConflictPairs, findUncapturedFailures, findingBody, findingToDraft, firstMemoryOneLine, gatePassedShas, generateBridges, getUsage, globToRegExp, handoffAgeMs, handoffFilePath, hasPendingTestMarker, 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, normalizeFramework, normalizeSessionId, overallScore, parseEslintJson, parseFileAst, parseFindings, parseLessonFields, parseMemory, parseNpmAudit, parseSarif, parseSince, parseSonar, pathsOverlap, pickSnippetNeedle, pickTestFramework, 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, reviewLearningsToDrafts, runRegexSensor, runSensors, runTierContract, runtimeJournalPath, saveCodeMap, saveConfig, saveUsageIndex, scaffoldPostIncidentTest, scannableSensorTargets, scoreRetrievalCase, scoreSensorCase, scrubbedCommandEnv, 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 BehaviourCoverageInput, type BehaviourCoverageMetrics, type BehaviourOracleInfo, 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 DistilledFailureLesson, 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 IncidentHints, 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 ProposedEvalSpec, type ProposedSensorVerdict, REVIEW_LEARNING_MARKER, RUNTIME_JOURNAL_FILENAME, type RecurrenceReport, type RecurrenceRow, type ResolveProjectInfo, type RetirementSignal, type RetrievalAggregate, type RetrievalCase, type RetrievalCaseResult, type ReviewDraftOptions, type ReviewLearning, type RuntimeJournalEntry, SCAFFOLD_MARKER_RE, SEED_QUALITY_FLOOR, SENSOR_ABSENT_LOOKBACK, SENSOR_ABSENT_WINDOW, SESSION_RECAP_TTL_MS, STACK_PACK_TAG, type ScaffoldLoopGap, 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 SensorWeakening, type SessionHandoffData, type SkillActivation, TEST_FRAMEWORKS, type TestFramework, type TestScaffold, type TierContractCheck, type TimelineEntry, type TopicStatusPair, type TruncateOptions, type TruncateResult, USAGE_FILE, USAGE_LOG_DIR, USAGE_LOG_FILE, type UncapturedFailure, type UncoveredAreaSuggestion, type UsageAggregate, type UsageEvent, type UsageIndex, type VerifyOptions, type VerifyResult, addedLineNumbersFromDiff, addedLinesFromDiff, aggregateRetrieval, aggregateSensors, aggregateUsage, allocateBudget, anchorMatchesComponent, antiPatternGateParams, appendEvalHistory, appendPreventionEvent, appendProposedRetrievalCases, appendRuntimeJournalEntry, appendSensorEvaluations, appendUsageEvent, applyConflictResolution, applyFeedbackAdjustment, approveProposedCases, assessBehaviourCoverage, assessBootstrapState, assessScaffoldLoop, assessSensorHealth, bridgeMemorySummary, briefingMarkerPath, briefingMarkersDir, briefingProofLine, buildCodeMap, buildCoverageIndex, buildDashboard, buildDocFrequency, buildFrontmatter, buildHandoffMarkdown, buildPreventionReceipt, buildProposeCommand, buildReport, bumpRead, classifyMemoryPriority, codeMapPath, collectTimelineEntries, compactAutoRecapBody, compareEvalReports, compareGatePrecision, compareImpact, compileRegexSensor, componentOf, computeEvalTrend, computeGatePrecision, computeImpact, computePreventionTrend, computeRecurrence, computeScopeHash, configPath, contractLockPath, countSourceFilesOnDisk, deriveConfidence, deriveMainAreas, detectAgentContext, detectSensorWeakening, detectStacksFromManifests, diffContract, diffHasDistinctiveOverlap, distillFailureObservations, distinctiveCap, draftsFromFindings, emptyUsage, emptyUsageIndex, enforcementDir, estimateTokens, evalHistoryPath, evaluateSkillActivation, existingGateMissShas, extractActionsBriefBody, extractReferencedPaths, extractReviewLearnings, extractSensorExamples, extractSnippet, extractTestFilePathsFromCommand, filterNewDrafts, findCoverageGaps, findLexicalConflictPairs, findProjectRoot, findTopicStatusConflictPairs, findUncapturedFailures, findingBody, findingToDraft, firstMemoryOneLine, gatePassedShas, generateBridges, getUsage, globToRegExp, handoffAgeMs, handoffFilePath, hasPendingTestMarker, hasRecentBriefingMarker, hashProjectContext, incidentHintsFromDiff, incidentSuffix, inferModulesFromPaths, isAutoPromoteEligible, isAutoRecap, isCovered, isDecaying, isDistinctiveToken, isEnvWorkaroundMemory, isFreshIsoDate, isGlobPath, isLikelyGuessable, isNoiseSubject, isProductionCodeFile, 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, normalizeFramework, normalizeSessionId, overallScore, parseEslintJson, parseFileAst, parseFindings, parseLessonFields, parseMemory, parseNpmAudit, parseSarif, parseSince, parseSonar, pathsOverlap, pickSnippetNeedle, pickTestFramework, planConflictResolution, planGitWatch, prepareBridgeData, preventionLogPath, priorityRank, prioritySignals, projectContextRecentlyEmitted, proposeGateMissDrafts, proposeSeedsFromCommits, pullCrossRepoSources, quarantineNote, queryCodeMap, rankMemoriesLexical, readRecentBriefingMarker, readRuntimeJournalTail, readSessionHandoff, readUsageEvents, recommendFeedbackAdjustment, recordApplied, recordPrevention, recordPreventionHits, recordProjectContextEmission, recordRejection, relPathFrom, renderBehaviourCoverageLine, renderBootstrapChecklist, renderCaughtForYou, renderPreventionReceipt, renderPreventionReceiptShare, resolveBriefingBudget, resolveHaivePaths, resolveManifestFiles, resolveProjectInfo, retirementSignal, revertedShaFromCommit, reviewLearningsToDrafts, runRegexSensor, runSensors, runTierContract, runtimeJournalPath, saveCodeMap, saveConfig, saveUsageIndex, scaffoldPostIncidentTest, scannableSensorTargets, scoreRetrievalCase, scoreSensorCase, scrubbedCommandEnv, 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

@@ -1151,7 +1151,7 @@ function summarizeCaughtForYou(events, memories, usage, options = {}) {
 function renderCaughtForYou(summary) {
   if (summary.total_catches === 0 || summary.rows.length === 0) return null;
   const lines = [
-    `Caught for you: ${summary.total_catches} prevented repeat${summary.total_catches === 1 ? "" : "s"} this session.`
+    `Caught for you: ${summary.total_catches} prevented repeat${summary.total_catches === 1 ? "" : "s"} ${summary.since ? "this session" : "in recorded history"}.`
   ];
   for (const row of summary.rows) {
     const gate = row.source === "anti-pattern" ? "Blocked" : "Caught";
@@ -4744,6 +4744,71 @@ function escapeRegExp(value) {
 
 // src/test-scaffold.ts
 var TEST_FRAMEWORKS = ["vitest", "jest", "pytest", "gotest"];
+function incidentHintsFromDiff(diff, opts = {}) {
+  const changedFiles = [];
+  const touched = [];
+  const valueAdded = [];
+  const CONTAINER_PATTERNS = [
+    /(?:^|\s)export\s+(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/,
+    /(?:^|\s)export\s+(?:default\s+)?class\s+([A-Za-z_$][\w$]*)/,
+    /(?:^|\s)(?:async\s+)?function\s+([A-Za-z_$][\w$]*)/,
+    /(?:^|\s)class\s+([A-Za-z_$][\w$]*)/,
+    /(?:^|\s)def\s+([A-Za-z_][\w]*)\s*\(/,
+    // python
+    /(?:^|\s)func\s+(?:\([^)]*\)\s*)?([A-Za-z_][\w]*)\s*\(/
+    // go (incl. methods)
+  ];
+  const VALUE_PATTERN = /(?:^|\s)export\s+(?:const|let|var)\s+([A-Za-z_$][\w$]*)/;
+  const containerOf = (text) => {
+    for (const re of CONTAINER_PATTERNS) {
+      const m = re.exec(text);
+      if (m?.[1]) return m[1];
+    }
+    return null;
+  };
+  let enclosing = null;
+  const markTouched = (sym) => {
+    if (sym && !touched.includes(sym)) touched.push(sym);
+  };
+  for (const raw of diff.split("\n")) {
+    if (raw.startsWith("+++ ")) {
+      const p = raw.slice(4).trim().replace(/^b\//, "");
+      if (p && p !== "/dev/null") changedFiles.push(p);
+      enclosing = null;
+      continue;
+    }
+    if (raw.startsWith("@@")) {
+      enclosing = containerOf(raw.replace(/^@@[^@]*@@/, ""));
+      continue;
+    }
+    if (raw.startsWith("---")) continue;
+    const isAdded = raw.startsWith("+");
+    const isRemoved = raw.startsWith("-");
+    const body = isAdded || isRemoved ? raw.slice(1) : raw.replace(/^ /, "");
+    const container = containerOf(body);
+    if (container) enclosing = container;
+    if (isAdded || isRemoved) {
+      markTouched(enclosing);
+      if (isAdded) {
+        const value = VALUE_PATTERN.exec(body);
+        if (value?.[1]) valueAdded.push(value[1]);
+      }
+    }
+  }
+  const limit = opts.limitSymbols ?? 6;
+  const changedSymbols = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const sym of [...touched, ...valueAdded]) {
+    if (seen.has(sym)) continue;
+    seen.add(sym);
+    changedSymbols.push(sym);
+  }
+  return {
+    ...opts.redRef ? { redRef: opts.redRef } : {},
+    changedFiles: [...new Set(changedFiles)],
+    changedSymbols: changedSymbols.slice(0, limit)
+  };
+}
 function normalizeFramework(input) {
   const v = input.trim().toLowerCase();
   if (v === "vitest") return "vitest";
@@ -4799,18 +4864,63 @@ function buildProposeCommand(lesson, runCommand) {
   return parts.join(" ");
 }
 function header(lesson, comment) {
+  const hints = lesson.incidentHints;
+  const fixLines = [];
+  if (hints && (hints.changedSymbols.length > 0 || hints.changedFiles.length > 0)) {
+    const ref = hints.redRef ? ` (${hints.redRef}..HEAD)` : "";
+    if (hints.changedSymbols.length > 0) {
+      fixLines.push(`Fix${ref} touched: ${hints.changedSymbols.join(", ")}` + (hints.changedFiles.length > 0 ? ` in ${hints.changedFiles.slice(0, 3).join(", ")}` : "") + ".");
+    } else {
+      fixLines.push(`Fix${ref} touched: ${hints.changedFiles.slice(0, 3).join(", ")}.`);
+    }
+  }
   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)}`] : [],
+    ...fixLines,
     "",
     "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 exampleLines(lesson, lang) {
+  const symbol = lesson.incidentHints?.changedSymbols[0];
+  const file = lesson.incidentHints?.changedFiles[0];
+  if (lang === "js") {
+    if (symbol) {
+      return [
+        `// it("guards the incident", () => {`,
+        ...file ? [`//   import { ${symbol} } from "${importSpecifier(file)}";  // adjust the relative path`] : [],
+        `//   // Reproduce the incident input, then assert the behaviour the fix guarantees:`,
+        `//   expect(${symbol}(/* incident input */)).toBe(/* post-fix expected */);`,
+        `// });`
+      ];
+    }
+    return [
+      `// it("guards the incident", () => {`,
+      `//   // Arrange the state that caused the incident, then assert the fixed behaviour.`,
+      `//   expect(subjectUnderTest()).toBe(/* expected */);`,
+      `// });`
+    ];
+  }
+  if (lang === "py") {
+    return symbol ? [
+      `    # Reproduce the incident input, then assert what the fix guarantees:`,
+      `    assert ${symbol}(...) == expected  # ${symbol} was changed by the fix`
+    ] : [
+      `    # Arrange the state that caused the incident, then assert the fixed behaviour.`,
+      `    assert subject_under_test() == expected`
+    ];
+  }
+  return symbol ? [`	// Reproduce the incident input, then assert what the fix guarantees (subject: ${symbol}).`] : [`	// Arrange the state that caused the incident, then assert the fixed behaviour.`];
+}
+function importSpecifier(file) {
+  return file.replace(/\.[cm]?[jt]sx?$/, "");
+}
 function scaffoldPostIncidentTest(lesson, options) {
   const framework = options.framework;
   const short = lessonShortName(lesson.memoryId);
@@ -4832,10 +4942,7 @@ function scaffoldPostIncidentTest(lesson, options) {
 ` + 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 */);
-  // });
+` + exampleLines(lesson, "js").map((l) => `  ${l}`).join("\n") + `
 });
 `;
   } else if (framework === "pytest") {
@@ -4851,9 +4958,7 @@ 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
-`;
+` + exampleLines(lesson, "py").join("\n") + "\n";
   } else {
     const fn = pascal(short);
     const dir = options.outPath ? options.outPath.replace(/\/[^/]+$/, "") : joinRel(options.baseDir, "incidents");
@@ -4869,7 +4974,7 @@ 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.
+` + exampleLines(lesson, "go").join("\n") + `
 }
 `;
   }
@@ -4931,6 +5036,16 @@ function isProductionCodeFile(file) {
   if (base.endsWith(".config.ts") || base.endsWith(".config.js") || base.endsWith(".config.mjs")) return false;
   return true;
 }
+function deriveMainAreas(codeFiles) {
+  const production = codeFiles.filter(isProductionCodeFile);
+  const fileCounts = /* @__PURE__ */ new Map();
+  for (const f of production) {
+    const c = componentOf(f);
+    if (!c) continue;
+    fileCounts.set(c, (fileCounts.get(c) ?? 0) + 1);
+  }
+  return [...fileCounts.entries()].filter(([c, n]) => c.includes("/") || n >= MIN_COMPONENT_FILES).map(([c]) => c).sort();
+}
 function componentOf(file) {
   const parts = file.replace(/^\/+/, "").split("/").filter(Boolean);
   if (parts.length >= 2 && CONTAINER_DIRS.has(parts[0])) return `${parts[0]}/${parts[1]}`;
@@ -4948,13 +5063,7 @@ function anchorMatchesComponent(anchorPath, component) {
 function assessBootstrapState(input) {
   const projectContextFilled = !isTemplateProjectContext(input.projectContextRaw) && input.projectContextRaw.trim().length >= MIN_CONTEXT_CHARS;
   const codeFiles = input.codeFiles.filter(isProductionCodeFile);
-  const fileCounts = /* @__PURE__ */ new Map();
-  for (const f of codeFiles) {
-    const c = componentOf(f);
-    if (!c) continue;
-    fileCounts.set(c, (fileCounts.get(c) ?? 0) + 1);
-  }
-  const components = [...fileCounts.entries()].filter(([c, n]) => c.includes("/") || n >= MIN_COMPONENT_FILES).map(([c]) => c).sort();
+  const components = deriveMainAreas(input.codeFiles);
   const anchoredMemories = input.memories.filter(
     (m) => (m.memory.frontmatter.status === "validated" || m.memory.frontmatter.status === "proposed") && m.memory.frontmatter.anchor.paths.length > 0
   );
@@ -5054,6 +5163,88 @@ function renderBootstrapChecklist(assessment) {
   return lines.join("\n");
 }
 
+// src/behaviour-coverage.ts
+function oracleReachesArea(m, area, productionInArea) {
+  const fm = m.memory.frontmatter;
+  if (fm.anchor.paths.some((p) => anchorMatchesComponent(p, area))) return true;
+  const scopes = fm.sensor?.paths ?? [];
+  return scopes.some((raw) => {
+    const scope = raw.replace(/^\/+/, "").replace(/\/+$/, "");
+    if (!scope) return false;
+    if (isGlobPath(scope)) {
+      const re = globToRegExp(scope);
+      return productionInArea.some((f) => re.test(f));
+    }
+    return anchorMatchesComponent(scope, area);
+  });
+}
+function assessBehaviourCoverage(input) {
+  const mainAreas = deriveMainAreas(input.codeFiles);
+  const production = input.codeFiles.filter(isProductionCodeFile);
+  const filesByArea = /* @__PURE__ */ new Map();
+  for (const area of mainAreas) {
+    filesByArea.set(area, production.filter((f) => componentOf(f) === area));
+  }
+  const oracleMemories = input.memories.filter((m) => {
+    const s = m.memory.frontmatter.sensor;
+    if (!s || s.kind !== "shell" && s.kind !== "test") return false;
+    const status = m.memory.frontmatter.status;
+    return status === "validated" || status === "proposed";
+  });
+  const oracles = oracleMemories.map((m) => {
+    const s = m.memory.frontmatter.sensor;
+    const areas = mainAreas.filter((area) => oracleReachesArea(m, area, filesByArea.get(area) ?? []));
+    return {
+      memory_id: m.memory.frontmatter.id,
+      kind: s.kind === "shell" ? "shell" : "test",
+      severity: s.severity === "block" ? "block" : "warn",
+      red_proven: s.red_proven === true,
+      areas
+    };
+  });
+  const areasWith = (predicate) => mainAreas.filter((area) => oracles.some((o) => o.areas.includes(area) && predicate(o)));
+  const areasWithOracle = areasWith(() => true);
+  const areasWithArmedOracle = areasWith((o) => o.severity === "block");
+  const areasWithRedProven = areasWith((o) => o.red_proven);
+  const uncoveredAreas = mainAreas.filter((area) => !areasWithOracle.includes(area));
+  const scaffoldableLessons = input.memories.filter((m) => {
+    const fm = m.memory.frontmatter;
+    if (fm.type !== "attempt" && fm.type !== "gotcha") return false;
+    if (fm.status !== "validated" && fm.status !== "proposed") return false;
+    const kind = fm.sensor?.kind;
+    return kind !== "shell" && kind !== "test";
+  });
+  const uncoveredAreaSuggestions = uncoveredAreas.map((area) => {
+    const candidates = scaffoldableLessons.filter((m) => m.memory.frontmatter.anchor.paths.some((p) => anchorMatchesComponent(p, area))).sort((a, b) => {
+      const rank = (m) => m.memory.frontmatter.type === "attempt" ? 0 : 1;
+      const byType = rank(a) - rank(b);
+      if (byType !== 0) return byType;
+      return String(b.memory.frontmatter.created_at ?? "").localeCompare(String(a.memory.frontmatter.created_at ?? ""));
+    });
+    const id = candidates[0]?.memory.frontmatter.id;
+    return id ? { area, candidateLessonId: id } : { area };
+  });
+  return {
+    mainAreas,
+    areasWithOracle,
+    areasWithArmedOracle,
+    areasWithRedProven,
+    uncoveredAreas,
+    uncoveredAreaSuggestions,
+    oracles,
+    totalOracles: oracles.length,
+    armedOracles: oracles.filter((o) => o.severity === "block").length,
+    redProvenOracles: oracles.filter((o) => o.red_proven).length
+  };
+}
+function renderBehaviourCoverageLine(m) {
+  if (m.mainAreas.length === 0) return "no main code areas detected";
+  if (m.totalOracles === 0) {
+    return `0/${m.mainAreas.length} area(s) guarded by a behavioural oracle (no test/shell sensors yet)`;
+  }
+  return `${m.areasWithOracle.length}/${m.mainAreas.length} area(s) guarded by a behavioural oracle (${m.areasWithArmedOracle.length} armed, ${m.areasWithRedProven.length} red-proven)`;
+}
+
 // src/findings.ts
 var STYLISTIC_RULE_RE = /(?:^|[/:])(?:prettier|semi|semi-spacing|no-extra-semi|quotes|jsx-quotes|quote-props|indent|comma-dangle|comma-spacing|comma-style|eol-last|linebreak-style|no-trailing-spaces|no-multiple-empty-lines|no-multi-spaces|object-curly-spacing|array-bracket-spacing|block-spacing|space-before-blocks|space-before-function-paren|space-infix-ops|space-in-parens|keyword-spacing|arrow-spacing|key-spacing|func-call-spacing|padded-blocks|padding-line-between-statements|brace-style|spaced-comment|max-len|prefer-const|no-var)(?:$|[/:])/i;
 var SONAR_STYLISTIC_KEYS = /* @__PURE__ */ new Set([
@@ -6276,6 +6467,7 @@ export {
   aggregateSensors,
   aggregateUsage,
   allocateBudget,
+  anchorMatchesComponent,
   antiPatternGateParams,
   appendEvalHistory,
   appendPreventionEvent,
@@ -6286,6 +6478,7 @@ export {
   applyConflictResolution,
   applyFeedbackAdjustment,
   approveProposedCases,
+  assessBehaviourCoverage,
   assessBootstrapState,
   assessScaffoldLoop,
   assessSensorHealth,
@@ -6322,6 +6515,7 @@ export {
   contractLockPath,
   countSourceFilesOnDisk,
   deriveConfidence,
+  deriveMainAreas,
   detectAgentContext,
   detectSensorWeakening,
   detectStacksFromManifests,
@@ -6361,6 +6555,7 @@ export {
   hasPendingTestMarker,
   hasRecentBriefingMarker,
   hashProjectContext,
+  incidentHintsFromDiff,
   incidentSuffix,
   inferModulesFromPaths,
   isAutoPromoteEligible,
@@ -6373,6 +6568,7 @@ export {
   isGlobPath,
   isLikelyGuessable,
   isNoiseSubject,
+  isProductionCodeFile,
   isRetiredMemory,
   isSensorScannablePath,
   isSkill,
@@ -6444,6 +6640,7 @@ export {
   recordProjectContextEmission,
   recordRejection,
   relPathFrom,
+  renderBehaviourCoverageLine,
   renderBootstrapChecklist,
   renderCaughtForYou,
   renderPreventionReceipt,