feat: add diff, tag, stash, revert, MCP read/merge tools, and comprehensive test coverage

New features for "git for agentic coding":
- morph diff: compare two commits/branches, show file-level changes (A/M/D)
- morph tag: create, list, and delete lightweight tags
- morph stash: save/pop/list staged changes without committing
- morph revert: create a new commit undoing a previous commit's changes
- MCP read tools: morph_status, morph_log, morph_show, morph_diff
- MCP merge tool: morph_merge (behavioral dominance via MCP)

Test coverage expanded from 332 to 434 tests (all passing):
- morph-core: 206 → 233 (+27) — new modules + gap-filling for morphignore,
  record_run, record_eval_metrics, migrate_0_2_to_0_3
- morph-cli: 87 → 122 (+35) — specs for diff, tag, stash, revert, run list/show,
  prompt show, trace show, error paths, morphignore
- morph-mcp: 0 → 16 (+16) — first-ever MCP tests covering all 14 tools

Docs updated: TESTING.md, README.md, CURSOR-SETUP.md.

Made-with: Cursor

Author: r

Cargo.lock

@@ -24,6 +24,27 @@ morph setup cursor   # writes .cursor/ (MCP, hooks, rules)
 
 Then open the project in Cursor. Ensure `morph` and `morph-mcp` are on your PATH. The MCP server and hooks will record prompts/responses and let the agent commit via Morph.
 
+## Core commands
+
+```bash
+morph init                  # initialize a morph repo
+morph add .                 # stage files
+morph commit -m "message"   # create a behavioral commit
+morph log                   # view commit history
+morph diff <ref1> <ref2>    # compare two commits/branches
+morph branch <name>         # create a branch
+morph checkout <name>       # switch branches
+morph merge <branch> ...    # behavioral merge (dominance required)
+morph tag <name>            # tag the current commit
+morph stash save            # save staged work for later
+morph stash pop             # restore most recent stash
+morph revert <hash>         # undo a commit
+morph status                # show working directory state
+morph run record-session    # record an agent prompt/response
+morph certify               # certify a commit against policy
+morph gate                  # check if a commit passes policy
+```
+
 ## Hosted service (team inspection)
 
 Run the Morph hosted service for shared, browser-based inspection of behavioral history:

README.md

@@ -154,6 +154,11 @@ When you want a snapshot:
 | `morph_annotate` | Attach metadata to any object |
 | `morph_branch` | Create a branch at HEAD |
 | `morph_checkout` | Switch HEAD and restore working tree |
+| `morph_status` | Show working-space status (new/tracked files) |
+| `morph_log` | Show commit history from HEAD or a named ref |
+| `morph_show` | Show a stored object as pretty JSON |
+| `morph_diff` | Compare two commits/refs and show file-level changes |
+| `morph_merge` | Merge a branch (requires behavioral dominance) |
 
 All tools accept optional `workspace_path`. To get a run's prompt from the CLI, run **`morph prompt show [REF]`** in the repo (e.g. `morph prompt show latest~1`). Ref is like Git: **`latest`** (default), **`latest~N`** or **`latest-N`** (Nth run back), or a **64-char run hash**. If the trace is missing, pass **`--run-upgrade`** to run `morph upgrade` and retry once. If omitted, uses the resolved workspace (see section 2).
 

docs/CURSOR-SETUP.md

@@ -4,19 +4,23 @@
 
 | Crate | Tests | Location |
 |-------|-------|----------|
-| **morph-core** | 182 unit tests across 16 modules | `#[cfg(test)]` blocks in each source file |
-| **morph-cli** | 76 integration tests | YAML specs in `morph-cli/tests/specs/*.yaml`, compiled by `build.rs` |
-| **morph-e2e** | 25 Cucumber e2e scenarios | `morph-e2e/features/*.feature`, step defs in `morph-e2e/tests/cucumber.rs` |
-| **morph-mcp** | None yet | -- |
-| **morph-serve** | 34+ unit/API tests (views, service, handlers, org policy, multi-repo) | `morph-serve/src/tests.rs` + `org_policy::tests` |
+| **morph-core** | 233 unit tests across 20 modules | `#[cfg(test)]` blocks in each source file |
+| **morph-cli** | 113 integration tests + 9 unit tests | YAML specs in `morph-cli/tests/specs/*.yaml`, compiled by `build.rs`; unit tests in `setup.rs` |
+| **morph-e2e** | 29 Cucumber e2e scenarios | `morph-e2e/features/*.feature`, step defs in `morph-e2e/tests/cucumber.rs` |
+| **morph-mcp** | 16 integration tests | `#[cfg(test)]` in `morph-mcp/src/main.rs` |
+| **morph-serve** | 34 unit/API tests (views, service, handlers, org policy, multi-repo) | `morph-serve/src/tests.rs` + `org_policy::tests` |
 
 ### morph-core unit test modules
 
-`hash` (including paper-aligned fields: review nodes, per-node env, set-valued attribution), `store` (FsStore + GixStore), `repo`, `working`, `commit` (including merge with union suite, **provenance from run**, evidence_refs, env_constraints, contributors), `metrics` (direction-aware thresholds, metric retirement), `merge` (merge planning, dominance explanation, direction-aware reference bar, metric retirement in dominance checks, execute merge), `annotate`, `identity`, `record`, `index`, `tree`, `migrate`, `extract` (pipeline extraction from runs: graph shape, provenance, attribution, error paths), **`sync`** (remote config round-trip, reachable object collection, ancestry checks, push to empty remote, push non-fast-forward rejection, push idempotency, hash preservation across sync, fetch creates remote-tracking refs, fetch does not overwrite local branches, fetch transfers only missing objects, pull fast-forward, pull divergence rejection, evidence-backed commit sync, remote store open/validation, ref listing), **`policy`** (policy round-trip, config preservation, default policy, certification pass/fail with required metrics/thresholds/directions, gate pass/fail for certified/uncertified commits, gate failure reason identification, certification annotation recording).
+`hash` (including paper-aligned fields: review nodes, per-node env, set-valued attribution), `store` (FsStore + GixStore), `repo`, `working`, `commit` (including merge with union suite, **provenance from run**, evidence_refs, env_constraints, contributors), `metrics` (direction-aware thresholds, metric retirement), `merge` (merge planning, dominance explanation, direction-aware reference bar, metric retirement in dominance checks, execute merge), `annotate`, `identity`, `record` (**record_run** with trace validation/mismatch/artifacts/error paths, **record_eval_metrics** with validation/error paths, record_session defaults), `index`, `tree`, `migrate` (**0.0→0.2** hash rewriting, **0.2→0.3** version bump, idempotency, empty/missing objects dir), `extract` (pipeline extraction from runs: graph shape, provenance, attribution, error paths), **`sync`** (remote config round-trip, reachable object collection, ancestry checks, push/fetch/pull scenarios, evidence-backed sync), **`policy`** (policy round-trip, certification pass/fail, gate pass/fail, annotation recording), **`morphignore`** (load/match patterns, glob, directory, negation, nested paths, multiple patterns, paths outside repo), **`diff`** (empty trees, added/deleted/modified/mixed changes, nested trees, store-backed diff, None-to-tree and tree-to-None), **`tag`** (create/list/delete, duplicate tag error, nonexistent delete error, empty repo), **`stash`** (save/pop roundtrip, empty index error, empty pop error, LIFO ordering, list, no-message save), **`revert`** (parent tree restoration, root commit → empty tree, non-commit error, branch ref update).
 
 ### morph-cli integration tests
 
-`init`, `status`, `add`, `prompt create/materialize`, `pipeline create/show`, `commit + log`, `run record + eval record`, `annotate + annotations`, `branch`, `checkout`, `merge` (including auto-union suite, explained metric failure, retirement), `merge_plan` (parent inspection, reference bar, retirement preview, incompatible suites), `rollup`, `upgrade`, `errors`, **`provenance`** (evidence-backed commits with `--from-run`, `morph show`), **`pipeline_extract`** (trace-backed pipeline extraction with `--from-run`, reviewer attribution, reuse in commits, error paths), **`remote`** (add/list remotes, push to empty remote, push idempotent, push to missing remote fails, refs listing), **`push_pull`** (fetch creates remote-tracking refs, pull fast-forwards, push non-fast-forward fails, evidence-backed commit closure transfer, refs show remote-tracking after fetch), **`policy`** (round-trip set/show, set-default-eval, default empty policy), **`certify_gate`** (certify with metrics file, certify specific commit, certify fail on missing metrics, certify fail below threshold, certify with runner, gate pass for certified commit, gate fail on missing metrics, gate fail below threshold, gate fail uncertified, JSON output for certify and gate).
+`init`, `status`, `add`, `prompt create/materialize`, **`prompt show`** (latest, by run hash, no-runs error), `pipeline create/show`, `commit + log`, `run record + eval record`, **`run list`** (populated + empty), **`run show`** (summary, JSON, with-trace, invalid hash), **`trace show`** (event display), `annotate + annotations`, `branch`, `checkout`, `merge`, `merge_plan`, `rollup`, `upgrade`, **`diff`** (added files, modified files, no changes, HEAD shorthand), **`tag`** (create/list, duplicate error, delete, delete nonexistent, list empty), **`stash`** (save/pop, list, empty save error, empty pop error), **`revert`** (undo commit, invalid hash error), **`error_paths`**, **`morphignore`**, `errors`, **`provenance`**, **`pipeline_extract`**, **`remote`**, **`push_pull`**, **`policy`**, **`certify_gate`**.
+
+### morph-mcp integration tests
+
+All 14 MCP tools tested: **init** (success + already-initialized error), **record_session** (hash return), **record_run**, **record_eval** (file-based metrics), **stage** (explicit paths + default `.`), **commit** (basic, with metrics, with `--from-run` provenance), **branch** (success + no-commit error), **checkout** (branch switch), **annotate** (annotation creation), **status** (file listing), **log** (commit history), **show** (object JSON), **diff** (between commits), **merge** (behavioral dominance), **repo_store** (not-found error message).
 
 ---
 
@@ -26,6 +30,7 @@
 cargo test                    # all workspace tests (unit + integration)
 cargo test -p morph-core      # core library only
 cargo test -p morph-cli       # CLI integration tests only
+cargo test -p morph-mcp       # MCP server tests
 cargo test -p morph-e2e --test cucumber   # e2e (Cucumber; runs real morph CLI)
 cargo test --lib              # unit tests only (no integration)
 ```
@@ -70,12 +75,9 @@ Each YAML spec supports: file/directory setup (`files`, `dirs`), sequenced CLI c
 
 ## Known gaps
 
-- **morph-mcp**: No tests. An integration harness that speaks MCP over stdio would cover the primary write path.
-- **morph-serve**: 34+ tests covering repo list/summary, branch listing, commit list/detail, run/trace/pipeline detail, annotations, policy, gate status, behavioral status (certification/merge), org policy CRUD, multi-repo, backward-compatible endpoints, and error paths.
 - **GixStore-specific paths**: `status()` and `record_session()` are now backend-aware (use `store.hash_object()`), but explicit GixStore integration tests would catch backend-specific regressions.
 - **proptest**: In dev-dependencies but not yet used. Good candidate for property-based tests on hash determinism and serialization round-trips.
-- **Error paths**: Many functions have untested error branches (malformed JSON, permission errors, missing refs).
-- **CLI gaps**: `branch`, `checkout`, `merge`, `rollup`, `upgrade`, `errors`, `provenance`, `remote`, `push_pull`, `policy`, and `certify_gate` now have YAML specs. MCP integration tests are still missing.
-- **Direction-aware dominance**: `check_dominance()` assumes all metrics are "maximize". The new `merge` module's `MergePlan::check_dominance()` and `check_dominance_with_suite()` respect per-metric direction. Tests cover both maximize and minimize directions during merge planning.
 - **Network transport**: Phase 5 sync uses local filesystem paths only. Network transport (HTTP, SSH) tests will be needed when that transport is added.
 - **MCP certification/gating**: The certification and gate flows are available via CLI only. MCP exposure would allow IDE-driven certification workflows.
+- **`morph blame`**: Per-file/per-line attribution showing which commit/agent modified each part. Planned but not yet implemented.
+- **E2E hosted service**: 3 Cucumber scenarios are skipped due to server binding constraints in CI.

docs/TESTING.md

@@ -209,6 +209,35 @@ enum Command {
         #[command(subcommand)]
         sub: SetupCmd,
     },
+    /// Compare two commits (or refs) and show file-level changes
+    Diff {
+        /// First ref (branch, tag, or commit hash). Default: parent of HEAD.
+        old_ref: String,
+        /// Second ref. Default: HEAD.
+        #[arg(default_value = "HEAD")]
+        new_ref: String,
+    },
+    /// Create, list, or delete tags
+    Tag {
+        /// Tag name to create (omit to list all tags)
+        name: Option<String>,
+        /// Delete the named tag
+        #[arg(short, long)]
+        delete: bool,
+    },
+    /// Stash staged changes (save/pop/list)
+    Stash {
+        #[command(subcommand)]
+        sub: StashCmd,
+    },
+    /// Create a new commit that undoes a previous commit's changes
+    Revert {
+        /// Commit hash to revert
+        commit: String,
+        /// Author identity
+        #[arg(long)]
+        author: Option<String>,
+    },
     /// Upgrade the repo store to the latest version (required before using MCP on older repos).
     Upgrade,
     /// Inspect traces (prompt/response events)
@@ -252,6 +281,19 @@ enum TraceCmd {
     },
 }
 
+#[derive(clap::Subcommand)]
+enum StashCmd {
+    /// Save staged changes and clear the index
+    Save {
+        #[arg(short, long)]
+        message: Option<String>,
+    },
+    /// Restore the most recent stash
+    Pop,
+    /// List all stashes
+    List,
+}
+
 #[cfg(feature = "cursor-setup")]
 #[derive(clap::Subcommand)]
 enum SetupCmd {
@@ -452,6 +494,76 @@ fn main() -> anyhow::Result<()> {
                 println!("  .cursor/mcp.json: {}", if report.mcp_json_updated { "updated" } else { "unchanged" });
             }
         },
+        Command::Diff { old_ref, new_ref } => {
+            let (_repo_root, store) = get_store(verbose)?;
+            let resolve = |r: &str| -> Result<morph_core::Hash, anyhow::Error> {
+                if r.len() == 64 && r.chars().all(|c| c.is_ascii_hexdigit()) {
+                    Ok(morph_core::Hash::from_hex(r)?)
+                } else if r == "HEAD" {
+                    morph_core::resolve_head(&store)?
+                        .ok_or_else(|| anyhow::anyhow!("HEAD has no commits"))
+                } else {
+                    store.ref_read(&format!("heads/{}", r))?
+                        .or_else(|| store.ref_read(&format!("tags/{}", r)).ok().flatten())
+                        .ok_or_else(|| anyhow::anyhow!("unknown ref: {}", r))
+                }
+            };
+            let old_hash = resolve(&old_ref)?;
+            let new_hash = resolve(&new_ref)?;
+            let entries = morph_core::diff_commits(&store, &old_hash, &new_hash)?;
+            if entries.is_empty() {
+                verbose_msg(verbose, "no changes");
+            }
+            for e in &entries {
+                println!("{}  {}", e.status, e.path);
+            }
+        }
+        Command::Tag { name, delete } => {
+            let (_repo_root, store) = get_store(verbose)?;
+            if delete {
+                let name = name.ok_or_else(|| anyhow::anyhow!("tag name required with -d"))?;
+                morph_core::delete_tag(&store, &name)?;
+                println!("Deleted tag {}", name);
+            } else if let Some(name) = name {
+                let head = morph_core::resolve_head(&store)?
+                    .ok_or_else(|| anyhow::anyhow!("no commit yet"))?;
+                morph_core::create_tag(&store, &name, &head)?;
+                println!("Tagged {} as {}", head, name);
+            } else {
+                let tags = morph_core::list_tags(&store)?;
+                for (name, hash) in &tags {
+                    println!("{}  {}", name, hash);
+                }
+            }
+        }
+        Command::Stash { sub } => match sub {
+            StashCmd::Save { message } => {
+                let (repo_root, _store) = get_store(verbose)?;
+                let morph_dir = repo_root.join(".morph");
+                let entry = morph_core::stash_save(&morph_dir, message.as_deref())?;
+                println!("Saved stash {}{}", entry.id, entry.message.as_ref().map(|m| format!(": {}", m)).unwrap_or_default());
+            }
+            StashCmd::Pop => {
+                let (repo_root, _store) = get_store(verbose)?;
+                let morph_dir = repo_root.join(".morph");
+                let entry = morph_core::stash_pop(&morph_dir)?;
+                println!("Restored stash {}{}", entry.id, entry.message.as_ref().map(|m| format!(": {}", m)).unwrap_or_default());
+            }
+            StashCmd::List => {
+                let (repo_root, _store) = get_store(verbose)?;
+                let morph_dir = repo_root.join(".morph");
+                let stashes = morph_core::stash_list(&morph_dir)?;
+                for (i, entry) in stashes.iter().enumerate() {
+                    println!("stash@{{{}}}: {}", i, entry.message.as_deref().unwrap_or("(no message)"));
+                }
+            }
+        }
+        Command::Revert { commit, author } => {
+            let (_repo_root, store) = get_store(verbose)?;
+            let hash = parse_hash(&commit)?;
+            let revert_hash = morph_core::revert_commit(&store, &hash, author)?;
+            println!("{}", revert_hash);
+        }
         Command::Upgrade => {
             let cwd = std::env::current_dir()?;
             verbose_msg(verbose, &format!("looking for repo from {}", cwd.display()));

morph-cli/src/main.rs

@@ -0,0 +1,60 @@
+# Tests for `morph diff`
+- name: diff_shows_added_files
+  files:
+    a.txt: "hello"
+  steps:
+    - morph: [add, .]
+    - morph: [commit, -m, first]
+      capture: c1
+    - write_file:
+        path: b.txt
+        content: "world"
+    - morph: [add, b.txt]
+    - morph: [commit, -m, second]
+      capture: c2
+    - morph: [diff, "${c1}", "${c2}"]
+      stdout_contains:
+        - "A"
+        - "b.txt"
+
+- name: diff_shows_modified_files
+  files:
+    a.txt: "version1"
+  steps:
+    - morph: [add, .]
+    - morph: [commit, -m, first]
+      capture: c1
+    - write_file:
+        path: a.txt
+        content: "version2"
+    - morph: [add, a.txt]
+    - morph: [commit, -m, second]
+      capture: c2
+    - morph: [diff, "${c1}", "${c2}"]
+      stdout_contains:
+        - "M"
+        - "a.txt"
+
+- name: diff_no_changes_empty_output
+  files:
+    a.txt: "same"
+  steps:
+    - morph: [add, .]
+    - morph: [commit, -m, first]
+      capture: c1
+    - morph: [diff, "${c1}", "${c1}"]
+
+- name: diff_head_shorthand
+  files:
+    a.txt: "v1"
+  steps:
+    - morph: [add, .]
+    - morph: [commit, -m, first]
+      capture: c1
+    - write_file:
+        path: b.txt
+        content: "new"
+    - morph: [add, b.txt]
+    - morph: [commit, -m, second]
+    - morph: [diff, "${c1}", HEAD]
+      stdout_contains: "b.txt"

morph-cli/tests/specs/diff.yaml

@@ -0,0 +1,39 @@
+# Additional error-path tests beyond errors.yaml
+- name: checkout_no_commits_fails
+  steps:
+    - morph: [checkout, main]
+      expect_exit: 1
+
+- name: show_invalid_hash_fails
+  steps:
+    - morph: [show, not-a-hash]
+      expect_exit: 1
+
+- name: show_missing_object_fails
+  steps:
+    - morph: [show, aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa]
+      expect_exit: 1
+
+- name: pipeline_show_missing_fails
+  steps:
+    - morph: [pipeline, show, aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa]
+      expect_exit: 1
+
+- name: rollup_no_commits_fails
+  steps:
+    - morph: [rollup, HEAD, HEAD, -m, squash]
+      expect_exit: 1
+
+- name: annotate_invalid_target_fails
+  steps:
+    - morph: [annotate, not-a-hash, -k, note, -d, "{}"]
+      expect_exit: 1
+
+- name: commit_empty_message_still_works
+  files:
+    hello.txt: "hello"
+  steps:
+    - morph: [add, hello.txt]
+    - morph: [commit, -m, ""]
+      capture: hash
+      assert_hash: true

morph-cli/tests/specs/error_paths.yaml

@@ -0,0 +1,34 @@
+# Tests for .morphignore behavior
+- name: morphignore_excludes_files_from_status
+  files:
+    .morphignore: "*.log"
+    code.txt: "fn main() {}"
+    debug.log: "log output"
+  steps:
+    - morph: [status]
+      stdout_contains: "code.txt"
+      stdout_not_contains: "debug.log"
+
+- name: morphignore_excludes_files_from_add
+  files:
+    .morphignore: "*.tmp"
+    code.txt: "fn main() {}"
+    scratch.tmp: "temporary"
+  steps:
+    - morph: [add, .]
+    - morph: [status]
+      stdout_not_contains: "scratch.tmp"
+
+- name: morphignore_directory_pattern
+  files:
+    .morphignore: "build/"
+    src/main.rs: "fn main() {}"
+  dirs:
+    - build
+  steps:
+    - write_file:
+        path: build/output.bin
+        content: binary
+    - morph: [status]
+      stdout_contains: "src/main.rs"
+      stdout_not_contains: "build/output.bin"