@compr/opscontext-mcp 2.5.5 → 2.5.7

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to OpsContext for AI Agents (previously ContextEngine — MC
 
 > Entries for 2.2.0 through 2.4.0 were not backfilled here; see `docs/sessions/SESSION_19` through `SESSION_21` for those releases.
 
+## [2.5.7] — 2026-09-05 — The learnings store was a pile of headings
+
+Of 3,005 records, about 2,760 had been produced by the doc importer from ~160 ordinary docs
+(copilot-instructions, session docs, Claude memory files) and about 240 by an agent calling
+`save_learning`. In a spread sample of 70 imported records, 32 were not rules at all ("Design
+Language:", "Session 24 TODO", "Files created (Phase 1 foundation)"), and the category of the rest
+came from a section title or a substring guess: "Flow A" under mobile, "Scoring internals are trade
+secrets" under mobile because "expose" contains "expo".
+
+### Changed
+
+- **Auto-import takes only marked learnings** (`[AUTO-IMPORT-ONLY-MARKED-LEARNINGS]`): inline
+  `- [category] rule → context` bullets anywhere; every shape inside a `*LEARNINGS.md` file; every
+  shape under a heading that says learnings / lessons / gotchas / pitfalls / rules / anti-patterns /
+  "never repeat" / "the hard way"; JSON. Bare H3 headings, bold bullets and table rows in ordinary
+  docs are reported as `ignored` and left alone; the docs stay searchable as docs. Replayed over the
+  818 discovered sources: 129 records instead of 1,879. `import_learnings` gains `permissive: true`
+  and the CLI `--permissive` for a file the user chose. Imported records carry `source`.
+- **Category inference scores whole words** (`[CATEGORY-BY-WHOLE-WORD-SCORE]`): every whole-word or
+  whole-phrase match counts, rule text weighs double the context, highest total wins, ties go to the
+  more specific category, no match is `other`. Measured: 11% → 27.5% agreement on 189 agent-labelled
+  records, 25% → 50% on 84 hand-labelled rules (`scripts/measure-categories.mjs`; the sample stays
+  outside the repo). `normalizeCategory()` no longer maps "Apple App Store" to api on a prefix.
+- New default source patterns: `AGENT-LEARNINGS.md`, `docs/AGENT-LEARNINGS.md`, `LEARNINGS.md`,
+  `docs/LEARNINGS.md`.
+
+### Added
+
+- `scripts/learnings-prune.mjs <plan.json> [--apply]`: dry run by default, backup before any
+  delete, one batched write under the store lock. The 2026-09-05 plan lists 2,635 import-derived
+  records to remove (370 kept), pending the owner's GO.
+
 ## [2.4.3] — 2026-08-17 — The audit verifier called concurrency "tampering" and condemned 316k records
 
 `audit-verify` reported `❌ Audit chain BROKEN at index 2826 (of 319438)` and told the user the

package/dist/audit.d.ts

@@ -1,4 +1,4 @@
-export type AuditEvent = "learning.save" | "learning.delete" | "learning.import" | "learning.export" | "session.save" | "session.delete" | "activation.activate" | "activation.deactivate" | "activation.heartbeat" | "activation.signature_reject" | "activation.legacy_signature" | "firewall.escalate" | "hook.block" | "hook.bypass" | "policy.skipped" | "browser.prompt" | "browser.response" | "browser.tool_call" | "browser.session_start" | "browser.session_end" | "browser.capture_miss" | "vscode.prompt_submit" | "vscode.tool_call" | "vscode.session_start" | "drift.detected" | "notification.fired" | "community.sync_ok" | "community.sync_error" | "audit.rotate" | "audit.redact";
+export type AuditEvent = "learning.save" | "learning.delete" | "learning.store_unreadable" | "learning.store_shrink_refused" | "learning.import" | "learning.export" | "session.save" | "session.delete" | "activation.activate" | "activation.deactivate" | "activation.heartbeat" | "activation.signature_reject" | "activation.legacy_signature" | "firewall.escalate" | "hook.block" | "hook.bypass" | "policy.skipped" | "browser.prompt" | "browser.response" | "browser.tool_call" | "browser.session_start" | "browser.session_end" | "browser.capture_miss" | "vscode.prompt_submit" | "vscode.tool_call" | "vscode.session_start" | "drift.detected" | "notification.fired" | "community.sync_ok" | "community.sync_error" | "audit.rotate" | "audit.redact";
 export interface AuditRecord {
     ts: string;
     event: AuditEvent;

package/dist/cli.js

@@ -2269,6 +2269,7 @@ async function cliImportLearnings(args) {
     let filePath = "";
     let category = "other";
     let project;
+    let permissive = false;
     for (let i = 0; i < args.length; i++) {
         if ((args[i] === "-c" || args[i] === "--category") && args[i + 1]) {
             category = args[++i];
@@ -2276,19 +2277,25 @@ async function cliImportLearnings(args) {
         else if ((args[i] === "-p" || args[i] === "--project") && args[i + 1]) {
             project = args[++i];
         }
+        else if (args[i] === "--permissive") {
+            permissive = true;
+        }
         else if (!filePath) {
             filePath = args[i];
         }
     }
     if (!filePath) {
-        console.error("Usage: contextengine import-learnings <file.md|file.json> [-c category] [-p project]");
+        console.error("Usage: contextengine import-learnings <file.md|file.json> [-c category] [-p project] [--permissive]");
+        console.error("  Default: only marked learnings ([category] bullets, *LEARNINGS.md files, learnings/lessons/gotchas/rules sections, JSON).");
+        console.error("  --permissive: every H3 heading, bold bullet and table row too.");
         process.exit(1);
     }
-    const result = importLearningsFromFile(filePath, category, project);
+    const result = importLearningsFromFile(filePath, category, project, { permissive });
     console.log(`\n📥 Import Results:`);
     console.log(`   Imported: ${result.imported}`);
     console.log(`   Updated:  ${result.updated}`);
     console.log(`   Skipped:  ${result.skipped}`);
+    console.log(`   Ignored:  ${result.ignored} (unmarked headings/bullets/rows; --permissive imports them)`);
     if (result.errors.length > 0) {
         console.log(`   Errors:`);
         for (const err of result.errors) {

package/dist/config.js

@@ -17,6 +17,12 @@ const DEFAULT_PATTERNS = [
     "AGENTS.md",
     // Context engineering
     "CONTEXT_MAP.md",
+    // Learnings files: the only ordinary-looking docs the auto-import reads in full
+    // ([LOCK] [AUTO-IMPORT-ONLY-MARKED-LEARNINGS] in learnings.ts)
+    "AGENT-LEARNINGS.md",
+    "docs/AGENT-LEARNINGS.md",
+    "LEARNINGS.md",
+    "docs/LEARNINGS.md",
 ];
 /**
  * Look for contextengine.json in standard locations.

package/dist/index.js

@@ -956,7 +956,7 @@ server.tool("delete_learning", "Delete a learning by its ID. Use list_learnings
 // ---------------------------------------------------------------------------
 // Tool: import_learnings (Bulk Import from Files)
 // ---------------------------------------------------------------------------
-server.tool("import_learnings", "Bulk-import learnings from a Markdown or JSON file. Parses headings, bullets, and tables to extract operational rules. Supports: (1) Structured Markdown (H2=category, H3=rule, bullets=context), (2) Inline bullets with [category] prefix, (3) JSON arrays of {category, rule, context}. Deduplicates against existing learnings.", {
+server.tool("import_learnings", "Bulk-import learnings from a Markdown or JSON file. By default only MARKED learnings are imported: inline bullets with a [category] prefix, anything inside a *LEARNINGS.md file, anything under a heading that says learnings / lessons / gotchas / rules, and JSON arrays of {category, rule, context}. Set permissive=true to also import every H3 heading, bold bullet and table row (H2=category, H3=rule, bullets=context). Deduplicates against existing learnings.", {
     file_path: z
         .string()
         .describe("Absolute path to the Markdown (.md) or JSON (.json) file to import from"),
@@ -968,8 +968,12 @@ server.tool("import_learnings", "Bulk-import learnings from a Markdown or JSON f
         .string()
         .optional()
         .describe("Project name to tag all imported learnings with (e.g., 'FC_project')"),
-}, async ({ file_path, default_category, project }) => {
-    const result = importLearningsFromFile(file_path, default_category || "other", project);
+    permissive: z
+        .boolean()
+        .optional()
+        .describe("Import every heading, bold bullet and table row as a rule (the pre-2.5.7 behaviour). Default false: only marked learnings."),
+}, async ({ file_path, default_category, project, permissive }) => {
+    const result = importLearningsFromFile(file_path, default_category || "other", project, { permissive: permissive === true });
     // Re-inject learnings into search index (project-scoped)
     const newChunks = learningsToChunks(activeProjectNames);
     const nonLearningChunks = chunks.filter((c) => c.source !== "💡 Learnings Store");
@@ -981,6 +985,7 @@ server.tool("import_learnings", "Bulk-import learnings from a Markdown or JSON f
         `- **Imported:** ${result.imported} new learnings`,
         `- **Updated:** ${result.updated} existing learnings (dedup match)`,
         `- **Skipped:** ${result.skipped} entries (missing data)`,
+        `- **Ignored:** ${result.ignored} headings / bold bullets / table rows outside a learnings scope (pass permissive=true to import them)`,
         ``,
         `📊 Store total: ${stats.total} learnings across ${Object.keys(stats.categories).length} categories`,
         ``,

package/dist/learnings.d.ts

@@ -8,6 +8,8 @@ export interface Learning {
     tags: string[];
     created: string;
     updated: string;
+    /** Where an imported record came from (absolute file path). Absent on agent-saved records. */
+    source?: string;
 }
 export interface LearningsStore {
     version: number;
@@ -17,11 +19,21 @@ export interface LearningsStore {
 /** Valid categories for learnings */
 export declare const LEARNING_CATEGORIES: readonly ["deployment", "api", "database", "frontend", "backend", "devops", "security", "performance", "testing", "debugging", "tooling", "git", "dependencies", "architecture", "data", "infrastructure", "mobile", "other"];
 export type LearningCategory = (typeof LEARNING_CATEGORIES)[number];
+/** Cross-process, re-entrant (within this process) lock around the store file. */
+export declare function withStoreLock<T>(fn: () => T): T;
+/**
+ * Run `fn` with ONE load and at most ONE save of the store, under the lock. Inside, every
+ * loadStore() returns the same in-memory store and every saveStore() only marks it dirty.
+ */
+export declare function withStoreBatch<T>(fn: () => T): T;
+/** Test seam for the writer's tripwire; not part of the API. */
+export declare function __writeStoreForTests(store: LearningsStore): void;
 /**
  * Save a new learning. Returns the created learning with ID.
  * Rejects rules shorter than MIN_RULE_LENGTH and auto-corrects "other" category.
  */
-export declare function saveLearning(category: string, rule: string, context: string, project?: string): Learning;
+export declare function saveLearning(...args: Parameters<typeof saveLearningUnlocked>): Learning;
+declare function saveLearningUnlocked(category: string, rule: string, context: string, project?: string, source?: string): Learning;
 /**
  * Search learnings by keyword. Returns matches sorted by relevance.
  */
@@ -64,9 +76,23 @@ export interface ImportResult {
     imported: number;
     updated: number;
     skipped: number;
+    /** Candidates the import rule left alone: headings, bold bullets and table rows outside a learnings scope. */
+    ignored: number;
     errors: string[];
 }
-export declare function importLearningsFromFile(filePath: string, defaultCategory?: string, defaultProject?: string): ImportResult;
+export interface ImportOptions {
+    /** Import every heading, bold bullet and table row as a rule, the pre-2026-09-05 behaviour. */
+    permissive?: boolean;
+}
+export declare const LEARNINGS_FILE_NAME: RegExp;
+export declare const LEARNINGS_HEADING: RegExp;
+export declare function importLearningsFromFile(filePath: string, defaultCategory?: string, defaultProject?: string, opts?: ImportOptions): ImportResult;
+/** Score every category over rule (x2) and context (x1); the caller picks the winner. */
+export declare function scoreCategories(rule: string, context: string): Map<LearningCategory, number>;
+/** Infer a category from rule text + context. "other" only when nothing matches at all. */
+export declare function inferCategory(rule: string, context: string): LearningCategory;
+/** Map free-form heading text to the closest LEARNING_CATEGORIES value. */
+export declare function normalizeCategory(heading: string): LearningCategory;
 /**
  * Convert learnings to Chunks so they can be included in search_context.
  * This is the key integration — learnings auto-surface in hybrid search.
@@ -93,6 +119,7 @@ export declare function autoImportFromSources(sources: Array<{
     total: number;
     imported: number;
     updated: number;
+    ignored: number;
 };
 /**
  * Get the store stats.
@@ -118,4 +145,5 @@ export interface FormatLearningsOptions {
     sinceSpec?: string;
 }
 export declare function formatLearnings(learnings: Learning[], opts?: FormatLearningsOptions): string;
+export {};
 //# sourceMappingURL=learnings.d.ts.map

package/dist/learnings.js

@@ -1,6 +1,6 @@
 // LOCKED — verified March 3 2026 — learning store: quality gates, auto-categorize, dedup, project-scoped filtering
 // DO NOT RE-AUDIT — min 15 chars, inferCategory(), autoImportFromSources() all verified v1.19.1
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync, copyFileSync, rmSync, statSync, readdirSync, unlinkSync } from "fs";
 import { join, dirname } from "path";
 import { homedir } from "os";
 import { fileURLToPath } from "url";
@@ -23,7 +23,7 @@ const __dirname = dirname(__filename);
  * - "macOS sandbox blocks ~/Downloads access from VS Code terminal"
  * - "Unicode NFC vs NFD causes false mismatches on Google Drive vs APFS"
  */
-const LEARNINGS_PATH = join(homedir(), ".contextengine", "learnings.json");
+const LEARNINGS_PATH = join(process.env.CONTEXTENGINE_HOME || join(homedir(), ".contextengine"), "learnings.json");
 /** Valid categories for learnings */
 export const LEARNING_CATEGORIES = [
     "deployment",
@@ -98,17 +98,139 @@ function mergeDefaults(store) {
     }
     return added > 0;
 }
-function loadStore() {
+// [LOCKED] [STORE-NEVER-STARTS-FRESH-OVER-DATA] 2026-09-05
+// [NEVER] turn an unreadable learnings.json into an empty store, write the store with a
+//         bare writeFileSync, or let two processes write it without the lock below.
+// WHY: on 2026-09-05 (16:34Z) the whole store was rebuilt from scratch: every id
+//      replaced, every `created` reset, the save_learning-only records gone. Cause, read
+//      from the code and the audit log: every MCP server (launchd, VS Code, Claude Code)
+//      watches ~880 doc files and re-imports all of them on any change, one full-file
+//      rewrite PER RULE; with two or three servers doing that at once, one read a
+//      half-written file, `catch { start fresh }` turned it into an empty store, and the
+//      next save overwrote 2,808 records with the rebuilt set. The audit log shows 54
+//      such bursts since 2026-06-23 and 143,352 ids created for a store of ~2,800: the
+//      same race, repeatedly, and the likeliest source of the 66 audit-chain forks.
+// FIX: (1) atomic writes, temp file + rename, so a reader never sees a torn file;
+//      (2) an unreadable existing file is copied to learnings.json.corrupt-<ts> and the
+//          load THROWS, it never becomes an empty store; (3) a saved store that is less
+//          than half the on-disk one (and the disk one has >= 100 records) is refused
+//          unless CONTEXTENGINE_ALLOW_SHRINK=1; (4) a cross-process lock directory
+//          around every load-modify-save; (5) imports run as ONE batch: one load, one
+//          save, instead of one rewrite per rule; (6) a daily learnings.json.bak-YYYYMMDD
+//          before the first write of the day, last 7 kept.
+const STORE_LOCK_DIR = LEARNINGS_PATH + ".lock";
+const LOCK_STALE_MS = 30_000;
+let lockDepth = 0;
+let batchStore = null;
+let batchDirty = false;
+function sleepMs(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** Cross-process, re-entrant (within this process) lock around the store file. */
+export function withStoreLock(fn) {
+    if (lockDepth > 0) {
+        lockDepth++;
+        try {
+            return fn();
+        }
+        finally {
+            lockDepth--;
+        }
+    }
+    ensureDir();
+    const timeoutMs = parseInt(process.env.CONTEXTENGINE_LOCK_TIMEOUT_MS || "10000", 10);
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            mkdirSync(STORE_LOCK_DIR);
+            try {
+                writeFileSync(join(STORE_LOCK_DIR, "pid"), String(process.pid));
+            }
+            catch { /* diagnostics only */ }
+            break;
+        }
+        catch (e) {
+            if (e?.code !== "EEXIST")
+                throw e;
+            let age = 0;
+            try {
+                age = Date.now() - statSync(STORE_LOCK_DIR).mtimeMs;
+            }
+            catch {
+                age = 0;
+            }
+            if (age > LOCK_STALE_MS) {
+                // Holder died (or hung) without releasing: take it over.
+                try {
+                    rmSync(STORE_LOCK_DIR, { recursive: true, force: true });
+                }
+                catch { /* retry below */ }
+                continue;
+            }
+            if (Date.now() > deadline) {
+                throw new Error(`learnings store is locked by another process (${STORE_LOCK_DIR}, ${Math.round(age / 1000)}s old); refusing to write over it`);
+            }
+            sleepMs(25);
+        }
+    }
+    lockDepth = 1;
+    try {
+        return fn();
+    }
+    finally {
+        lockDepth = 0;
+        try {
+            rmSync(STORE_LOCK_DIR, { recursive: true, force: true });
+        }
+        catch { /* best effort */ }
+    }
+}
+/**
+ * Run `fn` with ONE load and at most ONE save of the store, under the lock. Inside, every
+ * loadStore() returns the same in-memory store and every saveStore() only marks it dirty.
+ */
+export function withStoreBatch(fn) {
+    if (batchStore)
+        return fn(); // already batching (re-entrant)
+    return withStoreLock(() => {
+        batchStore = readStoreFromDisk();
+        batchDirty = false;
+        try {
+            const out = fn();
+            if (batchDirty)
+                writeStoreToDisk(batchStore);
+            return out;
+        }
+        finally {
+            batchStore = null;
+            batchDirty = false;
+        }
+    });
+}
+function readStoreFromDisk() {
     let store;
     if (existsSync(LEARNINGS_PATH)) {
+        const raw = readFileSync(LEARNINGS_PATH, "utf-8");
         try {
-            store = JSON.parse(readFileSync(LEARNINGS_PATH, "utf-8"));
-            // Filter out corrupted entries missing required 'rule' field
-            store.learnings = store.learnings.filter((l) => typeof l.rule === "string" && l.rule.length > 0);
+            store = JSON.parse(raw);
+            if (!store || !Array.isArray(store.learnings))
+                throw new Error("no learnings array");
         }
-        catch {
-            // Corrupted file — start fresh
-            store = { version: 1, count: 0, learnings: [] };
+        catch (e) {
+            const keep = `${LEARNINGS_PATH}.corrupt-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+            try {
+                copyFileSync(LEARNINGS_PATH, keep);
+            }
+            catch { /* the original stays in place regardless */ }
+            safeAppend("learning.store_unreadable", { path: LEARNINGS_PATH, bytes: raw.length, kept: keep, error: String(e?.message || e) });
+            throw new Error(`${LEARNINGS_PATH} exists but is unreadable (${e?.message || e}); refusing to start fresh over it. Copy kept at ${keep}. Another process may be mid-write: retry in a moment.`);
+        }
+        // Filter out corrupted entries missing required 'rule' field; a missing or unknown
+        // category becomes "other" (two June-era records crashed list_learnings on 2026-09-05).
+        store.learnings = store.learnings.filter((l) => typeof l.rule === "string" && l.rule.length > 0);
+        for (const l of store.learnings) {
+            if (typeof l.category !== "string" || !LEARNING_CATEGORIES.includes(l.category))
+                l.category = "other";
         }
     }
     else {
@@ -116,14 +238,68 @@ function loadStore() {
     }
     // Auto-merge bundled defaults on first load or when new defaults are added
     if (mergeDefaults(store)) {
-        saveStore(store);
+        if (batchStore)
+            batchDirty = true;
+        else
+            writeStoreToDisk(store);
     }
     return store;
 }
-function saveStore(store) {
+function loadStore() {
+    if (batchStore)
+        return batchStore;
+    return readStoreFromDisk();
+}
+function dailyBackup() {
+    if (!existsSync(LEARNINGS_PATH))
+        return;
+    const day = new Date().toISOString().slice(0, 10).replace(/-/g, "");
+    const bak = `${LEARNINGS_PATH}.bak-${day}`;
+    if (existsSync(bak))
+        return;
+    try {
+        copyFileSync(LEARNINGS_PATH, bak);
+        const dir = dirname(LEARNINGS_PATH);
+        const daily = readdirSync(dir).filter((f) => /^learnings\.json\.bak-\d{8}$/.test(f)).sort();
+        for (const f of daily.slice(0, Math.max(0, daily.length - 7)))
+            unlinkSync(join(dir, f));
+    }
+    catch { /* a missing backup must never block a save */ }
+}
+function writeStoreToDisk(store) {
     ensureDir();
     store.count = store.learnings.length;
-    writeFileSync(LEARNINGS_PATH, JSON.stringify(store, null, 2));
+    // Shrink tripwire: the exact shape of the 2026-09-05 loss was a near-empty store
+    // written over a full one.
+    if (existsSync(LEARNINGS_PATH) && process.env.CONTEXTENGINE_ALLOW_SHRINK !== "1") {
+        let onDisk = -1;
+        try {
+            onDisk = (JSON.parse(readFileSync(LEARNINGS_PATH, "utf-8")).learnings || []).length;
+        }
+        catch {
+            onDisk = -1;
+        }
+        if (onDisk >= 100 && store.learnings.length < onDisk / 2) {
+            safeAppend("learning.store_shrink_refused", { on_disk: onDisk, attempted: store.learnings.length });
+            throw new Error(`refusing to write ${store.learnings.length} learnings over a store of ${onDisk}: that is the shape of a wipe, not an edit. Set CONTEXTENGINE_ALLOW_SHRINK=1 if this is deliberate.`);
+        }
+    }
+    dailyBackup();
+    const tmp = `${LEARNINGS_PATH}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, JSON.stringify(store, null, 2));
+    renameSync(tmp, LEARNINGS_PATH);
+}
+function saveStore(store) {
+    if (batchStore) {
+        batchStore = store;
+        batchDirty = true;
+        return;
+    }
+    writeStoreToDisk(store);
+}
+/** Test seam for the writer's tripwire; not part of the API. */
+export function __writeStoreForTests(store) {
+    withStoreLock(() => writeStoreToDisk(store));
 }
 /** Generate a short unique ID */
 function generateId() {
@@ -156,7 +332,10 @@ const MIN_RULE_LENGTH = 15;
  * Save a new learning. Returns the created learning with ID.
  * Rejects rules shorter than MIN_RULE_LENGTH and auto-corrects "other" category.
  */
-export function saveLearning(category, rule, context, project) {
+export function saveLearning(...args) {
+    return withStoreLock(() => saveLearningUnlocked(...args));
+}
+function saveLearningUnlocked(category, rule, context, project, source) {
     const trimmedRule = rule.trim();
     // Quality gate: reject junk rules
     if (trimmedRule.length < MIN_RULE_LENGTH) {
@@ -178,12 +357,23 @@ export function saveLearning(category, rule, context, project) {
     const existing = store.learnings.find((l) => l.category === category &&
         typeof l.rule === "string" && l.rule.toLowerCase().trim() === ruleLower);
     if (existing) {
+        // A re-import that changes nothing must leave no trace: no write, no `updated` bump,
+        // no audit event. Before 2026-09-05 every startup re-import emitted one learning.save
+        // per rule (2,000 to 5,000 events per server start) for records that did not change.
+        const newTags = extractTags(existing.rule, context, category);
+        const sameTags = JSON.stringify(newTags) === JSON.stringify(existing.tags || []);
+        const sameSource = !source || existing.source === source;
+        if (existing.context === context && (!project || existing.project === project) && sameTags && sameSource) {
+            return existing;
+        }
         // Update existing learning with new context
         existing.context = context;
         existing.updated = now;
         if (project)
             existing.project = project;
-        existing.tags = extractTags(existing.rule, context, category);
+        if (source)
+            existing.source = source;
+        existing.tags = newTags;
         saveStore(store);
         safeAppend("learning.save", {
             id: existing.id,
@@ -204,6 +394,8 @@ export function saveLearning(category, rule, context, project) {
         created: now,
         updated: now,
     };
+    if (source)
+        learning.source = source;
     store.learnings.push(learning);
     saveStore(store);
     safeAppend("learning.save", {
@@ -270,7 +462,7 @@ export function listLearnings(category, projects) {
         result = result.filter((l) => !l.project || lowerProjects.includes(l.project.toLowerCase()));
     }
     if (category) {
-        result = result.filter((l) => l.category.toLowerCase() === category.toLowerCase());
+        result = result.filter((l) => String(l.category || "other").toLowerCase() === category.toLowerCase());
     }
     return result;
 }
@@ -278,6 +470,9 @@ export function listLearnings(category, projects) {
  * Delete a learning by ID.
  */
 export function deleteLearning(id) {
+    return withStoreLock(() => deleteLearningUnlocked(id));
+}
+function deleteLearningUnlocked(id) {
     const store = loadStore();
     const index = store.learnings.findIndex((l) => l.id === id);
     if (index === -1)
@@ -293,15 +488,37 @@ export function deleteLearning(id) {
     });
     return true;
 }
-export function importLearningsFromFile(filePath, defaultCategory = "other", defaultProject) {
+// [LOCKED] [AUTO-IMPORT-ONLY-MARKED-LEARNINGS] 2026-09-05
+// [NEVER] let the auto-import (autoImportFromSources, run by every MCP server on every doc change)
+//         treat an H3 heading, a bold bullet or a table row in an ordinary doc as a learning again.
+// WHY: measured 2026-09-05 (Session 25): of 3,005 store records, about 2,760 had been produced by
+//      this importer from ~160 ordinary docs (copilot-instructions, session docs, Claude memory
+//      files) and about 240 by an agent calling save_learning. In a spread sample of 70 imported
+//      records, 32 were not rules at all ("Design Language:", "External References:", "Session 24
+//      TODO", "Files created (Phase 1 foundation)"), and the category of the rest came from a
+//      section title or a substring guess ("Flow A" under mobile). A count of headings is not a
+//      knowledge base; every one of those docs is already searchable as a doc.
+// FIX: a candidate becomes a learning only when the author marked it as one:
+//      (1) an inline-category bullet `- [category] rule → context`, anywhere;
+//      (2) any shape inside a file whose name says learnings (AGENT-LEARNINGS.md, LEARNINGS.md);
+//      (3) any shape under a heading that says learnings / lessons / gotchas / pitfalls / rules /
+//          anti-patterns / "never repeat" / "the hard way" (LEARNINGS_HEADING);
+//      (4) JSON files, which are explicit by construction.
+//      `permissive: true` (MCP `import_learnings`, CLI `--permissive`) restores the old parser for
+//      a file the user chose on purpose. Every imported record now carries `source`.
+export const LEARNINGS_FILE_NAME = /learnings?\.md$/i;
+export const LEARNINGS_HEADING = /\b(learnings?|lessons?|gotchas?|pitfalls?|anti-?patterns?|never repeat|do not repeat|don'?t repeat|the hard way|hard way|mistakes?|rules?)\b/i;
+export function importLearningsFromFile(filePath, defaultCategory = "other", defaultProject, opts = {}) {
     if (!existsSync(filePath)) {
-        return { imported: 0, updated: 0, skipped: 0, errors: [`File not found: ${filePath}`] };
+        return { imported: 0, updated: 0, skipped: 0, ignored: 0, errors: [`File not found: ${filePath}`] };
     }
     const content = readFileSync(filePath, "utf-8");
     const ext = filePath.split(".").pop()?.toLowerCase();
-    const result = ext === "json"
-        ? importFromJson(content, defaultProject)
-        : importFromMarkdown(content, defaultCategory, defaultProject);
+    const permissive = opts.permissive === true || LEARNINGS_FILE_NAME.test(filePath.split("/").pop() || "");
+    // One load, one save for the whole file. [LOCK] [STORE-NEVER-STARTS-FRESH-OVER-DATA]
+    const result = withStoreBatch(() => ext === "json"
+        ? importFromJson(content, defaultProject, filePath)
+        : importFromMarkdown(content, defaultCategory, defaultProject, { permissive, source: filePath }));
     // Aggregate event correlating the individual learning.save records emitted
     // inside the loop. Useful for compliance attribution: "this batch came from
     // file X".
@@ -312,12 +529,13 @@ export function importLearningsFromFile(filePath, defaultCategory = "other", def
         imported: result.imported,
         updated: result.updated,
         skipped: result.skipped,
+        ignored: result.ignored,
         errors: result.errors.length,
     });
     return result;
 }
-function importFromJson(content, defaultProject) {
-    const result = { imported: 0, updated: 0, skipped: 0, errors: [] };
+function importFromJson(content, defaultProject, source) {
+    const result = { imported: 0, updated: 0, skipped: 0, ignored: 0, errors: [] };
     try {
         const data = JSON.parse(content);
         const items = Array.isArray(data)
@@ -339,7 +557,7 @@ function importFromJson(content, defaultProject) {
             const store = loadStore();
             const existing = store.learnings.find((l) => l.category === cat && typeof l.rule === "string" && l.rule.toLowerCase().trim() === item.rule.toLowerCase().trim());
             try {
-                saveLearning(cat, item.rule, item.context || "", item.project || defaultProject);
+                saveLearning(cat, item.rule, item.context || "", item.project || defaultProject, source);
                 if (existing) {
                     result.updated++;
                 }
@@ -357,12 +575,26 @@ function importFromJson(content, defaultProject) {
     }
     return result;
 }
-function importFromMarkdown(content, defaultCategory, defaultProject) {
-    const result = { imported: 0, updated: 0, skipped: 0, errors: [] };
+function importFromMarkdown(content, defaultCategory, defaultProject, opts = { permissive: false }) {
+    const result = { imported: 0, updated: 0, skipped: 0, ignored: 0, errors: [] };
     const lines = content.split("\n");
     let currentCategory = defaultCategory;
     let currentRule = "";
     let currentContext = [];
+    // Learnings scope, [LOCK] [AUTO-IMPORT-ONLY-MARKED-LEARNINGS]: unmarked shapes (H3, bold bullet,
+    // table row) count as rules only inside it. Three nested levels: the whole file (permissive,
+    // learnings file name, or an H1 that says so), an H2 section, an H3 subsection.
+    let fileScope = opts.permissive;
+    let h2Scope = false;
+    let h3Scope = false;
+    const inScope = () => fileScope || h2Scope || h3Scope;
+    // A candidate that arrives outside the scope is counted and dropped, never queued.
+    function candidate(text) {
+        if (inScope())
+            currentRule = text;
+        else
+            result.ignored++;
+    }
     function flushRule() {
         if (!currentRule)
             return;
@@ -378,7 +610,7 @@ function importFromMarkdown(content, defaultCategory, defaultProject) {
         const store = loadStore();
         const existing = store.learnings.find((l) => l.category === cat && typeof l.rule === "string" && l.rule.toLowerCase().trim() === currentRule.toLowerCase().trim());
         try {
-            saveLearning(cat, currentRule, ctx, defaultProject);
+            saveLearning(cat, currentRule, ctx, defaultProject, opts.source);
             if (existing) {
                 result.updated++;
             }
@@ -394,24 +626,33 @@ function importFromMarkdown(content, defaultCategory, defaultProject) {
     }
     for (const line of lines) {
         const trimmed = line.trim();
-        // H1 — file title, skip
-        if (trimmed.startsWith("# ") && !trimmed.startsWith("## "))
+        // H1 — file title, skip; a title that says learnings puts the whole file in scope
+        if (trimmed.startsWith("# ") && !trimmed.startsWith("## ")) {
+            if (LEARNINGS_HEADING.test(trimmed.slice(2)))
+                fileScope = true;
             continue;
+        }
         // H2 — category (e.g., "## deployment" or "## Security & Server Administration")
         if (trimmed.startsWith("## ")) {
             flushRule();
             const heading = trimmed.replace(/^##\s+/, "").toLowerCase().trim();
             currentCategory = heading;
+            h2Scope = LEARNINGS_HEADING.test(heading);
+            h3Scope = false;
             continue;
         }
-        // H3 — rule (e.g., "### Never docker build | tee")
+        // H3 — rule (e.g., "### Never docker build | tee"), or a subsection that says learnings
         if (trimmed.startsWith("### ")) {
             flushRule();
-            const candidate = trimmed.replace(/^###\s+/, "").trim();
-            // Quality filter: skip short headings ("Fix", "UI", "DB")
-            if (candidate.length >= MIN_RULE_LENGTH) {
-                currentRule = candidate;
+            h3Scope = false; // an H3 subsection ends at the next H3
+            const text = trimmed.replace(/^###\s+/, "").trim();
+            if (!inScope() && LEARNINGS_HEADING.test(text)) {
+                h3Scope = true; // "### Lessons learned" opens a scope; the heading itself is not a rule
+                continue;
             }
+            // Quality filter: skip short headings ("Fix", "UI", "DB")
+            if (text.length >= MIN_RULE_LENGTH)
+                candidate(text);
             continue;
         }
         // H4+ — sub-rule, treat as context for current rule
@@ -429,18 +670,19 @@ function importFromMarkdown(content, defaultCategory, defaultProject) {
             currentCategory = cat;
             // Split on → or — for rule/context separation
             const sepMatch = rest.match(/^(.+?)(?:\s*[→—]\s*|\s+[-–]\s+)(.+)$/);
+            // Marked by its author: imported in every mode. [LOCK] [AUTO-IMPORT-ONLY-MARKED-LEARNINGS]
             if (sepMatch) {
-                const candidate = sepMatch[1].trim();
-                if (candidate.length >= MIN_RULE_LENGTH) {
-                    currentRule = candidate;
+                const text = sepMatch[1].trim();
+                if (text.length >= MIN_RULE_LENGTH) {
+                    currentRule = text;
                     currentContext = [sepMatch[2].trim()];
                     flushRule();
                 }
             }
             else {
-                const candidate = rest.trim();
-                if (candidate.length >= MIN_RULE_LENGTH) {
-                    currentRule = candidate;
+                const text = rest.trim();
+                if (text.length >= MIN_RULE_LENGTH) {
+                    currentRule = text;
                     flushRule();
                 }
             }
@@ -450,11 +692,13 @@ function importFromMarkdown(content, defaultCategory, defaultProject) {
         const tableMatch = trimmed.match(/^\|\s*\*\*(.+?)\*\*\s*\|(.+)\|(.+)\|/);
         if (tableMatch) {
             flushRule();
-            const candidate = tableMatch[1].trim();
-            if (candidate.length >= MIN_RULE_LENGTH) {
-                currentRule = candidate;
-                currentContext = [tableMatch[2].trim() + " — " + tableMatch[3].trim()];
-                flushRule();
+            const text = tableMatch[1].trim();
+            if (text.length >= MIN_RULE_LENGTH) {
+                candidate(text);
+                if (currentRule) {
+                    currentContext = [tableMatch[2].trim() + " — " + tableMatch[3].trim()];
+                    flushRule();
+                }
             }
             continue;
         }
@@ -464,13 +708,13 @@ function importFromMarkdown(content, defaultCategory, defaultProject) {
             flushRule();
             const boldMatch = trimmed.match(/^[-*]\s+\*\*(.+?)\*\*\s*(.*)$/);
             if (boldMatch) {
-                const candidate = boldMatch[1].trim();
+                const text = boldMatch[1].trim();
                 // Quality filter: skip short/single-word headings
-                if (candidate.length < MIN_RULE_LENGTH) {
+                if (text.length < MIN_RULE_LENGTH) {
                     continue;
                 }
-                currentRule = candidate;
-                if (boldMatch[2]) {
+                candidate(text);
+                if (currentRule && boldMatch[2]) {
                     // Strip leading separators
                     currentContext = [boldMatch[2].replace(/^[\s—→:]+/, "").trim()];
                 }
@@ -492,117 +736,195 @@ function importFromMarkdown(content, defaultCategory, defaultProject) {
     flushRule(); // Flush last rule
     return result;
 }
-/** Infer a category from rule text + context when "other" is provided */
-function inferCategory(rule, context) {
-    const text = `${rule} ${context}`.toLowerCase();
-    const keywords = {
-        "deploy": "deployment", "rsync": "deployment", "publish": "deployment", "release": "deployment",
-        "ci/cd": "devops", "ci cd": "devops", "pipeline": "devops", "github actions": "devops", "docker": "devops",
-        "nginx": "infrastructure", "ssl": "infrastructure", "server": "infrastructure", "pm2": "infrastructure", "vps": "infrastructure",
-        "api": "api", "endpoint": "api", "rest": "api", "graphql": "api", "webhook": "api",
-        "sql": "database", "sqlite": "database", "mysql": "database", "postgres": "database", "query": "database", "migration": "database",
-        "react": "frontend", "vue": "frontend", "css": "frontend", "html": "frontend", "dom": "frontend", "component": "frontend", "ui": "frontend",
-        "express": "backend", "node": "backend", "flask": "backend", "middleware": "backend",
-        "auth": "security", "cors": "security", "xss": "security", "csrf": "security", "helmet": "security", "encrypt": "security", "password": "security",
-        "test": "testing", "vitest": "testing", "jest": "testing", "spec": "testing", "assert": "testing",
-        "debug": "debugging", "error": "debugging", "stack trace": "debugging", "breakpoint": "debugging", "log": "debugging",
-        "npm": "dependencies", "package": "dependencies", "yarn": "dependencies", "pnpm": "dependencies", "version": "dependencies",
-        "git": "git", "commit": "git", "branch": "git", "merge": "git", "rebase": "git",
-        "perf": "performance", "latency": "performance", "cache": "performance", "optimize": "performance",
-        "eslint": "tooling", "lint": "tooling", "prettier": "tooling", "vscode": "tooling", "editor": "tooling",
-        "pattern": "architecture", "refactor": "architecture", "module": "architecture", "design": "architecture",
-        "ios": "mobile", "android": "mobile", "expo": "mobile", "react native": "mobile",
-    };
-    for (const [keyword, cat] of Object.entries(keywords)) {
-        if (text.includes(keyword))
-            return cat;
+// [LOCKED] [CATEGORY-BY-WHOLE-WORD-SCORE] 2026-09-05
+// [NEVER] go back to a first-hit `text.includes(keyword)` over an unanchored substring list,
+//         in inferCategory() or in normalizeCategory().
+// WHY: measured 2026-09-05 (Session 25) on 189 store records whose category an agent had
+//      chosen by hand: 21 correct, 11%. "expose" matched "expo" (mobile), "access" matched
+//      "css" (frontend), "restart" matched "rest" (api), "build" matched "ui", "login" matched
+//      "log" (debugging), and the FIRST hit won whatever the rest of the text said, so
+//      "Scoring internals are trade secrets, don't expose point values" was filed under mobile.
+// FIX: whole-word and whole-phrase matches only; every match counts; a match in the rule text
+//      weighs double a match in the context; the highest total wins; ties go to the more
+//      specific category (CATEGORY_TIE_ORDER); no match at all is "other", never a guess.
+//      Regression floors in src/learnings-category.test.ts against tests/fixtures/category-labels.json.
+/** Terms per category. Single words match as whole tokens, phrases as whole phrases. */
+const CATEGORY_TERMS = {
+    deployment: ["deploy", "deploys", "deployed", "deploying", "deployment", "deployments", "rsync",
+        "scp", "publish", "published", "publishing", "release", "releases", "released", "rollout",
+        "rollback", "ship", "shipped", "shipping", "go live", "go-live", "cutover", "staging",
+        "production", "prod", "tarball", "npm publish", "verify-release", "preflight", "hotfix",
+        "live-verify"],
+    devops: ["ci", "ci/cd", "cicd", "pipeline", "pipelines", "github actions", "workflow",
+        "workflows", "docker", "dockerfile", "container", "containers", "compose", "kubernetes", "k8s",
+        "cron", "crontab", "launchd", "scheduler", "scheduled", "automation", "automated",
+        "orchestration"],
+    infrastructure: ["nginx", "apache", "ssl", "tls", "certificate", "certificates", "letsencrypt",
+        "server", "servers", "vps", "pm2", "ssh", "dns", "domain", "domains", "firewall", "ufw",
+        "fail2ban", "systemd", "backup", "backups", "restore", "disk", "ovh", "gandi", "hosting",
+        "smtp", "cloudflare", "proxy", "reverse proxy", "load balancer", "uptime", "monitoring", "ram",
+        "cpu", "swap", "reboot", "restart", "restarted", "daemon",
+        "box", "machine", "process", "processes", "host", "hosts"],
+    api: ["api", "apis", "endpoint", "endpoints", "rest", "graphql", "webhook", "webhooks", "route",
+        "routes", "router", "request", "requests", "response", "responses", "http", "https",
+        "status code", "payload", "rate limit", "rate-limit", "throttle", "throttling", "header",
+        "headers", "url", "urls", "fetch", "axios", "curl", "openapi", "swagger"],
+    database: ["sql", "sqlite", "mysql", "postgres", "postgresql", "mongodb", "mongo", "mongoose",
+        "query", "queries", "migration", "migrations", "schema", "table", "tables", "column", "columns",
+        "collection", "collections", "aggregate", "redis", "orm", "sqlalchemy", "prisma", "eloquent",
+        "transaction", "transactions", "row", "rows", "db", "database", "databases", "pg_dump",
+        "setval", "primary key", "foreign key", "upsert", "insert",
+        "index", "indexes", "join", "select", "sequence", "dump"],
+    frontend: ["react", "vue", "svelte", "css", "html", "dom", "component", "components", "ui", "ux",
+        "jsx", "tsx", "tailwind", "vite", "webpack", "render", "renders", "rendering", "rendered",
+        "page", "pages", "button", "buttons", "modal", "chip", "chips", "localstorage", "browser",
+        "usestate", "useeffect", "spinner", "layout", "responsive", "widget", "widgets", "form",
+        "forms", "click", "scroll", "font", "fonts", "color", "colors", "colour", "colours", "contrast",
+        "display", "screen", "screens", "frontend", "front-end", "pwa", "service worker", "bundle",
+        "hydration"],
+    backend: ["express", "node", "nodejs", "flask", "fastapi", "django", "laravel", "php", "python",
+        "middleware", "uvicorn", "gunicorn", "worker", "workers", "queue", "queues", "controller",
+        "controllers", "service", "services", "artisan", "i18n", "server-side", "backend", "back-end",
+        "handler", "handlers", "model", "models", "trait", "setdefault", "asyncio", "celery",
+        "cache_key"],
+    security: ["auth", "authentication", "authorization", "oauth", "jwt", "token", "tokens", "cors",
+        "xss", "csrf", "helmet", "encrypt", "encrypted", "encryption", "password", "passwords",
+        "passkey", "passkeys", "webauthn", "credential", "credentials", "secret", "secrets", "vault",
+        "permission", "permissions", "tenant", "isolation", "rbac", "hash", "hashed", "injection",
+        "sanitize", "sanitise", "vulnerability", "vulnerabilities", "cve", "exposed", "expose",
+        "cookie", "cookies", "login", "logout", "signin", "sign-in", "2fa", "mfa", "otp", "magic code",
+        "allowlist", "whitelist", "trade secret", "trade secrets", "lockout",
+        "origin", "leak", "leaks", "leaked"],
+    performance: ["perf", "performance", "latency", "cache", "cached", "caching", "optimize",
+        "optimise", "optimization", "optimisation", "slow", "slower", "bottleneck", "bottlenecks",
+        "throughput", "memory leak", "n+1", "benchmark", "loop invariant", "nested loop", "timeout",
+        "timeouts", "concurrency", "batch size",
+        "parallel", "expensive"],
+    testing: ["test", "tests", "testing", "tested", "vitest", "jest", "pytest", "spec", "specs",
+        "assert", "assertion", "assertions", "mock", "mocks", "mocked", "fixture", "fixtures", "e2e",
+        "end-to-end", "headless", "playwright", "cypress", "test suite", "regression", "tdd", "green",
+        "red", "smoke", "smoke test", "collect", "collected", "harness", "canary"],
+    debugging: ["debug", "debugging", "error", "errors", "stack trace", "traceback", "breakpoint",
+        "log", "logs", "logging", "diagnose", "diagnosis", "diagnostic", "diagnostics", "symptom",
+        "symptoms", "crash", "crashes", "crashed", "hang", "hangs", "freeze", "frozen", "root cause",
+        "reproduce", "repro", "bug", "bugs", "silent", "silently", "off-by-one", "stale",
+        "wrong", "invisible"],
+    tooling: ["eslint", "lint", "linter", "prettier", "vscode", "vs code", "editor", "cli", "script",
+        "scripts", "shell", "bash", "zsh", "terminal", "claude code", "agent", "agents", "subagent",
+        "subagents", "mcp", "extension", "plugin", "plugins", "tsc", "compiler", "formatter",
+        "makefile", "pipefail", "set -e", "grep", "sed", "regex", "quoting", "command", "commands",
+        "flag", "flags", "dry run", "dry-run", "--check", "prompt", "prompts", "transcript",
+        "transcripts", "copilot"],
+    git: ["git", "commit", "commits", "committed", "branch", "branches", "merge", "merged", "rebase",
+        "push", "pushed", "pull", "pull request", "pr", "prs", "checkout", "stash", "cherry-pick",
+        "no-verify", "--no-verify", "pre-commit", "post-commit", "pre-push", "post-push", "gitignore",
+        ".gitignore", "git push", "git pull", "bare repo", "worktree", "revert", "squash",
+        "history", "remote", "remotes", "tag", "tags", "conflict", "conflicts", "hook", "hooks"],
+    dependencies: ["npm", "package", "packages", "yarn", "pnpm", "pip", "composer", "dependency",
+        "dependencies", "upgrade", "upgraded", "semver", "lockfile", "package.json", "node_modules",
+        "requirements.txt", "sdk", "pubspec", "peer dependency", "bump", "bumped", "outdated", "npx",
+        "version", "versions", "install", "installed", "pin", "pinned", "pinning"],
+    architecture: ["pattern", "patterns", "refactor", "refactoring", "module", "modules", "design",
+        "architecture", "single source of truth", "coupling", "boundary", "boundaries", "abstraction",
+        "interface", "interfaces", "layer", "layers", "event bus", "invariant", "invariants", "guard",
+        "guards", "contract", "contracts", "decision", "decisions", "encode", "encoded", "absence",
+        "unknown", "responsibility", "coupled", "decoupled",
+        "trace", "structure", "structural"],
+    data: ["csv", "dataset", "datasets", "data", "categoriser", "categorizer", "categorisation",
+        "categorization", "taxonomy", "parse", "parser", "parsed", "encoding", "unicode", "nfc", "nfd",
+        "dedup", "deduplicate", "normalization", "normalisation", "etl", "classifier", "verdict",
+        "verdicts", "denominator", "nutri-score", "catalog", "catalogue", "spreadsheet", "excel",
+        "count", "counts", "figure", "figures", "json", "product", "products", "field", "fields", "label", "labels", "labelled", "coverage", "metric", "metrics", "import", "imports", "export", "exports", "record", "records"],
+    mobile: ["ios", "android", "expo", "react native", "flutter", "dart", "swift", "kotlin", "xcode",
+        "app store", "play store", "google play", "testflight", "apk", "aab", "ipa", "riverpod",
+        "app store connect", "simulator", "emulator", "mobile", "gradle", "cocoapods", "pod", "pods",
+        "mainactivity", "flutterfragmentactivity", "flutteractivity", "revenuecat", "subscription",
+        "subscriptions", "guideline", "review team", "samsung", "iphone", "device", "devices",
+        "widget tree"],
+};
+/** Unambiguous technology names: one occurrence outweighs two generic words. */
+const STRONG_TERMS = new Set([
+    "rsync", "docker", "dockerfile", "kubernetes", "nginx", "fail2ban", "ufw", "pm2", "letsencrypt",
+    "graphql", "webhook", "webhooks", "endpoint", "endpoints", "sqlite", "mysql", "postgres", "postgresql",
+    "mongodb", "mongoose", "sqlalchemy", "prisma", "eloquent", "pg_dump", "react", "vue", "svelte",
+    "tailwind", "usestate", "useeffect", "localstorage", "express", "flask", "fastapi", "django", "laravel",
+    "uvicorn", "gunicorn", "artisan", "jwt", "csrf", "xss", "webauthn", "passkey", "passkeys", "oauth",
+    "vitest", "jest", "pytest", "playwright", "cypress", "stack trace", "traceback", "eslint", "prettier",
+    "vscode", "vs code", "rebase", "cherry-pick", "no-verify", "--no-verify", "pre-commit", "gitignore",
+    "npm", "yarn", "pnpm", "pip", "composer", "semver", "package.json", "node_modules", "csv", "unicode",
+    "flutter", "dart", "swift", "kotlin", "xcode", "testflight", "apk", "aab", "ipa", "riverpod", "expo",
+    "react native", "app store", "play store", "google play", "app store connect", "pubspec",
+    "single source of truth", "n+1", "memory leak", "loop invariant", "github actions", "trade secret",
+    "trade secrets", "git push", "git pull", "pull request", "mongo", "redis", "migration", "migrations",
+]);
+/** When two categories tie, the earlier one wins: the more specific before the more generic. */
+const CATEGORY_TIE_ORDER = [
+    "mobile", "database", "security", "git", "testing", "deployment", "api", "devops", "infrastructure",
+    "frontend", "backend", "performance", "dependencies", "data", "tooling", "debugging", "architecture",
+];
+function normalizeForMatch(text) {
+    // Lowercase; every run of characters outside [a-z0-9+#./_-] becomes one space, so a term like
+    // "ci/cd", "n+1", "--no-verify" or "package.json" survives as a phrase, and word boundaries
+    // become spaces. Padded with spaces so a term can be looked up as " term ".
+    return " " + text.toLowerCase().replace(/[^a-z0-9+#./_-]+/g, " ").trim() + " ";
+}
+/** Whole-word / whole-phrase occurrence check on a normalised string. */
+function hasTerm(normalized, term) {
+    return normalized.includes(` ${term} `);
+}
+/** Score every category over rule (x2) and context (x1); the caller picks the winner. */
+export function scoreCategories(rule, context) {
+    const r = normalizeForMatch(rule);
+    const c = normalizeForMatch(context || "");
+    const scores = new Map();
+    for (const [cat, terms] of Object.entries(CATEGORY_TERMS)) {
+        let s = 0;
+        for (const term of terms) {
+            const w = STRONG_TERMS.has(term) ? 2 : 1;
+            if (hasTerm(r, term))
+                s += 2 * w;
+            else if (hasTerm(c, term))
+                s += w;
+        }
+        if (s > 0)
+            scores.set(cat, s);
+    }
+    return scores;
+}
+/** Infer a category from rule text + context. "other" only when nothing matches at all. */
+export function inferCategory(rule, context) {
+    const scores = scoreCategories(rule, context);
+    let best = "other";
+    let bestScore = 0;
+    for (const cat of CATEGORY_TIE_ORDER) {
+        const s = scores.get(cat) || 0;
+        if (s > bestScore) {
+            best = cat;
+            bestScore = s;
+        }
     }
-    return "other";
+    return best;
 }
-/** Map free-form heading text to closest LEARNING_CATEGORIES value */
-function normalizeCategory(heading) {
-    const h = heading.toLowerCase().replace(/[^a-z0-9\s]/g, " ").trim();
-    // Direct match
+/** Map free-form heading text to the closest LEARNING_CATEGORIES value. */
+export function normalizeCategory(heading) {
+    const h = normalizeForMatch(heading);
+    // A heading that IS a category name ("## deployment", "## Testing") maps directly.
     for (const cat of LEARNING_CATEGORIES) {
-        if (h === cat || h.startsWith(cat))
+        if (h.trim() === cat)
             return cat;
     }
-    // Keyword mapping
-    const map = {
-        "deploy": "deployment",
-        "ci/cd": "devops",
-        "ci cd": "devops",
-        "pipeline": "devops",
-        "docker": "devops",
-        "nginx": "infrastructure",
-        "server": "infrastructure",
-        "hosting": "infrastructure",
-        "ssl": "security",
-        "cors": "security",
-        "auth": "security",
-        "malware": "security",
-        "hack": "security",
-        "hardening": "security",
-        "terminal": "tooling",
-        "command": "tooling",
-        "monitoring": "tooling",
-        "vs code": "tooling",
-        "test": "testing",
-        "jest": "testing",
-        "spec": "testing",
-        "debug": "debugging",
-        "bug": "debugging",
-        "fix": "debugging",
-        "react": "frontend",
-        "vue": "frontend",
-        "css": "frontend",
-        "ui": "frontend",
-        "laravel": "backend",
-        "django": "backend",
-        "flask": "backend",
-        "express": "backend",
-        "mysql": "database",
-        "postgres": "database",
-        "sql": "database",
-        "migration": "database",
-        "npm": "dependencies",
-        "composer": "dependencies",
-        "pip": "dependencies",
-        "package": "dependencies",
-        "git": "git",
-        "commit": "git",
-        "branch": "git",
-        "hook": "git",
-        "perf": "performance",
-        "speed": "performance",
-        "cache": "performance",
-        "mobile": "mobile",
-        "expo": "mobile",
-        "flutter": "mobile",
-        "react native": "mobile",
-        "swift": "mobile",
-        "pattern": "architecture",
-        "design": "architecture",
-        "struct": "architecture",
-        "data type": "data",
-        "csv": "data",
-        "import": "data",
-        "export": "data",
-        "api": "api",
-        "endpoint": "api",
-        "rest": "api",
-        "smtp": "infrastructure",
-        "email": "infrastructure",
-        "queue": "infrastructure",
-        "audit": "security",
-        "version": "dependencies",
-        "upgrade": "dependencies",
-    };
-    for (const [keyword, cat] of Object.entries(map)) {
-        if (h.includes(keyword))
+    // A few heading words that the term lists do not carry as rule vocabulary.
+    const headingWords = [
+        ["lessons", "other"], ["learnings", "other"], ["gotchas", "other"],
+        ["hardening", "security"], ["malware", "security"], ["audit", "security"],
+        ["terminal", "tooling"], ["commands", "tooling"], ["monitoring", "infrastructure"],
+        ["bugs", "debugging"], ["fixes", "debugging"], ["speed", "performance"],
+    ];
+    for (const [word, cat] of headingWords) {
+        if (hasTerm(h, word))
             return cat;
     }
-    return "other";
+    return inferCategory(heading, "");
 }
 /**
  * Convert learnings to Chunks so they can be included in search_context.
@@ -649,22 +971,29 @@ export function learningsToChunks(projects) {
 export function autoImportFromSources(sources) {
     let totalImported = 0;
     let totalUpdated = 0;
+    let totalIgnored = 0;
     let processed = 0;
-    for (const source of sources) {
-        // Only process markdown files
-        if (!source.path.endsWith(".md"))
-            continue;
-        if (!existsSync(source.path))
-            continue;
-        // Extract project name from source name (e.g., "ContextEngine — copilot-instructions.md")
-        const project = source.name.split(" — ")[0]?.trim() || undefined;
-        const result = importLearningsFromFile(source.path, "other", project);
-        totalImported += result.imported;
-        totalUpdated += result.updated;
-        if (result.imported > 0 || result.updated > 0)
-            processed++;
-    }
-    return { total: processed, imported: totalImported, updated: totalUpdated };
+    // One load and one save for the whole sweep (~880 files), instead of one full-file
+    // rewrite per rule per file. [LOCK] [STORE-NEVER-STARTS-FRESH-OVER-DATA]
+    withStoreBatch(() => {
+        for (const source of sources) {
+            // Only process markdown files
+            if (!source.path.endsWith(".md"))
+                continue;
+            if (!existsSync(source.path))
+                continue;
+            // Extract project name from source name (e.g., "ContextEngine — copilot-instructions.md")
+            const project = source.name.split(" — ")[0]?.trim() || undefined;
+            // Strict by construction: only marked learnings. [LOCK] [AUTO-IMPORT-ONLY-MARKED-LEARNINGS]
+            const result = importLearningsFromFile(source.path, "other", project);
+            totalImported += result.imported;
+            totalUpdated += result.updated;
+            totalIgnored += result.ignored;
+            if (result.imported > 0 || result.updated > 0)
+                processed++;
+        }
+    });
+    return { total: processed, imported: totalImported, updated: totalUpdated, ignored: totalIgnored };
 }
 /**
  * Get the store stats.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compr/opscontext-mcp",
-  "version": "2.5.5",
+  "version": "2.5.7",
   "description": "OpsContext for AI Agents — read-only fleet visibility (PM2/nginx/Docker/git/cron) + tamper-evident audit log + policy-as-code hooks. The ops + compliance layer Claude Code can't grow natively.",
   "type": "module",
   "main": "dist/index.js",
@@ -18,7 +18,8 @@
     "test:watch": "vitest",
     "lint": "eslint src/",
     "prepublishOnly": "node scripts/check-npm-token-expiry.mjs && npm run build && node scripts/obfuscate-rubric.mjs",
-    "check-token": "node scripts/check-npm-token-expiry.mjs"
+    "check-token": "node scripts/check-npm-token-expiry.mjs",
+    "verify-release": "bash scripts/verify-release.sh"
   },
   "keywords": [
     "mcp",