@gethmy/mcp 2.8.4 → 2.8.5

package/src/auto-session.ts

@@ -68,14 +68,18 @@ export function resolveAgentIdentity(info: ClientInfo | null): {
 /**
  * Tools that trigger auto-start of a session.
  *
- * Restricted to tools that signal real work on a card. Board-management ops
- * (move, label add/remove) are excluded — they're routinely used for triage
- * and would create false-positive sessions whose side effect (the auto-added
- * `agent` label on the card) confuses both UI and humans.
+ * Restricted to tools that signal real work on a card. Triage/board-management
+ * ops are excluded — they're routinely used for sorting and card creation, not
+ * implementation, and would create false-positive sessions whose side effect
+ * (the auto-added `agent` label on the card) confuses both UI and humans.
+ *
+ * `harmony_update_card` is deliberately NOT a trigger: editing a card's
+ * title/description/priority is metadata editing (used during `/hmy` create and
+ * triage), not work. Including it spawned phantom sessions on freshly-created
+ * cards (card #295), the same reason move/label ops are excluded.
  */
 export const AUTO_START_TRIGGERS = new Set([
   "harmony_generate_prompt",
-  "harmony_update_card",
   "harmony_create_subtask",
   "harmony_toggle_subtask",
   "harmony_update_subtask",
@@ -134,6 +138,15 @@ export async function trackActivity(
   const client = options?.client ?? clientGetter?.();
   if (!client) return;
 
+  // Resolve agent identity from the MCP `initialize` handshake. Never auto-start
+  // an anonymous session: if we can't say WHO is working, we don't fabricate a
+  // phantom "Unknown Agent" session (card #295). Identified clients only — this
+  // bail happens BEFORE ending other sessions so an unidentified call can't tear
+  // down a legitimate tracked session.
+  const info = clientInfoGetter?.() ?? null;
+  if (!info?.name) return;
+  const { agentIdentifier, agentName } = resolveAgentIdentity(info);
+
   // Collect auto-sessions on other cards to end (avoid mutating map during iteration)
   const toEnd: string[] = [];
   for (const [otherCardId, session] of activeSessions) {
@@ -145,10 +158,6 @@ export async function trackActivity(
     await autoEndSession(client, otherCardId, "completed");
   }
 
-  // Resolve agent identity from MCP client info
-  const info = clientInfoGetter?.() ?? null;
-  const { agentIdentifier, agentName } = resolveAgentIdentity(info);
-
   // Start a new auto-session
   try {
     await client.startAgentSession(cardId, {

package/src/graph-expansion.ts

@@ -138,6 +138,159 @@ export async function findSimilarEntities(
   }
 }
 
+// ============ WRITE-TIME SEMANTIC DEDUP (card #275) ============
+
+/**
+ * RRF-score floor for treating a hybrid-search hit as a *supersede candidate*
+ * at write time. The hybrid_search RPC fuses FTS + vector ranks via Reciprocal
+ * Rank Fusion: score = 1/(k+fts_rank) + 1/(k+semantic_rank), k=50. A row that
+ * ranks #1 in BOTH lists tops out near 2/51 ≈ 0.039; #1 in a single list is
+ * ≈ 0.0196. RRF rank is NOT cosine similarity, so this threshold alone is a
+ * weak signal — it is paired with a lexical title-overlap guard below so we
+ * only ever surface genuinely near-duplicate titles. Deliberately
+ * conservative: dedup must never produce false "this already exists" noise.
+ *
+ * Tuning note: the cross-type causal linker (linkCrossTypeNeighbors) uses
+ * minRrfScore 0.04 for a comparable "strongly related" bar; we sit just under
+ * it because dedup probes the SAME type and wants the top fused hit.
+ */
+export const SUPERSEDE_RRF_THRESHOLD = 0.029;
+
+/**
+ * Minimum Jaccard overlap of significant title tokens required, in addition to
+ * the RRF floor, before a hit counts as a supersede candidate. Guards against
+ * semantic-only matches (e.g. two different patterns about "BoardContext")
+ * being flagged as duplicates. 0.5 = at least half the significant tokens are
+ * shared.
+ */
+export const SUPERSEDE_TITLE_OVERLAP = 0.5;
+
+const TITLE_STOPWORDS = new Set([
+  "a",
+  "an",
+  "the",
+  "and",
+  "or",
+  "of",
+  "to",
+  "in",
+  "on",
+  "for",
+  "with",
+  "is",
+  "are",
+  "be",
+  "by",
+  "at",
+  "as",
+]);
+
+function significantTitleTokens(title: string): Set<string> {
+  return new Set(
+    title
+      .toLowerCase()
+      .replace(/[^a-z0-9\s]/g, " ")
+      .split(/\s+/)
+      .filter((t) => t.length > 2 && !TITLE_STOPWORDS.has(t)),
+  );
+}
+
+/** Jaccard similarity of two token sets. Returns 0 when either set is empty. */
+function jaccard(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 || b.size === 0) return 0;
+  let intersection = 0;
+  for (const t of a) if (b.has(t)) intersection++;
+  return intersection / (a.size + b.size - intersection);
+}
+
+export interface SupersedeCandidate {
+  id: string;
+  title: string;
+  /** RRF score from the hybrid search (higher = more relevant). */
+  score: number;
+}
+
+/**
+ * Write-time dedup probe (card #275). BEFORE inserting a new memory, find
+ * existing, non-superseded entities of the SAME type + scope that look like
+ * near-duplicates of the candidate title+content.
+ *
+ * Reuses the existing hybrid-search path (searchMemoryEntities → the
+ * hybrid_search_knowledge_entities RPC) — no new embedding pipeline. A hit must
+ * clear BOTH the RRF floor AND a lexical title-overlap guard, so this is a
+ * conservative "these are probably the same memory" signal, never a silent
+ * merge.
+ *
+ * Non-fatal and non-blocking: any failure returns [] so the write still
+ * proceeds. The caller ALWAYS inserts; this only surfaces candidates for the
+ * caller (agent / assistant / human) to optionally supersede.
+ */
+export async function findSupersedeCandidates(
+  client: HarmonyApiClient,
+  title: string,
+  content: string,
+  type: string,
+  workspaceId: string,
+  options?: {
+    projectId?: string;
+    scope?: string;
+    limit?: number;
+    rrfThreshold?: number;
+    titleOverlap?: number;
+  },
+): Promise<SupersedeCandidate[]> {
+  const rrfThreshold = options?.rrfThreshold ?? SUPERSEDE_RRF_THRESHOLD;
+  const titleOverlap = options?.titleOverlap ?? SUPERSEDE_TITLE_OVERLAP;
+  const candidateTokens = significantTitleTokens(title);
+
+  try {
+    const hits = await findSimilarEntities(
+      client,
+      title,
+      content,
+      workspaceId,
+      {
+        projectId: options?.projectId,
+        // Filter to the same type server-side — dedup only applies within a type.
+        type,
+        limit: options?.limit ?? 10,
+        minRrfScore: rrfThreshold,
+      },
+    );
+
+    return hits
+      .filter((e) => {
+        // Same scope only — a project memory shouldn't supersede a global one.
+        if (options?.scope && (e as { scope?: string }).scope !== undefined) {
+          if ((e as { scope?: string }).scope !== options.scope) return false;
+        }
+        // Skip already-superseded rows when the field is present. NOTE: the
+        // hybrid-search RPC does not return `superseded_at`, so this only fires
+        // on the FTS-fallback path; on the embedding path an already-retired row
+        // can still surface as a *candidate*. That is non-destructive — the
+        // `similar` list is advisory and the caller decides explicitly whether
+        // to supersede. A complete fix needs the RPC to return/filter the column
+        // (migration + deploy); tracked in docs/memory.md.
+        if ((e as { superseded_at?: string | null }).superseded_at) {
+          return false;
+        }
+        // Lexical guard: require real title-token overlap on top of RRF.
+        return (
+          jaccard(candidateTokens, significantTitleTokens(e.title)) >=
+          titleOverlap
+        );
+      })
+      .map((e) => ({
+        id: e.id,
+        title: e.title,
+        score: e.rrf_score ?? 0,
+      }));
+  } catch {
+    // Never block a write because the dedup probe failed.
+    return [];
+  }
+}
+
 /**
  * Causal lookup table: maps an entity type to the target types it should
  * be linked to, along with the relation type and direction.

package/src/memory-park.ts

@@ -11,9 +11,18 @@
  *                      baseline so recency + importance still differentiate.
  *   recency_decay    — exp(-Δt_seconds / τ_type) clamped to [0, 1].
  *                      τ depends on memory type per plan §4.
- *   importance_norm  — importance / 10, clamped to [0, 1].
+ *   importance_norm  — effective_importance / 10, clamped to [0, 1], where
+ *                      effective_importance folds in two bounded, deterministic
+ *                      signals on top of the stored importance (card #279):
+ *                        + usage bump   — proven-useful memories (recalled
+ *                                         often) rank above never-recalled ones
+ *                        + feedback bump — 👍/👎 stored in metadata.feedback
+ *                      See `effectiveImportance` below. This is RANKING ONLY:
+ *                      nothing is stored, deleted, or mutated.
  *
- *   defaults: α=0.55, β=0.25, γ=0.20 (sum to 1.0).
+ *   defaults: α=0.55, β=0.25, γ=0.20 (sum to 1.0). Weights are NOT re-tuned by
+ *   #279 — usage + feedback fold into the existing γ·importance term so the
+ *   formula stays a stable 3-weight model.
  *
  * The function is pure. Hot-path-safe — no LLM calls, no DB reads.
  */
@@ -28,6 +37,37 @@ export const DEFAULT_WEIGHTS = {
   importance: 0.2,
 } as const;
 
+// ---------------------------------------------------------------------------
+// Usage + feedback bumps (card #279) — fold into effective importance.
+// ---------------------------------------------------------------------------
+
+/**
+ * Usage bump (card #279, task 2). A bounded, log-scaled lift to importance for
+ * memories that have actually been recalled. Proven-useful memories outrank
+ * never-recalled ones at equal relevance/recency; never-used ones get +0 and
+ * gently sink relative to their used peers.
+ *
+ *   bump = USAGE_BUMP_SCALE · ln(1 + access_count), capped at USAGE_BUMP_MAX
+ *
+ * Log scaling keeps the lift gentle and diminishing: the jump from 0→1 recall
+ * matters most, runaway counts can't dominate. Capped so usage never swamps the
+ * stored importance signal. Pure + deterministic — no LLM, no storage change.
+ */
+export const USAGE_BUMP_SCALE = 0.6;
+export const USAGE_BUMP_MAX = 2;
+
+/**
+ * Feedback bump (card #279, task 3). Net 👍/👎 stored non-destructively in
+ * `metadata.feedback = { up, down }` shifts importance up (positive net) or
+ * down (negative net), bounded and symmetric. Feedback affects RANKING ONLY —
+ * it never deletes or supersedes a memory.
+ *
+ *   bump = FEEDBACK_BUMP_SCALE · sign(net) · ln(1 + |net|),
+ *          clamped to ±FEEDBACK_BUMP_MAX
+ */
+export const FEEDBACK_BUMP_SCALE = 0.8;
+export const FEEDBACK_BUMP_MAX = 2;
+
 // Per-type recency time constant τ in seconds.
 // `Infinity` = never decays (preferences shouldn't fade with disuse).
 export const TYPE_TAU_SECONDS: Record<string, number> = {
@@ -71,17 +111,28 @@ export const TYPE_IMPORTANCE_DEFAULT: Record<string, number> = {
 // Types
 // ---------------------------------------------------------------------------
 
+/** 👍/👎 counters stored non-destructively at `metadata.feedback`. */
+export interface MemoryFeedback {
+  up?: number;
+  down?: number;
+}
+
 export interface ParkInput {
   type: string;
   importance?: number | null;
   last_accessed_at?: string | null;
   created_at?: string | null;
+  /** Recall counter maintained by batch_touch_knowledge_entities (#273). */
+  access_count?: number | null;
+  /** Carries `metadata.feedback` (#279). Other metadata keys are ignored. */
+  metadata?: { feedback?: MemoryFeedback | null } | null;
 }
 
 export interface ParkScored<T extends ParkInput> {
   entity: T;
   relevance: number;
   recency: number;
+  /** Effective importance term, normalised to [0,1] (post usage + feedback). */
   importance: number;
   score: number;
 }
@@ -124,10 +175,59 @@ function recencyDecay(
   return clamp01(Math.exp(-dtSec / tau));
 }
 
-function importanceNorm(raw: number | null | undefined, type: string): number {
+/** Resolve the stored (base) importance, clamped to [1,10]. */
+function baseImportance(raw: number | null | undefined, type: string): number {
   let v = typeof raw === "number" ? raw : (TYPE_IMPORTANCE_DEFAULT[type] ?? 5);
   if (v < 1) v = 1;
   if (v > 10) v = 10;
+  return v;
+}
+
+/**
+ * Bounded, log-scaled usage lift (card #279, task 2). +0 for never-recalled.
+ * Pure; reads only `access_count`.
+ */
+export function usageBump(accessCount: number | null | undefined): number {
+  const n =
+    typeof accessCount === "number" && accessCount > 0 ? accessCount : 0;
+  if (n === 0) return 0;
+  return Math.min(USAGE_BUMP_MAX, USAGE_BUMP_SCALE * Math.log(1 + n));
+}
+
+/**
+ * Bounded, symmetric feedback shift (card #279, task 3). Positive net 👍 lifts,
+ * negative net 👎 demotes. Pure; reads only `metadata.feedback`.
+ */
+export function feedbackBump(
+  feedback: MemoryFeedback | null | undefined,
+): number {
+  const up = typeof feedback?.up === "number" ? feedback.up : 0;
+  const down = typeof feedback?.down === "number" ? feedback.down : 0;
+  const net = up - down;
+  if (net === 0) return 0;
+  const raw =
+    FEEDBACK_BUMP_SCALE * Math.sign(net) * Math.log(1 + Math.abs(net));
+  if (raw > FEEDBACK_BUMP_MAX) return FEEDBACK_BUMP_MAX;
+  if (raw < -FEEDBACK_BUMP_MAX) return -FEEDBACK_BUMP_MAX;
+  return raw;
+}
+
+/**
+ * Effective importance = base importance + usage bump + feedback bump, clamped
+ * to [1,10], then normalised to [0,1] (card #279, task 2 + 3).
+ *
+ * Folding usage + feedback into the existing γ·importance term — instead of
+ * adding new weights — keeps the Park formula a stable 3-weight model. This is
+ * a RANKING-ONLY transform: it reads `access_count` and `metadata.feedback`
+ * but never writes, deletes, or supersedes anything.
+ */
+export function effectiveImportance(entity: ParkInput): number {
+  const base = baseImportance(entity.importance, entity.type);
+  const bump =
+    usageBump(entity.access_count) + feedbackBump(entity.metadata?.feedback);
+  let v = base + bump;
+  if (v < 1) v = 1;
+  if (v > 10) v = 10;
   return v / 10;
 }
 
@@ -160,7 +260,7 @@ export function rescore<T extends ParkInput & { id?: string }>(
       entity.type,
       now,
     );
-    const importance = importanceNorm(entity.importance, entity.type);
+    const importance = effectiveImportance(entity);
     const score =
       w.relevance * relevance + w.recency * recency + w.importance * importance;
     return { entity, relevance, recency, importance, score };
@@ -176,6 +276,28 @@ export function rescore<T extends ParkInput & { id?: string }>(
   return scored;
 }
 
+// ---------------------------------------------------------------------------
+// minConfidence filter (#273)
+// ---------------------------------------------------------------------------
+
+/**
+ * Keep only entities whose confidence meets the threshold. Entities with a
+ * non-numeric confidence are dropped (we can't prove they clear the bar).
+ *
+ * Pure + exported so the recall path's `minConfidence` semantics are
+ * unit-testable. Once writes set non-uniform confidence (#273), a low
+ * threshold yields a strictly smaller set than passing no threshold.
+ */
+export function filterByMinConfidence<T extends { confidence?: number | null }>(
+  entities: T[],
+  minConfidence: number | undefined,
+): T[] {
+  if (typeof minConfidence !== "number") return entities;
+  return entities.filter(
+    (e) => typeof e.confidence === "number" && e.confidence >= minConfidence,
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Rank-to-relevance helper (Phase 1 hybrid retrieval bridge)
 // ---------------------------------------------------------------------------
@@ -250,3 +372,60 @@ export function fitToBudget<
   }
   return out;
 }
+
+// ---------------------------------------------------------------------------
+// Stale / never-recalled signal (card #279, task 4)
+// ---------------------------------------------------------------------------
+
+export interface StaleUnusedInput {
+  access_count?: number | null;
+  last_accessed_at?: string | null;
+  created_at?: string | null;
+}
+
+/**
+ * Returns true when a memory has NEVER been recalled (access_count 0/absent)
+ * AND has existed longer than `thresholdDays`. SIGNAL ONLY — card #280's
+ * prune-suggestion digest consumes this to surface candidates for human
+ * review. It deletes/modifies NOTHING; non-destructive by construction.
+ *
+ * Age is measured from `created_at` (a never-recalled memory has no meaningful
+ * `last_accessed_at`; #273 only stamps it on recall). A memory that has been
+ * recalled even once is never stale-unused, regardless of age.
+ */
+export function isStaleUnused(
+  entity: StaleUnusedInput,
+  now: Date,
+  thresholdDays: number,
+): boolean {
+  const recalled =
+    typeof entity.access_count === "number" && entity.access_count > 0;
+  if (recalled) return false;
+  const createdRaw = entity.created_at ?? null;
+  if (!createdRaw) return false; // Unknown age: don't flag.
+  const created = Date.parse(createdRaw);
+  if (Number.isNaN(created)) return false;
+  const ageDays = (now.getTime() - created) / (1000 * 60 * 60 * 24);
+  return ageDays > thresholdDays;
+}
+
+// ---------------------------------------------------------------------------
+// Feedback merge (card #279, task 3) — non-destructive counter increment
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge a single 👍/👎 vote into an existing feedback counter, returning a NEW
+ * object (input is never mutated). Used by the recall-feedback record path to
+ * compute the `metadata.feedback` patch before persisting. Pure + bounded to
+ * non-negative integers.
+ */
+export function mergeFeedback(
+  existing: MemoryFeedback | null | undefined,
+  vote: "up" | "down",
+): MemoryFeedback {
+  const up =
+    typeof existing?.up === "number" && existing.up > 0 ? existing.up : 0;
+  const down =
+    typeof existing?.down === "number" && existing.down > 0 ? existing.down : 0;
+  return vote === "up" ? { up: up + 1, down } : { up, down: down + 1 };
+}

package/src/memory-provenance.ts

@@ -0,0 +1,177 @@
+/**
+ * Write-time provenance + signal-derived confidence/importance.
+ *
+ * Card #273: "Set meaningful confidence, importance & provenance at write
+ * time". Three deterministic, rule-based concerns live here (NO LLM rating —
+ * LLM-rated importance was reverted in 43782a4 for poisoning the corpus and
+ * stays deferred):
+ *
+ *   1. `MemoryOrigin` — provenance stamped into `metadata.origin`. There is no
+ *      dedicated provenance column; it rides inside the existing metadata jsonb.
+ *   2. `defaultConfidenceForSource` — source/trust-derived confidence default
+ *      used only when the caller did NOT pass an explicit confidence.
+ *   3. `importanceWithSignalBump` — per-type importance default plus a bounded
+ *      bump for signal density (file paths, "Why"/"How to apply" sections,
+ *      proper nouns). Pairs with the Park rescore so ranking differentiates.
+ *
+ * Pure and side-effect free — safe to unit test without network/DB.
+ */
+
+// ---------------------------------------------------------------------------
+// Provenance shape (task 1)
+// ---------------------------------------------------------------------------
+
+/** Where a memory came from. */
+export type MemorySource = "manual" | "assistant" | "agent-run" | "import";
+
+/**
+ * Provenance record stored at `metadata.origin`. Input for provenance badges
+ * (companion UI card) and auto-vs-curated hygiene filtering. All fields except
+ * `source` are optional so partial context still round-trips.
+ */
+export interface MemoryOrigin {
+  source: MemorySource;
+  /** Card the write originated from (uuid or short id as string). */
+  source_card_id?: string;
+  /** Agent/working-memory session that produced the write. */
+  source_session_id?: string;
+  /** Human or agent identifier that authored the memory. */
+  author?: string;
+  /**
+   * Trust hint carried through from the write call (e.g. 'document',
+   * 'manual', 'agent'). Persisted so downstream hygiene can reason about it —
+   * previously `source_trust` only reached the Floor and was dropped.
+   */
+  source_trust?: string;
+}
+
+/**
+ * Build a `MemoryOrigin`, dropping undefined fields so the stored jsonb stays
+ * compact. `source` is always present.
+ */
+export function buildOrigin(input: {
+  source: MemorySource;
+  source_card_id?: string | null;
+  source_session_id?: string | null;
+  author?: string | null;
+  source_trust?: string | null;
+}): MemoryOrigin {
+  const origin: MemoryOrigin = { source: input.source };
+  if (input.source_card_id) origin.source_card_id = input.source_card_id;
+  if (input.source_session_id)
+    origin.source_session_id = input.source_session_id;
+  if (input.author) origin.author = input.author;
+  if (input.source_trust) origin.source_trust = input.source_trust;
+  return origin;
+}
+
+// ---------------------------------------------------------------------------
+// Source-derived confidence default (task 5)
+// ---------------------------------------------------------------------------
+
+/**
+ * Default confidence by source/trust, applied ONLY when the caller omits an
+ * explicit confidence. An explicit value always wins (handled by the caller).
+ *
+ * Rule (deterministic, documented):
+ *   - manual capture (human at the keyboard): high — 0.9
+ *   - `source_trust === 'document'` import: high — 0.9 (curated long-form)
+ *   - assistant-authored (board assistant on the user's behalf): 0.8
+ *   - agent-run auto-extract / low-trust import: moderate — 0.6
+ *
+ * The point is non-uniformity: most live entities sat at 1.0, which made
+ * `minConfidence` filtering inert. Auto-written memories should start lower so
+ * a curated pattern outranks a freshly auto-extracted episode at equal
+ * relevance/recency.
+ */
+export function defaultConfidenceForSource(input: {
+  source: MemorySource;
+  source_trust?: string;
+}): number {
+  if (input.source_trust === "document") return 0.9;
+  if (input.source_trust === "manual") return 0.9;
+  switch (input.source) {
+    case "manual":
+      return 0.9;
+    case "assistant":
+      return 0.8;
+    case "agent-run":
+      return 0.6;
+    case "import":
+      return 0.6;
+    default:
+      return 0.7;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Importance signal-density bump (task 6)
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-type importance default. Mirrors the edge function `IMPORTANCE_DEFAULTS`
+ * and `memory-park.ts` `TYPE_IMPORTANCE_DEFAULT`; duplicated here so the write
+ * path doesn't import the rescorer. Values in [1,10].
+ */
+export const TYPE_IMPORTANCE_DEFAULT: Record<string, number> = {
+  preference: 9,
+  lesson: 8,
+  decision: 8,
+  pattern: 7,
+  solution: 7,
+  procedure: 7,
+  error: 5,
+  context: 5,
+  task: 5,
+  agent: 5,
+  relationship: 6,
+  commitment: 7,
+  project: 6,
+  handoff: 6,
+};
+
+// A file path / module path, e.g. `src/foo/bar.ts`, `packages/x/y`.
+const FILE_PATH =
+  /(?:[\w.-]+\/){1,}[\w.-]+\.[a-z]{1,4}\b|(?:[\w-]+\/){2,}[\w-]+/i;
+// A "Why" or "How to apply" style guidance heading.
+const GUIDANCE_SECTION =
+  /\b(why|how to apply|how to use|takeaway|root cause)\b/i;
+// A proper noun / identifier in the body (PascalCase, camelCase, snake_case,
+// or a backtick-fenced symbol).
+const PROPER_NOUN =
+  /`[^`]+`|\b[A-Z][a-z0-9]+[A-Z][A-Za-z0-9]*\b|\b[a-z]+_[a-z][\w]*\b/;
+
+/**
+ * Count distinct signal-density cues present in the content. Bounded [0,3].
+ *   +1 — contains a file/module path
+ *   +1 — contains a "Why"/"How to apply"/"Takeaway"/"Root cause" section
+ *   +1 — contains a proper noun / code identifier
+ */
+export function signalDensity(content: string): number {
+  let n = 0;
+  if (FILE_PATH.test(content)) n += 1;
+  if (GUIDANCE_SECTION.test(content)) n += 1;
+  if (PROPER_NOUN.test(content)) n += 1;
+  return n;
+}
+
+/**
+ * Importance = per-type default + bounded signal-density bump, clamped to
+ * [1,10]. Deterministic and rule-based.
+ *
+ * The bump is +1 per cue, capped at +2 total, so a dense, file-path-bearing
+ * lesson edges out a thin one of the same type — giving the Park rescore a
+ * non-flat importance term to work with. A caller-provided importance always
+ * takes precedence and never enters this function.
+ */
+export function importanceWithSignalBump(
+  type: string,
+  content: string,
+): number {
+  const base = TYPE_IMPORTANCE_DEFAULT[type] ?? 5;
+  const bump = Math.min(2, signalDensity(content));
+  const v = base + bump;
+  if (v < 1) return 1;
+  if (v > 10) return 10;
+  return v;
+}