docs(engram-protocol): tighten save format — closed type table, manda…

[kecarmona]

🏷️ PR Type

• type:docs — Documentation only

---

📝 Summary

Tighten the Engram memory protocol so saved observations are actually findable
across sessions and projects. Upstream left topic_key optional, the type
field open-ended, and the title free-form — which produced duplicates,
collisions, and titles in mixed languages that broke cross-project search.

This change introduces a strict naming convention as a local override that
replaces only the Format for mem_save section of the upstream block. The rest
of the protocol (triggers, search rules, session-close, after-compaction) stays
untouched.

Key rules now enforced:

• topic_key is MANDATORY (was "recommended"), path-style
  <domain>/<scope>/<slug>, with a table of canonical patterns per case
  (SDD, bugfix, pattern, config, decision, discovery, preference, session).
• title subject MUST be in English, even when the conversation is in
  another language — search runs cross-project, English is the common
  denominator. Body content stays in whatever language the conversation uses.
• type is a CLOSED table of 14 values. Legacy architecture is REMOVED
  (SDD artifacts use the dedicated phase types; non-SDD architectural
  decisions go under decision).
• title follows a fixed format: <Prefix>: <ticket-id?> <subject> — <qualifier?>,
  prefix bound to the type (Bugfix:, Decision:, Pattern:, Spec:, etc.).
• Pre-save dedupe is MANDATORY: call mem_search on the candidate
  topic_key before mem_save. On hit → mem_update, never duplicate.
• content structure: What / Why / Where / Learned. No Tags
  field — topic_key plus the normalized title cover findability.
• Pre-save self-check checklist added so each save is verifiable before commit.

The override declares its own precedence (THIS section wins over the
upstream block when they conflict) and lives outside the gentle-ai sync
markers, so future syncs of the upstream protocol will not overwrite it.

---

📂 Changes

File / Area	What Changed
engram-naming-override.md	New strict convention: mandatory topic_key, closed type table, fixed title format, English subject rule,
mandatory dedupe, pre-save self-check
CLAUDE.md (override block)	Added LOCAL OVERRIDE section pointing to the spec, with hard-rule summary and precedence note

---

🧪 Test Plan

This PR is documentation/convention only — no Go code changes.

• Manually walked through the 6-step pre-save self-check on three sample saves (bugfix / SDD spec / session summary) — all produced valid,
  dedupe-safe records
• Verified the override sits OUTSIDE <!-- gentle-ai:engram-protocol --> markers, so gentle-ai sync will not touch it
• Confirmed all 14 type values map 1:1 to a Prefix and a topic_key pattern
• Unit tests pass (go test ./...) — N/A, no code changes
• E2E tests pass (cd e2e && ./docker-test.sh) — N/A, no code changes

If this PR is paired with validation code that enforces the rules at
mem_save time, run the full suite there.

---

✅ Contributor Checklist

• PR is linked to an issue with status:approved
• I have added the appropriate type:* label to this PR
• I have updated documentation (this PR IS the documentation)
• My commits follow Conventional Commits (docs(engram): …)
• My commits do not include Co-Authored-By trailers

---

💬 Notes for Reviewers

• The override is intentionally a superset of upstream, not a fork. Sections
  not mentioned (triggers, search, session-close, after-compaction) are left
  untouched on purpose — please flag if you find a case where they conflict.
• The removal of architecture from the type table is the most
  user-visible breaking change. Migration note is included: existing records
  stay searchable via full-text; convention applies to NEW saves and to
  mem_update of old ones.
• title examples in the spec are all English on purpose — they double as
  the canonical format reference.