[luuuc]

Summary

brAIn had built capability it never gave anyone a handle on: effectiveness ranking
that nothing could switch on, and data-model fields that no interface could write.
This connects them, and removes two fields that were decoration.

Pitch

.doc/pitches/02-05-ranking-and-fields.md — local only, since .doc/ stays out of
the public repo.

Changes

Engine

• RecallOptions.UseEffectiveness deleted; every domain-scoped recall ranks on
  persona acceptance rates. Scores are per-domain, so a recall naming no domain
  loads nothing
• A persona that is not a lower-kebab-case slug is rejected rather than stored and
  silently never matched
• A supersedes path that does not resolve is rejected before anything is written

CLI

• brain remember gains --persona, --revisit-if and --supersedes
• revisit_if surfaces in recall --json, recall text, and the session-start
  injection

MCP

• brain_remember accepts persona, revisit_if and supersedes
• brain_recall returns revisit_if

Data model

• confidence and source: refresh removed

Architecture Highlights

• The effectiveness switch is deleted, not exposed. Pitch 01-06 settled that
  effectiveness "surfaces in recall results the same way for everyone"; adding a flag
  would reopen a closed question, and a capability nothing can switch on is what this
  replaced.
• --persona is what makes the ranking mean anything. Found while building, not
  while auditing: ranking.go:95 scores on Persona, and only brain track ever
  wrote that field. Switching ranking on without this reorders nothing.
• Validation lives in the engine, so the CLI and MCP inherit one rule rather than
  duplicating it.
• confidence removal is safe because frontmatter parsing is lenient — and that
  same leniency means a hand-written confidence: now silently does nothing. Chosen
  knowingly; brAIn is pre-alpha and the alternative is keeping a field alive so that
  setting it can appear to work.

Breaking Changes

⚠️ supersedes with an unresolvable path now errors instead of warning. It
previously wrote the memory and attached a warning, leaving the superseded decision
live and the replacement claiming to have replaced it. Anything relying on
write-anyway behaviour now gets exit 3 and no write.

⚠️ Domain-scoped recall ordering changes where a domain has tracked outcomes.
Memories attributed to a persona with a high acceptance rate now rank above newer
memories from a persona with a low one. Domains with no outcomes are unaffected.

New corrections no longer carry confidence: high. Existing files that have it keep
loading unchanged.

Test Plan

• End-to-end through the CLI: track outcomes for two personas, attribute a memory
  to each, confirm the overridden persona's newer lesson ranks below the
  accepted persona's older one — mutation-verified by stripping the assignment
• A domain-less recall still falls back to recency, so the session-start hook's
  path is unchanged
• revisit_if reaches all four readers: frontmatter, recall --json, recall
  text, session-start injection; and no empty line when unset
• --supersedes retires the replaced decision; an unresolvable path exits 3 with
  nothing written
• A correction still carrying the removed confidence: field loads without error
• A non-slug persona is rejected at the engine, so CLI and MCP both reject it
• Each of the 4 commits builds and passes go test ./... standalone, verified in
  a separate worktree
• make ci passes; coverage internal/cmd 83.8%, internal/engine 87.5%,
  internal/mcp 89.3%, internal/memory 62.5%

Follow-ups

• StaleAfter is still unreachable, and it is the same class of bug.
  engine.go:142 documents caller-set staleness as a feature — "including one already
  in the past, which is how a memory can be written pre-expired" — and no interface can
  set it. The audit that opened this pitch found two such fields and missed this one; a
  sweep for the class would beat another hunt for instances.
• A missing persona scores identically to a persona overridden every time
  (ranking.go:90), so they tie and fall through to recency.
• --persona is accepted on every layer, including facts.