@hivelore/core 0.56.0 → 0.57.3

package/dist/index.d.ts

@@ -1077,6 +1077,124 @@ declare function decideVerdict(input: GateVerdictInput): GateVerdict;
  */
 declare function buildBaselineHealthFinding(findings: GateFinding[], health: BaselineHealth, shouldBlock: boolean): GateFinding | null;
 
+/**
+ * How much does an anchor actually TELL US?
+ *
+ * A memory anchored to a file matched by the change is treated as `must_read` — the strongest
+ * ranking signal there is, ahead of anything semantic. That is right when the anchor is specific.
+ * It is wrong when the anchor is a file every commit touches.
+ *
+ * Measured on this repository (60 commits, 116 anchored memories):
+ *
+ *   - the MEDIAN memory claims relevance on 12 of 60 commits (20%)
+ *   - the p90 memory claims 36 of 60 (60%)
+ *   - the worst claim 37–42, and every one of them is anchored to a `package.json`
+ *
+ * A version bump touches `package.json`, so a lesson about cross-package dependency ranges declares
+ * itself `must_read` on every release commit. On a typical commit here, ~34 memories all claimed the
+ * top rank at once and the briefing had 8 slots: recall@8 was pinned near its arithmetic ceiling,
+ * and the slots went to whichever plausible memory sorted first rather than to the one that mattered.
+ * That is the mechanism behind a field report scoring briefing usefulness 30/100 while the eval
+ * harness reported 98% recall — the eval asks "given a query written to find memory X, does X
+ * surface?", which never exposes anchors competing with each other.
+ *
+ * The correction is the oldest one in information retrieval: weight a match by how rare it is.
+ * An anchor on a file touched by 3% of commits is strong evidence; the same match on a file touched
+ * by 60% of them is nearly none, and must be corroborated before it outranks everything else.
+ *
+ * Pure: churn is measured elsewhere (git), scored here.
+ */
+/** How many of the sampled commits touched each project-relative path. */
+type AnchorChurn = ReadonlyMap<string, number>;
+/**
+ * Anchors touched by more than this share of recent commits carry too little information to
+ * promote a memory on their own. 0.35 keeps genuinely component-scoped anchors (a module a third of
+ * the work touches is still a real signal) while demoting repo-wide files like `package.json`,
+ * lockfiles and CI config.
+ */
+declare const WEAK_ANCHOR_CHURN_RATIO = 0.35;
+/** Unknown churn must never penalise: a repo with no git history ranks exactly as it did before. */
+declare const DEFAULT_SPECIFICITY = 1;
+/**
+ * Specificity of the BEST anchor that matched, in 0..1.
+ *
+ * 1 = this path is barely ever touched, so matching it is strong evidence.
+ * 0 = every commit touches it, so matching it says nothing.
+ *
+ * The best (rarest) matching anchor wins: a memory anchored to both `package.json` and one precise
+ * file is precise when the precise file is what changed.
+ */
+declare function anchorSpecificity(matchedPaths: readonly string[], churn: AnchorChurn, totalCommits: number): number;
+/** True when this anchor is too common in this repo to promote a memory by itself. */
+declare function isWeakAnchor(specificity: number): boolean;
+declare function normalizeChurnPath(value: string): string;
+/**
+ * Roll per-file commit counts up to the anchor paths a memory actually declares, so a directory or
+ * glob anchor inherits the churn of everything under it. Without this, `packages/cli/` would look
+ * unknown (no commit touches a directory) and silently keep the strong default.
+ */
+declare function churnForAnchors(anchorPaths: readonly string[], fileChurn: AnchorChurn): AnchorChurn;
+interface AnchorAuditRow {
+    id: string;
+    /** Specificity of this memory's most discriminating anchor, 0..1. */
+    specificity: number;
+    /** The anchors that make it broad, with the share of commits touching each. */
+    broad: Array<{
+        path: string;
+        ratio: number;
+    }>;
+}
+/**
+ * Which memories claim relevance on nearly every change?
+ *
+ * A memory anchored only to high-churn files is not wrong — the lesson really is about that file —
+ * but it cannot help a briefing choose. It occupies a slot on every commit and displaces the lesson
+ * that is actually about the work in hand. Surfacing the list turns an invisible ranking problem
+ * into a corpus-hygiene task with an obvious fix: add the precise path the lesson is really about.
+ *
+ * Pure. Sorted worst-first so a report can take the head.
+ */
+declare function auditAnchorSpecificity(memories: ReadonlyArray<{
+    id: string;
+    anchorPaths: readonly string[];
+}>, fileChurn: AnchorChurn, totalCommits: number): AnchorAuditRow[];
+
+/**
+ * Did the tagged releases actually reach the registry?
+ *
+ * `enforce finish` verified commit, version, tag, push and CI — the whole release chain except its
+ * last link. Three consecutive releases sat tagged and green while npm stayed several versions
+ * behind, because the publish workflow SKIPS (rather than fails) when its token is absent. Nothing
+ * reported it: green CI on an unpublished release looks exactly like a shipped one.
+ *
+ * The severity split is the whole design. `finish` runs BEFORE you publish, so "HEAD's version is
+ * not on the registry yet" is the NORMAL state and can only ever be informational — a gate that
+ * cannot pass in the normal flow is a gate people switch off. What is a real defect is an
+ * INTERMEDIATE tagged version the registry skipped: it was tagged, so it was meant to ship, and it
+ * silently never did.
+ *
+ * Pure: the registry lookup and the tag listing happen in the caller.
+ */
+type NpmPublicationCode = "npm-published" | "npm-publish-pending" | "npm-releases-skipped" | "npm-publication-unverified";
+interface NpmPublicationInput {
+    packageName: string;
+    /** Version in the working tree (the lockstep version). */
+    localVersion: string;
+    /** Latest version on the registry, or null when it could not be reached. */
+    publishedVersion: string | null;
+    /** Tagged versions strictly between `publishedVersion` and `localVersion`. */
+    taggedBetween: readonly string[];
+    /** How to publish, injected so core stays free of tooling opinions. */
+    publishHint?: string;
+}
+interface NpmPublicationVerdict {
+    code: NpmPublicationCode;
+    severity: "ok" | "info" | "warn";
+    message: string;
+    fix?: string;
+}
+declare function classifyNpmPublication(input: NpmPublicationInput): NpmPublicationVerdict;
+
 type MemoryPriority = "must_read" | "useful" | "background";
 /**
  * Normalized priority evidence. A caller fills only the signals it can compute; unknown ones default
@@ -1104,6 +1222,12 @@ interface PrioritySignals {
     moduleOrDomainMatch: boolean;
     /** A memory tag matched a task token. */
     tagTaskMatch: boolean;
+    /**
+     * How much information the matched anchor carries in THIS repo, 0..1 (see `anchor-specificity.ts`).
+     * 1 (the default) means "unknown or highly specific" and preserves the historical behaviour
+     * exactly, so a repo without git history ranks as it always did.
+     */
+    anchorSpecificity?: number;
 }
 declare const DEFAULT_PRIORITY_SIGNALS: PrioritySignals;
 /** Convenience: build a full signal set from a partial one. */
@@ -1893,6 +2017,17 @@ interface HaiveConfig {
         commandSensorUnrunnable?: "warn" | "block";
         /** Require explicit resolution of a diff that demotes, rewrites, or removes a BLOCK sensor. */
         sensorWeakeningGate?: "warn" | "block";
+        /**
+         * Whether `hivelore enforce finish` checks that tagged releases actually reached the npm
+         * registry. Default on; set "off" for repos that publish elsewhere or not at all.
+         *
+         * It never blocks. `finish` runs BEFORE you publish, so "HEAD is not on npm yet" is the normal
+         * state and is reported as info. A tagged version the registry SKIPPED is reported as a warning:
+         * it was tagged, so it was meant to ship. Three consecutive releases were lost that way — the
+         * publish workflow skips rather than fails when NPM_TOKEN is absent, and green CI on an
+         * unpublished release looks exactly like a shipped one.
+         */
+        npmPublishCheck?: "off" | "warn";
         /**
          * How `hivelore enforce finish` reacts to hard failures observed this session that were never
          * captured as a lesson (`mem_tried`):
@@ -3888,4 +4023,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 AppendFrictionInput, type AppendFrictionResult, type AppliedConflictResolution, type AstExport, type AutoPromoteRule, BRIDGE_MARKERS, BRIDGE_TARGETS, BRIDGE_TARGET_PATH, BRIEFING_MARKER_TTL_MS, BRIEFING_PRESET_DEFAULTS, type BaselineHealth, 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, CONTENT_CATCH_CODES, 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 ContractCheck, 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_POSTURE, 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, FRICTION_FIELD_MAX, FRICTION_LOG_FILE, FRICTION_STATE_FILE, type FailureCoverageOptions, type FailureObservation, type FeedbackAdjustment, type FeedbackAdjustmentAction, type FeedbackAdjustmentOptions, type Finding, type FindingFormat, type FindingSeverity, type FrictionGroup, type FrictionKind, type FrictionReport, type FrictionState, type FrictionStateEntry, type FrictionStatus, GATE_REMINDER_WINDOW_MS, GUESSABLE_THRESHOLD, type GateFinding, type GateMissProposal, type GatePolicy, type GatePolicyInput, type GatePosture, type GatePrecision, type GatePrecisionDelta, type GatePrecisionMetricDelta, type GateSeverity, type GateStage, type GateTuningSuggestion, type GateVerdict, type GateVerdictInput, 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, LEGACY_CONFIG_FILE, 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, PREVENTION_RECEIPT_MARKER, PROCESS_GATE_CODES, PROJECT_CONTEXT_FILE, PROJECT_CONTEXT_THROTTLE_MS, type PostIncidentLesson, type PreventionCommentFinding, 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, SETUP_GATE_CODES, STACK_PACK_TAG, type ScaffoldLoopGap, type ScaffoldOptions, type ScaffoldStyle, 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, appendFrictionReport, appendPreventionEvent, appendProposedRetrievalCases, appendRuntimeJournalEntry, appendSensorEvaluations, appendUsageEvent, applyConflictResolution, applyFeedbackAdjustment, approveProposedCases, assessBehaviourCoverage, assessBootstrapState, assessScaffoldLoop, assessSensorHealth, bridgeMemorySummary, briefingMarkerPath, briefingMarkersDir, briefingProofLine, buildBaselineHealthFinding, buildCodeMap, buildCoverageIndex, buildDashboard, buildDocFrequency, buildFrontmatter, buildHandoffMarkdown, buildPreventionReceipt, buildProposeCommand, buildReport, bumpRead, classifyMemoryPriority, codeMapContentHash, codeMapPath, collectTimelineEntries, compactAutoRecapBody, compareEvalReports, compareGatePrecision, compareImpact, compileRegexSensor, componentOf, computeBaselineHealth, computeEvalTrend, computeGatePrecision, computeImpact, computePreventionTrend, computeRecurrence, computeScopeHash, configPath, contractLockPath, countSourceFilesOnDisk, decideVerdict, dedupeRefusals, deriveConfidence, deriveMainAreas, describePosture, detectAgentContext, detectSensorWeakening, detectStacksFromManifests, diffContract, diffHasDistinctiveOverlap, distillFailureObservations, distinctiveCap, draftsFromFindings, emptyUsage, emptyUsageIndex, enforcementDir, estimateTokens, evalHistoryPath, evaluateSkillActivation, existingGateMissShas, explainSensorRejection, extractActionsBriefBody, extractCorrectApproachExamples, extractReferencedPaths, extractReviewLearnings, extractSensorExamples, extractSnippet, extractTestFilePathsFromCommand, filterNewDrafts, findCoverageGaps, findLexicalConflictPairs, findProjectRoot, findTopicStatusConflictPairs, findUncapturedFailures, findingBody, findingToDraft, firstMemoryOneLine, formatFrictionIssue, frictionFingerprint, frictionLogPath, frictionStatePath, gatePassedShas, generateBridges, getUsage, globToRegExp, groupFriction, handoffAgeMs, handoffFilePath, hasPendingTestMarker, hasRecentBriefingMarker, hashProjectContext, incidentHintsFromDiff, incidentSuffix, inferModulesFromPaths, isAutoPromoteEligible, isAutoRecap, isCovered, isDecaying, isDistinctiveToken, isEnvWorkaroundMemory, isFreshIsoDate, isGlobPath, isHarnessErrorOutput, isLikelyGuessable, isNoiseSubject, isProductionCodeFile, isRetiredMemory, isSensorScannablePath, isSkill, isSkillSuppressed, isStackPackSeed, isStylisticRule, isTemplateProjectContext, judgeProposedSensor, lessonShortName, listMarkdownFilesRecursive, literalMatchesAllTokens, literalMatchesAnyToken, loadCodeMap, loadConfig, loadConfigSync, loadEvalHistory, loadFrictionState, loadMemoriesFromDir, loadMemoriesFromDirDetailed, loadMemory, loadPreventionEvents, loadSensorLedger, loadUsageIndex, looksLikeGenericAdvice, meetsSeedQualityFloor, memoryFilePath, memoryHasExcludedTag, memoryMatchesAnchorPaths, mergeHotFiles, mergeMemoryVersions, mineSensorSeedFromDiff, moduleNameOf, newMemoryId, normalizeFindingSeverity, normalizeFramework, normalizeFrictionSummary, normalizeKind, normalizeScaffoldStyle, 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, readFrictionReports, readRecentBriefingMarker, readRuntimeJournalTail, readSessionHandoff, readUsageEvents, recommendFeedbackAdjustment, recordApplied, recordGateReminder, recordPrevention, recordPreventionHits, recordProjectContextEmission, recordRejection, relPathFrom, renderBehaviourCoverageLine, renderBootstrapChecklist, renderCaughtForYou, renderPreventionComment, renderPreventionReceipt, renderPreventionReceiptShare, resolveBriefingBudget, resolveConfigPath, resolveGatePolicy, resolveHaivePaths, resolveManifestFiles, resolveProjectInfo, retirementSignal, revertedShaFromCommit, reviewLearningsToDrafts, runRegexSensor, runSensors, runTierContract, runValidationContract, runtimeJournalPath, saveCodeMap, saveConfig, saveFrictionState, saveUsageIndex, scaffoldPostIncidentTest, scannableSensorTargets, scoreRetrievalCase, scoreSensorCase, scrubbedCommandEnv, selectCommandSensors, sensorAppliesToPath, sensorLedgerPath, sensorPatternBrittleness, sensorPromotedAtMap, sensorSelfCheck, sensorTargetsFromDiff, serializeCodeMap, serializeMemory, setFrictionStatus, shouldExpandGateReminder, 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, type AnchorAuditRow, type AnchorChurn, AnchorSchema, type AntiPatternGate, type AppendFrictionInput, type AppendFrictionResult, type AppliedConflictResolution, type AstExport, type AutoPromoteRule, BRIDGE_MARKERS, BRIDGE_TARGETS, BRIDGE_TARGET_PATH, BRIEFING_MARKER_TTL_MS, BRIEFING_PRESET_DEFAULTS, type BaselineHealth, 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, CONTENT_CATCH_CODES, 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 ContractCheck, 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_POSTURE, DEFAULT_PRIORITY_SIGNALS, DEFAULT_SPECIFICITY, 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, FRICTION_FIELD_MAX, FRICTION_LOG_FILE, FRICTION_STATE_FILE, type FailureCoverageOptions, type FailureObservation, type FeedbackAdjustment, type FeedbackAdjustmentAction, type FeedbackAdjustmentOptions, type Finding, type FindingFormat, type FindingSeverity, type FrictionGroup, type FrictionKind, type FrictionReport, type FrictionState, type FrictionStateEntry, type FrictionStatus, GATE_REMINDER_WINDOW_MS, GUESSABLE_THRESHOLD, type GateFinding, type GateMissProposal, type GatePolicy, type GatePolicyInput, type GatePosture, type GatePrecision, type GatePrecisionDelta, type GatePrecisionMetricDelta, type GateSeverity, type GateStage, type GateTuningSuggestion, type GateVerdict, type GateVerdictInput, 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, LEGACY_CONFIG_FILE, 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, type NpmPublicationCode, type NpmPublicationInput, type NpmPublicationVerdict, PREVENTION_DEBOUNCE_MS, PREVENTION_RECEIPT_MARKER, PROCESS_GATE_CODES, PROJECT_CONTEXT_FILE, PROJECT_CONTEXT_THROTTLE_MS, type PostIncidentLesson, type PreventionCommentFinding, 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, SETUP_GATE_CODES, STACK_PACK_TAG, type ScaffoldLoopGap, type ScaffoldOptions, type ScaffoldStyle, 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, WEAK_ANCHOR_CHURN_RATIO, addedLineNumbersFromDiff, addedLinesFromDiff, aggregateRetrieval, aggregateSensors, aggregateUsage, allocateBudget, anchorMatchesComponent, anchorSpecificity, antiPatternGateParams, appendEvalHistory, appendFrictionReport, appendPreventionEvent, appendProposedRetrievalCases, appendRuntimeJournalEntry, appendSensorEvaluations, appendUsageEvent, applyConflictResolution, applyFeedbackAdjustment, approveProposedCases, assessBehaviourCoverage, assessBootstrapState, assessScaffoldLoop, assessSensorHealth, auditAnchorSpecificity, bridgeMemorySummary, briefingMarkerPath, briefingMarkersDir, briefingProofLine, buildBaselineHealthFinding, buildCodeMap, buildCoverageIndex, buildDashboard, buildDocFrequency, buildFrontmatter, buildHandoffMarkdown, buildPreventionReceipt, buildProposeCommand, buildReport, bumpRead, churnForAnchors, classifyMemoryPriority, classifyNpmPublication, codeMapContentHash, codeMapPath, collectTimelineEntries, compactAutoRecapBody, compareEvalReports, compareGatePrecision, compareImpact, compileRegexSensor, componentOf, computeBaselineHealth, computeEvalTrend, computeGatePrecision, computeImpact, computePreventionTrend, computeRecurrence, computeScopeHash, configPath, contractLockPath, countSourceFilesOnDisk, decideVerdict, dedupeRefusals, deriveConfidence, deriveMainAreas, describePosture, detectAgentContext, detectSensorWeakening, detectStacksFromManifests, diffContract, diffHasDistinctiveOverlap, distillFailureObservations, distinctiveCap, draftsFromFindings, emptyUsage, emptyUsageIndex, enforcementDir, estimateTokens, evalHistoryPath, evaluateSkillActivation, existingGateMissShas, explainSensorRejection, extractActionsBriefBody, extractCorrectApproachExamples, extractReferencedPaths, extractReviewLearnings, extractSensorExamples, extractSnippet, extractTestFilePathsFromCommand, filterNewDrafts, findCoverageGaps, findLexicalConflictPairs, findProjectRoot, findTopicStatusConflictPairs, findUncapturedFailures, findingBody, findingToDraft, firstMemoryOneLine, formatFrictionIssue, frictionFingerprint, frictionLogPath, frictionStatePath, gatePassedShas, generateBridges, getUsage, globToRegExp, groupFriction, handoffAgeMs, handoffFilePath, hasPendingTestMarker, hasRecentBriefingMarker, hashProjectContext, incidentHintsFromDiff, incidentSuffix, inferModulesFromPaths, isAutoPromoteEligible, isAutoRecap, isCovered, isDecaying, isDistinctiveToken, isEnvWorkaroundMemory, isFreshIsoDate, isGlobPath, isHarnessErrorOutput, isLikelyGuessable, isNoiseSubject, isProductionCodeFile, isRetiredMemory, isSensorScannablePath, isSkill, isSkillSuppressed, isStackPackSeed, isStylisticRule, isTemplateProjectContext, isWeakAnchor, judgeProposedSensor, lessonShortName, listMarkdownFilesRecursive, literalMatchesAllTokens, literalMatchesAnyToken, loadCodeMap, loadConfig, loadConfigSync, loadEvalHistory, loadFrictionState, loadMemoriesFromDir, loadMemoriesFromDirDetailed, loadMemory, loadPreventionEvents, loadSensorLedger, loadUsageIndex, looksLikeGenericAdvice, meetsSeedQualityFloor, memoryFilePath, memoryHasExcludedTag, memoryMatchesAnchorPaths, mergeHotFiles, mergeMemoryVersions, mineSensorSeedFromDiff, moduleNameOf, newMemoryId, normalizeChurnPath, normalizeFindingSeverity, normalizeFramework, normalizeFrictionSummary, normalizeKind, normalizeScaffoldStyle, 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, readFrictionReports, readRecentBriefingMarker, readRuntimeJournalTail, readSessionHandoff, readUsageEvents, recommendFeedbackAdjustment, recordApplied, recordGateReminder, recordPrevention, recordPreventionHits, recordProjectContextEmission, recordRejection, relPathFrom, renderBehaviourCoverageLine, renderBootstrapChecklist, renderCaughtForYou, renderPreventionComment, renderPreventionReceipt, renderPreventionReceiptShare, resolveBriefingBudget, resolveConfigPath, resolveGatePolicy, resolveHaivePaths, resolveManifestFiles, resolveProjectInfo, retirementSignal, revertedShaFromCommit, reviewLearningsToDrafts, runRegexSensor, runSensors, runTierContract, runValidationContract, runtimeJournalPath, saveCodeMap, saveConfig, saveFrictionState, saveUsageIndex, scaffoldPostIncidentTest, scannableSensorTargets, scoreRetrievalCase, scoreSensorCase, scrubbedCommandEnv, selectCommandSensors, sensorAppliesToPath, sensorLedgerPath, sensorPatternBrittleness, sensorPromotedAtMap, sensorSelfCheck, sensorTargetsFromDiff, serializeCodeMap, serializeMemory, setFrictionStatus, shouldExpandGateReminder, 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

@@ -1396,6 +1396,116 @@ function buildBaselineHealthFinding(findings, health, shouldBlock) {
   };
 }
 
+// src/anchor-specificity.ts
+var WEAK_ANCHOR_CHURN_RATIO = 0.35;
+var DEFAULT_SPECIFICITY = 1;
+function anchorSpecificity(matchedPaths, churn, totalCommits) {
+  if (totalCommits <= 0 || matchedPaths.length === 0) return DEFAULT_SPECIFICITY;
+  let best = 0;
+  let sawKnown = false;
+  for (const path22 of matchedPaths) {
+    const touched = churn.get(normalizeChurnPath(path22));
+    if (touched === void 0) continue;
+    sawKnown = true;
+    best = Math.max(best, 1 - Math.min(1, touched / totalCommits));
+  }
+  return sawKnown ? best : DEFAULT_SPECIFICITY;
+}
+function isWeakAnchor(specificity) {
+  return specificity < 1 - WEAK_ANCHOR_CHURN_RATIO;
+}
+function normalizeChurnPath(value) {
+  return value.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function churnForAnchors(anchorPaths, fileChurn) {
+  const out = /* @__PURE__ */ new Map();
+  for (const raw of anchorPaths) {
+    const anchor = normalizeChurnPath(raw);
+    const direct = fileChurn.get(anchor);
+    if (direct !== void 0) {
+      out.set(anchor, direct);
+      continue;
+    }
+    let max = 0;
+    let matched = false;
+    for (const [file, count] of fileChurn) {
+      if (!pathCoveredByAnchor(anchor, file)) continue;
+      matched = true;
+      max = Math.max(max, count);
+    }
+    if (matched) out.set(anchor, max);
+  }
+  return out;
+}
+function pathCoveredByAnchor(anchor, file) {
+  if (anchor === file) return true;
+  if (!anchor.includes("*")) return file.startsWith(`${anchor}/`);
+  const pattern = anchor.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "\0").replace(/\*/g, "[^/]*").replace(//g, ".*");
+  try {
+    return new RegExp(`^${pattern}$`).test(file);
+  } catch {
+    return false;
+  }
+}
+function auditAnchorSpecificity(memories, fileChurn, totalCommits) {
+  if (totalCommits <= 0) return [];
+  const rows = [];
+  for (const memory of memories) {
+    if (memory.anchorPaths.length === 0) continue;
+    const rolled = churnForAnchors(memory.anchorPaths, fileChurn);
+    if (rolled.size === 0) continue;
+    const specificity = anchorSpecificity(memory.anchorPaths, rolled, totalCommits);
+    if (!isWeakAnchor(specificity)) continue;
+    const broad = [...rolled].map(([path22, count]) => ({ path: path22, ratio: count / totalCommits })).filter((entry) => entry.ratio > WEAK_ANCHOR_CHURN_RATIO).sort((a, b) => b.ratio - a.ratio);
+    rows.push({ id: memory.id, specificity, broad });
+  }
+  return rows.sort((a, b) => a.specificity - b.specificity);
+}
+
+// src/npm-publication.ts
+function compareVersions(a, b) {
+  const pa = a.split(/[.-]/).map((p) => Number.parseInt(p, 10) || 0);
+  const pb = b.split(/[.-]/).map((p) => Number.parseInt(p, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length, 3); i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+function classifyNpmPublication(input) {
+  const { packageName, localVersion, publishedVersion } = input;
+  const hint = input.publishHint ?? `publish ${packageName} ${localVersion}`;
+  if (!publishedVersion) {
+    return {
+      code: "npm-publication-unverified",
+      severity: "info",
+      message: `Could not reach the registry to check whether ${packageName} ${localVersion} is published.`
+    };
+  }
+  if (compareVersions(publishedVersion, localVersion) >= 0) {
+    return {
+      code: "npm-published",
+      severity: "ok",
+      message: `${packageName} ${publishedVersion} is on npm.`
+    };
+  }
+  const skipped = [...input.taggedBetween].sort(compareVersions);
+  if (skipped.length > 0) {
+    return {
+      code: "npm-releases-skipped",
+      severity: "warn",
+      message: `${skipped.length} tagged release(s) never reached npm \u2014 ${packageName} is on ${publishedVersion}: ${skipped.map((v) => `v${v}`).join(", ")}.`,
+      fix: `Registry versions are not cumulative, so publishing the newest is enough: ${hint}. If the release workflow keeps skipping, its publish credentials are missing.`
+    };
+  }
+  return {
+    code: "npm-publish-pending",
+    severity: "info",
+    message: `${packageName} ${localVersion} is not on npm yet (registry has ${publishedVersion}) \u2014 expected at this point; publish is the next step.`,
+    fix: hint
+  };
+}
+
 // src/priority.ts
 var DEFAULT_PRIORITY_SIGNALS = {
   type: "",
@@ -1407,7 +1517,8 @@ var DEFAULT_PRIORITY_SIGNALS = {
   strongSemantic: false,
   usefulSemantic: false,
   moduleOrDomainMatch: false,
-  tagTaskMatch: false
+  tagTaskMatch: false,
+  anchorSpecificity: DEFAULT_SPECIFICITY
 };
 function prioritySignals(partial) {
   return { ...DEFAULT_PRIORITY_SIGNALS, ...partial };
@@ -1415,9 +1526,13 @@ function prioritySignals(partial) {
 function classifyMemoryPriority(signals) {
   const isNegative = signals.type === "attempt";
   const isSkill2 = signals.type === "skill";
-  if (signals.requiresHumanApproval || signals.directAnchor || signals.directSymbol || isNegative && (signals.exactTaskMatch || signals.strongSemantic) || isSkill2 && (signals.exactTaskMatch || signals.strongSemantic)) {
+  const weakAnchor = signals.directAnchor && isWeakAnchor(signals.anchorSpecificity ?? DEFAULT_SPECIFICITY);
+  const strongAnchor = signals.directAnchor && !weakAnchor;
+  const corroborated = signals.strongSemantic || signals.directSymbol;
+  if (signals.requiresHumanApproval || strongAnchor || signals.directSymbol || weakAnchor && corroborated || isNegative && (signals.exactTaskMatch || signals.strongSemantic) || isSkill2 && (signals.exactTaskMatch || signals.strongSemantic)) {
     return "must_read";
   }
+  if (weakAnchor) return "useful";
   if (isStackPackSeed({ tags: signals.tags }) || isEnvWorkaroundMemory({ tags: signals.tags })) {
     if (isStackPackSeed({ tags: signals.tags }) && (signals.exactTaskMatch || signals.strongSemantic)) {
       return "useful";
@@ -7153,6 +7268,7 @@ export {
   DEFAULT_DORMANT_DAYS,
   DEFAULT_POSTURE,
   DEFAULT_PRIORITY_SIGNALS,
+  DEFAULT_SPECIFICITY,
   ENV_WORKAROUND_TAGS,
   FRICTION_FIELD_MAX,
   FRICTION_LOG_FILE,
@@ -7189,6 +7305,7 @@ export {
   USAGE_FILE,
   USAGE_LOG_DIR,
   USAGE_LOG_FILE,
+  WEAK_ANCHOR_CHURN_RATIO,
   addedLineNumbersFromDiff,
   addedLinesFromDiff,
   aggregateRetrieval,
@@ -7196,6 +7313,7 @@ export {
   aggregateUsage,
   allocateBudget,
   anchorMatchesComponent,
+  anchorSpecificity,
   antiPatternGateParams,
   appendEvalHistory,
   appendFrictionReport,
@@ -7211,6 +7329,7 @@ export {
   assessBootstrapState,
   assessScaffoldLoop,
   assessSensorHealth,
+  auditAnchorSpecificity,
   bridgeMemorySummary,
   briefingMarkerPath,
   briefingMarkersDir,
@@ -7226,7 +7345,9 @@ export {
   buildProposeCommand,
   buildReport,
   bumpRead,
+  churnForAnchors,
   classifyMemoryPriority,
+  classifyNpmPublication,
   codeMapContentHash,
   codeMapPath,
   collectTimelineEntries,
@@ -7319,6 +7440,7 @@ export {
   isStackPackSeed,
   isStylisticRule,
   isTemplateProjectContext,
+  isWeakAnchor,
   judgeProposedSensor,
   lessonShortName,
   listMarkdownFilesRecursive,
@@ -7345,6 +7467,7 @@ export {
   mineSensorSeedFromDiff,
   moduleNameOf,
   newMemoryId,
+  normalizeChurnPath,
   normalizeFindingSeverity,
   normalizeFramework,
   normalizeFrictionSummary,