fix(memory): move the citation contract to where instructions are read

[kevintseng]

Summary

The signal memesh uses to justify injecting memories at all has never produced a number. Read off a real database, not a fixture:

citation_sessions_total = 4          ← 4 sessions received injected memories
citation_sessions_cited = (absent)   ← the branch that writes it never ran

None of those four sessions cited a memory. R1 spent +70 tokens per session building that accounting: write side shipped, read side (analytics.ts) shipped, tests on both, review passed. The live values were read for the first time eight days later.

Why it produced nothing — and why it is not Claude Code's fault

The instruction asking for [mem:id] markers was not missing. It is appended after the fenced block deliberately, so it reads as an instruction rather than as data. The problem is one layer further out: Claude Code wraps every hook's additionalContext in a system-reminder ending

IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant.

The instruction lands inside that container along with the memories and is read the same way — as data.

That wrapper is correct and must stay. Memory content is attacker-influenced in the general case (anything the agent was ever told can end up in an observation), so a hook's injected text must not be able to drive the agent. What it protects is memesh's own users. memesh was simply using the wrong channel: it put a contract into the data pipe.

Verified against the running binary (2.1.241), not documentation — the current docs describe tool_result and compaction_trigger, which appear zero times in that binary. It sends tool_response and trigger, which is what memesh already reads.

What changed

src/core/citation-rule.ts	writes .claude/rules/memesh-citations.md — the layer Claude Code loads as instructions. Only the contract moves; memory content stays fenced and treated as data. Leaf module (node builtins only) so generate-hook-core can mirror it for the hooks.
install-hooks.ts	writes it on the npm path, including when a plugin runtime is detected — hooks must not double-fire, but nothing in the plugin runtime writes a rules file
session-start.js	self-heals it for plugin installs, which never run install-hooks — the majority of users
session-start.js	removes the injected instruction line. A per-session copy of an instruction that is read as data is a per-session cost with no effect.
session-summary.js	citation_sessions_cited initialised unconditionally — "zero cited" and "never ran" were the same absent key
doctor.ts	new citation_compliance row. The numbers were already correct and readable; reaching anyone required going to look.
scripts/audit/measure-signals.mjs	read-only census of what every measuring mechanism actually produces on a live database
dashboard/src/lib/i18n.ts	doctor.msg.citation.none.* in all 11 locales

Safety

The rule file sits inside the user's own config tree, so both write and remove refuse to touch a file without the <!-- managed-by: memesh --> marker, and report foreign-file rather than failing silently. Pinned by tests in both directions.

Verification

Real values, not fixtures:

node scripts/audit/measure-signals.mjs     19 signals · 0 producing nothing · 1 unmeasurable
                                           citation.sessions = "? cited / 4 injected"  (live DB)
SessionStart hook, throwaway HOME          exit=0; wrote memesh-citations.md (599 bytes)
                                           grep -c "cite it once inline" on injected block = 0
npm run typecheck                          exit=0
npm run build                              exit=0
node scripts/run-tests-isolated.mjs        160 files, 2354 tests passed, exit=0
node scripts/audit/verification-audit.mjs  exit=0  (C8: denominator=25 hits=0)

• npx tsc --noEmit clean
• npm run build clean — dist/ and dashboard/dist/ regenerated and committed (plugin-marketplace installs run committed dist/)
• npm test -- --run passing — 160 files, 2354 tests
• Hooks touched → exercised end-to-end against a real payload shape taken from the 2.1.241 binary
• LLM flows untouched

What the guards caught, and what they missed

C8 caught the new doctor row the moment it was added (hits=1 new=1) — that detector was added yesterday for exactly this, and it worked on its first real opportunity.

Two things it structurally could not see, both caught by the suite:

• the doctor stub answered expect(sql).toMatch(/COUNT\(/) for any unknown query, so the new memesh_metadata read made four tests fail
• the new message code had no entry in the 11 locale catalogues — dashboard-i18n.test.ts failed on it

Both are the same shape as the bug this PR fixes: a piece added on one side, and the other side never told.

Known limitations / follow-ups

• The fix is unproven. Moving the contract to the instruction layer is supported by this session's own evidence (every CLAUDE.md rule obeyed; zero citations from the injected one) and by outside reports that additionalContext loses to system-level instructions — but whether the citation rate actually moves off 0% can only be answered by running it for a week and reading citation_compliance again. That number, not this PR, is the verdict.
• Instruction-layer rules are soft: sources describe CLAUDE.md as context Claude weighs, not a policy engine. The only hard enforcement available is a hook exit 2, which the Stop hook could use to refuse to end a session that cited nothing. Deliberately NOT in this PR — it changes session behaviour and needs a decision.
• access_count still only moves on the kg.search() path; hook injection uses its own SQL. The census reports this rather than hiding it.