feat(mcp): P2 hygiene — honest category suggestions, skill-reference lint, cadence copy (#882)

* feat(mcp): counterparty-tied category suggestions + no_signal (P2-1)

suggest_categories padded every transaction with a company-wide
category-frequency fallback at <=0.5 confidence — an identical four-way
spread on 20+/24 items that agents correctly reported as pure noise
(agent.feedback). Real signal came from memory atoms and query_journal.

- History is now counterparty-keyed: buildMerchantHistory groups past
  categorized transactions by normalized merchant; the engine only
  surfaces history for THIS transaction's merchant, with provenance
  ('Bokförd N gånger tidigare för denna motpart') and occurrence-scaled
  confidence (0.56 at 1x, capped 0.85). No global padding — an empty
  list is the honest answer.
- The MCP tool returns no_signal_transaction_ids for transactions where
  NO source matched, steering agents to investigate (query_journal)
  instead of pattern-matching on unrelated rows.
- Both callers (REST suggest-categories route + MCP tool) share the new
  helpers, so web UI and agents improve together.

Part of dev_docs/mcp_optimization_plan.md (P2-1).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* feat(skills): dangling-reference validation in skills:check + fix 10 dangling links (P2-2)

skills:generate/check now fail when an atom SKILL.md links a
references/*.md that does not exist on disk — a dangling pointer ships
a 404 to every agent that follows it (the weekly-booking-check
incident, agent.feedback).

The validator immediately caught 10 live dangling links in 4 atoms,
three distinct flavors:
- filename typo: swedish-asset-accounting/references/depreciaton.md
  renamed to depreciation.md (the link was right, the file misspelled)
- link mismatch: swedish-e-invoicing linked market-providers-pricing.md;
  the file is market-provider-pricing.md (link fixed)
- unauthored plans: single-shareholder-ab-fmb TODOs and reklambyra's
  'planerad utbyggnad' section used resolvable references/ paths for
  files that were never written — rephrased as plans without paths

Seed migration regenerated (4 atoms bumped, renamed reference child).

Part of dev_docs/mcp_optimization_plan.md (P2-2).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(events): align agent-feedback review cadence copy (P2-4)

gnubok_feedback replies 'we aggregate signal weekly'; the event-log
handler comment said quarterly. One of them was lying — weekly wins
(the mcp_optimization_plan triage is the living example).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

lib/events/handlers/event-log-handler.ts

@@ -53,7 +53,8 @@ const PERSISTED_EVENT_TYPES: CoreEventType[] = [
   // whether a loaded atom helps or hurts.
   'mcp.skill_loaded',
   // Agent self-reported feedback — surfaces "this tool was missing", "this
-  // description was wrong", etc. Quarterly review → roadmap.
+  // description was wrong", etc. Reviewed weekly (matches the gnubok_feedback
+  // reply copy); triage → dev_docs/mcp_optimization_plan.md.
   'agent.feedback',
   // Bank connection consent lifecycle — required audit trail per ASVS V16
   // and GDPR Art.30 (records of processing) for PSD2 consent decisions.

lib/transactions/__tests__/category-suggestions.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from 'vitest'
+import {
+  buildMerchantHistory,
+  getSuggestedCategories,
+  merchantHistoryFor,
+} from '../category-suggestions'
+import type { Transaction } from '@/types'
+
+/**
+ * P2-1 (mcp_optimization_plan): suggestions must carry signal tied to THIS
+ * transaction. The old company-wide frequency fallback emitted an identical
+ * ~0.5 four-way spread on every transaction — noise agents correctly
+ * distrusted. History is now counterparty-keyed with provenance; when no
+ * source matches, the honest answer is an empty list.
+ */
+
+const tx = (overrides: Partial<Transaction> = {}): Transaction =>
+  ({
+    id: 'tx-1',
+    company_id: 'company-1',
+    date: '2026-06-01',
+    description: 'KORTKÖP POLARN O PYRET',
+    amount: -500,
+    currency: 'SEK',
+    merchant_name: 'Polarn O. Pyret',
+    ...overrides,
+  }) as Transaction
+
+describe('buildMerchantHistory / merchantHistoryFor', () => {
+  const rows = [
+    { merchant_name: 'Polarn O. Pyret', category: 'expense_office' },
+    { merchant_name: 'polarn o. pyret', category: 'expense_office' },
+    { merchant_name: 'Polarn O. Pyret', category: 'expense_consumables' },
+    { merchant_name: 'DNB Bank', category: 'expense_bank_fees' },
+    { merchant_name: null, category: 'expense_other' },
+    { merchant_name: 'Ghost AB', category: null },
+  ]
+
+  it('groups case-insensitively by merchant and ignores null merchants/categories', () => {
+    const map = buildMerchantHistory(rows)
+    expect(merchantHistoryFor(map, 'POLARN O. PYRET')).toEqual({
+      expense_office: 2,
+      expense_consumables: 1,
+    })
+    expect(merchantHistoryFor(map, 'DNB Bank')).toEqual({ expense_bank_fees: 1 })
+    expect(merchantHistoryFor(map, 'Unknown Vendor')).toEqual({})
+    expect(merchantHistoryFor(map, null)).toEqual({})
+  })
+})
+
+describe('getSuggestedCategories — counterparty history', () => {
+  it('returns an empty list (not a fabricated spread) when nothing matches', () => {
+    const result = getSuggestedCategories(
+      tx({ merchant_name: 'Helt Okänd Motpart', description: 'XYZ 123' }),
+      [],
+      {},
+    )
+    expect(result).toEqual([])
+  })
+
+  it('surfaces merchant history with provenance and occurrence-scaled confidence', () => {
+    const result = getSuggestedCategories(tx({ description: 'XYZ 123' }), [], {
+      expense_office: 3,
+      expense_consumables: 1,
+    })
+    expect(result.length).toBe(2)
+    expect(result[0]).toMatchObject({
+      category: 'expense_office',
+      source: 'history',
+      confidence: Math.min(0.85, 0.5 + 3 * 0.06),
+    })
+    expect(result[0].match_reason).toMatch(/3 gånger tidigare för denna motpart/)
+    expect(result[1].category).toBe('expense_consumables')
+    expect(result[1].match_reason).toMatch(/1 gång tidigare/)
+  })
+
+  it('caps history confidence at 0.85', () => {
+    const result = getSuggestedCategories(tx({ description: 'XYZ 123' }), [], {
+      expense_office: 50,
+    })
+    expect(result[0].confidence).toBe(0.85)
+  })
+
+  it('filters history to the transaction direction', () => {
+    const result = getSuggestedCategories(
+      tx({ amount: 1000, description: 'XYZ 123' }), // income direction
+      [],
+      { expense_office: 5 },
+    )
+    expect(result).toEqual([])
+  })
+})

lib/transactions/category-suggestions.ts

@@ -34,13 +34,51 @@ const CATEGORY_LABELS: Record<string, string> = {
 }
 
 /**
- * Get suggested categories for a transaction
- * Combines mapping rules, pattern matching, and user history
+ * Counterparty-keyed history: normalized merchant name -> category counts.
+ * Built once per request from the caller's recent categorized transactions.
+ */
+export type MerchantHistoryMap = Map<string, Record<string, number>>
+
+function normalizeMerchantKey(name: string | null | undefined): string {
+  return (name ?? '').toLowerCase().trim()
+}
+
+export function buildMerchantHistory(
+  rows: Array<{ merchant_name: string | null; category: string | null }>,
+): MerchantHistoryMap {
+  const map: MerchantHistoryMap = new Map()
+  for (const row of rows) {
+    const key = normalizeMerchantKey(row.merchant_name)
+    if (!key || !row.category) continue
+    const bucket = map.get(key) ?? {}
+    bucket[row.category] = (bucket[row.category] || 0) + 1
+    map.set(key, bucket)
+  }
+  return map
+}
+
+export function merchantHistoryFor(
+  map: MerchantHistoryMap,
+  merchantName: string | null | undefined,
+): Record<string, number> {
+  const key = normalizeMerchantKey(merchantName)
+  return key ? (map.get(key) ?? {}) : {}
+}
+
+/**
+ * Get suggested categories for a transaction.
+ * Combines mapping rules, pattern matching, and counterparty history.
+ *
+ * merchantHistory is the category history FOR THIS TRANSACTION'S counterparty
+ * (see buildMerchantHistory/merchantHistoryFor) — never a company-wide
+ * frequency map. Global padding produced identical ~0.5 four-way spreads on
+ * every transaction, which agents correctly read as no signal
+ * (mcp_optimization_plan P2-1); an empty result is the honest answer.
  */
 export function getSuggestedCategories(
   transaction: Transaction,
   mappingRules: MappingRule[],
-  categoryHistory: Record<string, number>
+  merchantHistory: Record<string, number>
 ): SuggestedCategory[] {
   const suggestions: SuggestedCategory[] = []
   const seen = new Set<string>()
@@ -104,8 +142,9 @@ export function getSuggestedCategories(
     })
   }
 
-  // 3. User history (most commonly used categories)
-  const historyEntries = Object.entries(categoryHistory)
+  // 3. Counterparty history — categories this merchant was booked as before.
+  // Confidence scales with occurrences and the reason carries provenance.
+  const historyEntries = Object.entries(merchantHistory)
     .sort(([, a], [, b]) => b - a)
     .filter(([cat]) => !seen.has(cat))
 
@@ -120,8 +159,11 @@ export function getSuggestedCategories(
       category: cat as TransactionCategory,
       label: CATEGORY_LABELS[cat] || cat,
       account: getExpenseAccountForCategory(cat as TransactionCategory),
-      confidence: Math.min(0.5, count / 20),
+      // 1 previous booking -> 0.56, capped at 0.85 (history informs, a human
+      // or counterparty template confirms).
+      confidence: Math.min(0.85, 0.5 + count * 0.06),
       source: 'history',
+      match_reason: `Bokförd ${count} gång${count === 1 ? '' : 'er'} tidigare för denna motpart`,
     })
   }