fix(mcp): validate write project resolution

Author: Alan-TheGentleman

DOCS.md

@@ -583,13 +583,13 @@ This envelope is used consistently by `/sync/push` validation/control failures a
 
 ## MCP Project Resolution
 
-Engram resolves the project at MCP tool call time from the **server process working directory** (cwd), not at MCP startup and not from arbitrary LLM arguments. This eliminates project drift caused by agents supplying different names for the same repo.
+Engram resolves the project at MCP tool call time. The default source is the **server process working directory** (cwd), not MCP startup state, but some write tools have stronger context: `mem_session_start(directory=...)` resolves from the provided directory, and `mem_save` may use a validated explicit `project` or an existing `session_id` project before falling back to cwd detection. The explicit field is treated as a **validated selection**, not a free-form creation hint. This eliminates project drift caused by agents supplying different names for the same repo.
 
 ### Detection algorithm
 
 | Case | Condition | Source | Project |
 |------|-----------|--------|---------|
-| 1 | `.engram/config.json` exists at the repo root, or at cwd outside git | `config` | `project_name` from config |
+| 1 | nearest `.engram/config.json` exists within the enclosing git root, or at cwd outside git | `config` | `project_name` from config |
 | 2 | cwd is a git root with `origin` remote | `git_remote` | repo name from remote URL |
 | 3 | cwd is inside a git repo (subdirectory) | `git_root` | git root's directory basename |
 | 4 | cwd has exactly one git-repo child | `git_child` | child repo name (warning included) |
@@ -617,13 +617,28 @@ Exceptions:
 - `mem_current_project` returns detection fields directly (`project`, `project_source`, `project_path`, `cwd`, `available_projects`, optional `warning` / `error_hint`) and does not wrap them in `result`.
 - `mem_doctor` returns the same JSON report shape as `engram doctor --json`; it uses read-project resolution before running diagnostics but does not wrap the report in the common MCP envelope.
 
-### Write tools (cwd-detected project, limited recovery override)
+### Write tools (explicit/session/cwd project resolution)
 
-`mem_session_start`, `mem_session_end`, `mem_session_summary`, and `mem_capture_passive` auto-detect project from cwd. Any `project` argument the LLM sends is ignored.
+`mem_session_start` resolves from its explicit `directory` argument when supplied; otherwise it auto-detects from cwd. `mem_session_end`, `mem_session_summary`, and `mem_capture_passive` auto-detect project from cwd. Any `project` argument the LLM sends to these tools is ignored.
 
 `mem_update` uses ID-based updates and auto-detects project only for response envelope metadata. Its public schema does not expose `project`; raw legacy clients may still send a non-empty `project` argument, and the handler tolerates it as an observation project update for compatibility.
 
-`mem_save` and `mem_save_prompt` also auto-detect project from cwd by default, but they accept one narrow recovery override: after a previous `ambiguous_project` error, the agent may retry with `project=<one of available_projects>` and `project_choice_reason=user_selected_after_ambiguous_project`. Without that exact reason, LLM-supplied `project` is ignored so routine writes cannot drift across project names.
+`mem_save` resolves writes by precedence: validated explicit `project`, project already associated with `session_id`, repo/cwd detection (nearest `.engram/config.json` within the enclosing git root, git remote/root/child), then directory-basename fallback.
+
+Guardrails:
+- Invalid explicit `project` names fail loudly instead of silently falling back.
+- Valid-looking explicit `project` names are accepted only when backed by known context: an existing local project in the store, a matching existing session project, the nearest resolvable `.engram/config.json`, or exact ambiguous-project recovery after the user selected one available project.
+- An unbacked explicit `project` fails loudly and does not create a new bucket.
+- If a non-empty `session_id` is supplied and no session exists, `mem_save` fails with a structured error and does not write.
+- If both explicit `project` and `session_id` are supplied, they must resolve to the same normalized project or `mem_save` fails with a structured error and does not write.
+- `project_choice_reason=user_selected_after_ambiguous_project` is only honored when cwd resolution is actually ambiguous. On a non-ambiguous cwd, stale recovery flags do not override explicit-project precedence or session mismatch validation.
+- If ambiguous-project recovery is active, `project` must exactly match one of the previously returned `available_projects`; invented or normalized guesses are rejected.
+- Exact ambiguous-project choices can still fail with `project_name_collision` when multiple available names collapse to the same stored project bucket after normalization. Rename or disambiguate the colliding projects before retrying.
+- Ordinary explicit `mem_save(project=...)` calls can also fail with `project_name_collision` when the raw explicit name collapses into an existing config-backed, session-backed, or store-backed project bucket, such as `foo--bar` colliding with `foo-bar`.
+
+For monorepos, detection now honors the **nearest** `.engram/config.json` at or below the enclosing git root. That lets `repo/backend/.engram/config.json` and `repo/frontend/.engram/config.json` behave as independent projects without letting `~/.engram/config.json` leak into nested workspaces.
+
+`mem_save_prompt` keeps the older cwd/default behavior by default and only uses `project` for the narrow ambiguous-project recovery override: after a previous `ambiguous_project` error, the agent may retry with `project=<one of available_projects>` and `project_choice_reason=user_selected_after_ambiguous_project`.
 
 ### Read tools (optional project override)
 
@@ -729,6 +744,7 @@ Save comprehensive end-of-session summary:
 ## Instructions
 ## Discoveries
 ## Accomplished
+## Next Steps
 ## Relevant Files
 ```
 
@@ -900,7 +916,7 @@ All project names are normalized on write and read: **lowercase**, **trimmed**,
 ### Auto-detection
 
 MCP tools resolve project names at call time using the shared detection chain:
-1. `.engram/config.json` `project_name` at the repo root, or at cwd outside git
+1. Nearest `.engram/config.json` `project_name` within the enclosing git root, or at cwd outside git
 2. Git remote origin URL (extracts repo name)
 3. Git repository root directory name
 4. Single git-repo child of cwd
@@ -990,7 +1006,7 @@ Instead of a separate LLM service, the agent itself compresses observations. The
 **Two levels:**
 
 - **Per-action** (`mem_save`): Structured summaries (What/Why/Where/Learned)
-- **Session summary** (`mem_session_summary`): Comprehensive end-of-session summary (Goal/Instructions/Discoveries/Accomplished/Files)
+- **Session summary** (`mem_session_summary`): Comprehensive end-of-session summary (Goal/Instructions/Discoveries/Accomplished/Next Steps/Files)
 
 ### No Raw Tool-Call Auto-Capture
 

docs/AGENT-SETUP.md

@@ -27,7 +27,9 @@ Engram works with **any MCP-compatible agent**. Pick your agent below.
 
 ### Project auto-detection (important)
 
-**Do not pass `project` to write tools during normal operation.** Engram auto-detects the project from the server's working directory (cwd) using `.engram/config.json`, git remote URL, repo root name, or directory basename. Agents that include `project` in `mem_save` or similar calls will have that argument ignored unless they are using the explicit ambiguous-project recovery flow below.
+`mem_save` resolves its write project in this order: validated explicit `project`, existing `session_id` association, repo `.engram/config.json`/cwd detection, then directory-basename fallback. Use an explicit `project` when you intentionally want to target a known project; invalid or unbacked names fail loudly instead of silently falling back.
+
+Other write tools still primarily use cwd/repo detection unless their schema says otherwise. Start the MCP server from the repo or add `.engram/config.json` when you want deterministic default writes.
 
 To lock write tools to the canonical project for a repo, add `.engram/config.json` at the repo root:
 
@@ -37,7 +39,9 @@ To lock write tools to the canonical project for a repo, add `.engram/config.jso
 }
 ```
 
-When present, `project_name` is used for writes from the repo and its subdirectories and overrides lower-confidence cwd/git detection. This is a write lock only: read tools can still use an explicit `project` filter when you need to query another existing project. Empty or invalid `project_name` values fail writes loudly instead of falling back silently.
+When present, `project_name` is the default auto-detected target for writes from the repo and its subdirectories and overrides lower-confidence cwd/git detection. It is NOT an unbreakable lock against an explicit `mem_save(project=...)`, but explicit project writes are still validated against known context before they are accepted. Read tools can still use an explicit `project` filter when you need to query another existing project. Empty or invalid `project_name` values fail writes loudly instead of falling back silently.
+
+For monorepos, prefer subproject configs such as `backend/.engram/config.json` and `frontend/.engram/config.json`. Engram uses the **nearest** config under the enclosing git root, so backend/frontend can resolve as separate projects while still blocking `$HOME/.engram/config.json` ancestor leakage.
 
 **Recommended first call:** `mem_current_project` — confirms which project Engram detected before you start writing. Returns `project_source` (how it was detected) and `available_projects` (if cwd is ambiguous).
 
@@ -63,7 +67,7 @@ The first write fails with an error like:
 }
 ```
 
-Ask the user to choose exactly one value from `available_projects`, then retry only `mem_save` or `mem_save_prompt` with both recovery fields:
+Ask the user to choose exactly one value from `available_projects`. For ambiguous-project recovery, retry `mem_save` with BOTH fields:
 
 ```json
 {
@@ -72,7 +76,7 @@ Ask the user to choose exactly one value from `available_projects`, then retry o
 }
 ```
 
-On success, Engram writes to the selected project and reports the recovery source:
+On success, `mem_save` writes to the selected project and reports the recovery source:
 
 ```json
 {
@@ -82,36 +86,63 @@ On success, Engram writes to the selected project and reports the recovery sourc
 }
 ```
 
+If the exact choices normalize to the same stored project bucket, Engram returns `project_name_collision` instead of writing. Ask the user to rename or disambiguate the colliding projects before retrying.
+
 ### Ambiguous-project recovery rules
 
-This is a narrow rescue path, not a free-form project override:
+Normal `mem_save` precedence:
+
+- explicit `project`
+- existing `session_id` project
+- repo `.engram/config.json` / cwd detection
+- directory-basename fallback
 
-- Recovery is accepted only after cwd detection failed with `ambiguous_project`.
-- `project_choice_reason` must be exactly `user_selected_after_ambiguous_project`.
-- `project`, after trimming surrounding whitespace, must exactly match one of the reported `available_projects`.
-- Normalized variants and guesses are rejected: if `available_projects` contains `foo--bar`, retry with `foo--bar`, not `foo-bar`.
-- Empty or whitespace-only choices are rejected.
-- In all non-ambiguous cases, `.engram/config.json`/git/cwd detection remains authoritative and the explicit `project` field is ignored.
+Additional rules:
+
+- `project`, after trimming surrounding whitespace, must be a name, not a path.
+- Empty, whitespace-only, path-like, or control-character names are rejected.
+- Names are normalized the same way the store normalizes projects.
+- Invalid explicit `project` names fail loudly.
+- Valid-looking explicit `project` names are accepted only when backed by known context: an existing local project in the store, a matching existing session project, the nearest resolvable repo/subproject `.engram/config.json`, or exact ambiguous-project recovery.
+- Unbacked explicit `project` values are rejected; `mem_save(project=...)` is a validated selection, not an arbitrary project-creation path.
+- If `session_id` is provided and no session exists, `mem_save` fails loudly instead of falling back to cwd/config detection.
+- If both explicit `project` and `session_id` are supplied, they must match after normalization or the write is rejected.
+- `project_choice_reason=user_selected_after_ambiguous_project` is only valid when cwd detection is actually ambiguous; stale flags on a non-ambiguous cwd do not override explicit `project` precedence or session mismatch checks.
+- When ambiguous-project recovery is active, `project` must exactly match one of `available_projects`; invented or normalized guesses are rejected.
+- Exact choices may still fail with `project_name_collision` when two available names collapse to the same normalized storage bucket, such as `foo--bar` and `foo-bar`.
+- Ordinary explicit `mem_save(project=...)` calls may also fail with `project_name_collision` when the raw explicit name collapses into an existing config-backed, session-backed, or store-backed project bucket, such as `foo--bar` versus `foo-bar`.
+
+`mem_save_prompt` keeps the older cwd/default behavior. Its `project` field is only for ambiguous-project recovery together with `project_choice_reason=user_selected_after_ambiguous_project`.
 
 Mental model:
 
 ```text
-mem_save fails with ambiguous_project
+normal mem_save call
         ↓
-Engram returns available_projects
+explicit project wins when valid
         ↓
-agent asks the user to choose one exact value
+otherwise existing session project wins
         ↓
-agent retries with project + project_choice_reason
+otherwise repo/cwd detection picks the default target
+```
+
+Ambiguous recovery:
+
+```text
+write fails with ambiguous_project
         ↓
-Engram validates the choice came from ambiguity
+user chooses one exact value from available_projects
         ↓
-Engram saves to the selected project
+agent retries with project + project_choice_reason
+        ↓
+Engram validates the exact choice and writes to that repo
 ```
 
+If validation returns `project_name_collision`, do not guess. Ask the user to disambiguate the project names first.
+
 Alternatives: `cd` into the target repo before starting the MCP server, or add repo `.engram/config.json`.
 
-**Read tools** (`mem_search`, `mem_context`, `mem_get_observation`, `mem_stats`, `mem_timeline`) accept an optional `project` override validated against the store. Omit it to auto-detect.
+**Read tools** (`mem_search`, `mem_context`, `mem_stats`, `mem_timeline`, `mem_doctor`) accept an optional `project` override validated against the store. Omit it to auto-detect. `mem_get_observation` is ID-based and does not accept a `project` override.
 
 ---
 
@@ -127,7 +158,7 @@ engram setup opencode
 
 This does three things:
 1. Copies the plugin to `~/.config/opencode/plugins/engram.ts` (session tracking, Memory Protocol, compaction recovery)
-2. Adds the `engram` MCP server entry to your `opencode.json` with `--tools=agent` (14 agent-facing tools)
+2. Adds the `engram` MCP server entry to your `opencode.json` with `--tools=agent` (15 agent-facing tools)
 3. Adds `opencode-subagent-statusline` to your `tui.json` or `tui.jsonc` so OpenCode shows sub-agent activity in the sidebar/home footer
 
 The plugin auto-starts the HTTP server if needed for session tracking. If your environment blocks background processes, run it manually:
@@ -138,7 +169,7 @@ engram serve &
 
 > **Windows**: OpenCode uses `~/.config/opencode/` on Windows too (it does not read `%APPDATA%\opencode\`). `engram setup opencode` writes to `~/.config/opencode/plugins/` and `~/.config/opencode/opencode.json`. To run the server in the background: `Start-Process engram -ArgumentList "serve" -WindowStyle Hidden` (PowerShell) or just run `engram serve` in a separate terminal.
 
-**Alternative: Manual MCP-only setup** (no plugin, all 18 tools by default):
+**Alternative: Manual MCP-only setup** (no plugin, all 19 tools by default):
 
 Add to your `opencode.json` (global: `~/.config/opencode/opencode.json` on all platforms, or project-level):
 
@@ -179,7 +210,7 @@ engram setup claude-code
 
 During setup, you'll be asked whether to add engram's agent-profile MCP tools to `~/.claude/settings.json` `permissions.allow`. The setup writes entries for both the durable user-level MCP server id (`mcp__engram__...`) and the plugin-scoped server id used by older Claude Code plugin installs, so re-running setup repairs stale or incomplete allowlists without adding startup delay.
 
-**Option C: Bare MCP** — all 18 tools by default, no session management:
+**Option C: Bare MCP** — all 19 tools by default, no session management:
 
 Add to your `.claude/settings.json` (project) or `~/.claude/settings.json` (global):
 

docs/ARCHITECTURE.md

@@ -42,7 +42,7 @@ Engram trusts the **agent** to decide what's worth remembering — not a firehos
 ```
 Session starts → Agent works → Agent saves memories proactively
                                     ↓
-Session ends → Agent writes session summary (Goal/Discoveries/Accomplished/Files)
+Session ends → Agent writes session summary (Goal/Discoveries/Accomplished/Next Steps/Files)
                                     ↓
 Next session starts → Previous session context is injected automatically
 ```
@@ -69,6 +69,9 @@ Next session starts → Previous session context is injected automatically
 | `mem_capture_passive` | Extract learnings from text output |
 | `mem_merge_projects` | Merge project name variants into canonical name (admin) |
 | `mem_current_project` | Detect project from cwd — never errors, recommended first call |
+| `mem_doctor` | Run read-only operational diagnostics for project detection and store health |
+| `mem_judge` | Record a verdict for a pending memory conflict surfaced by `mem_save` |
+| `mem_compare` | Persist a semantic relation verdict between two existing observations |
 
 ---
 
@@ -126,7 +129,7 @@ engram/
 ├── internal/
 │   ├── store/store.go              # Core: SQLite + FTS5 + all data ops
 │   ├── server/server.go            # HTTP REST API (port 7437)
-│   ├── mcp/mcp.go                  # MCP stdio server (18 tools)
+│   ├── mcp/mcp.go                  # MCP stdio server (19 tools)
 │   ├── setup/setup.go              # Agent plugin installer (go:embed)
 │   ├── cloud/                       # Optional cloud runtime (Postgres + dashboard)
 │   │   ├── cloudserver/             # /sync API + dashboard mount + auth/session bridge

docs/PLUGINS.md

@@ -82,7 +82,7 @@ claude --plugin-dir ./plugin/claude-code
 
 | Feature | Bare MCP | Plugin |
 |---------|----------|--------|
-| MCP tools available | 18 default (`engram mcp`) | 14 agent-profile tools (`engram mcp --tools=agent`) |
+| MCP tools available | 19 default (`engram mcp`) | 15 agent-profile tools (`engram mcp --tools=agent`) |
 | Session tracking (auto-start) | ✗ | ✓ |
 | Auto-import git-synced memories | ✗ | ✓ |
 | Compaction recovery | ✗ | ✓ |