From f308eea6c654353a718e3c6e5304006f8878fc73 Mon Sep 17 00:00:00 2001
From: Layne Penney <dev@layne.pro>
Date: Wed, 8 Apr 2026 11:29:14 -0500
Subject: [PATCH 01/15] Sprint 13: integrate gr2 team-workspace foundation
 (#509)

---
 Cargo.lock          |   9 +
 Cargo.toml          |   8 +
 gr2/Cargo.toml      |  13 ++
 gr2/src/args.rs     |  85 ++++++++
 gr2/src/dispatch.rs | 239 +++++++++++++++++++++
 gr2/src/lib.rs      |   6 +
 src/bin/gr2.rs      |  22 ++
 tests/cli_tests.rs  | 513 ++++++++++++++++++++++++++++++++++++++++++++
 8 files changed, 895 insertions(+)
 create mode 100644 gr2/Cargo.toml
 create mode 100644 gr2/src/args.rs
 create mode 100644 gr2/src/dispatch.rs
 create mode 100644 gr2/src/lib.rs
 create mode 100644 src/bin/gr2.rs

diff --git a/Cargo.lock b/Cargo.lock
index d273c8a9..31da8d59 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -826,6 +826,7 @@ dependencies = [
  "futures",
  "git2",
  "gix",
+ "gr2-cli",
  "indicatif",
  "octocrab",
  "once_cell",
@@ -1586,6 +1587,14 @@ dependencies = [
  "gix-validate 0.9.4",
 ]
 
+[[package]]
+name = "gr2-cli"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "clap",
+]
+
 [[package]]
 name = "h2"
 version = "0.4.13"
diff --git a/Cargo.toml b/Cargo.toml
index 4d178366..aaa078cf 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -13,6 +13,9 @@ readme = "README.md"
 keywords = ["git", "monorepo", "workflow", "multi-repo", "cli"]
 categories = ["development-tools", "command-line-utilities"]
 
+[workspace]
+members = ["gr2"]
+
 [[bin]]
 name = "gr"
 path = "src/main.rs"
@@ -21,6 +24,10 @@ path = "src/main.rs"
 name = "gitgrip"
 path = "src/main.rs"
 
+[[bin]]
+name = "gr2"
+path = "src/bin/gr2.rs"
+
 [lib]
 name = "gitgrip"
 path = "src/lib.rs"
@@ -40,6 +47,7 @@ release-logs = ["tracing/release_max_level_info"]
 max-perf = ["tracing/max_level_off"]
 
 [dependencies]
+gr2_cli = { package = "gr2-cli", path = "gr2" }
 # Async runtime
 tokio = { version = "1", features = ["rt-multi-thread", "macros", "process", "time", "net", "io-util", "sync"] }
 uuid = { version = "1", features = ["v4"] }
diff --git a/gr2/Cargo.toml b/gr2/Cargo.toml
new file mode 100644
index 00000000..b8b7067f
--- /dev/null
+++ b/gr2/Cargo.toml
@@ -0,0 +1,13 @@
+[package]
+name = "gr2-cli"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+name = "gr2_cli"
+path = "src/lib.rs"
+
+[dependencies]
+anyhow = "1"
+clap = { version = "4", features = ["derive"] }
diff --git a/gr2/src/args.rs b/gr2/src/args.rs
new file mode 100644
index 00000000..f4f5916d
--- /dev/null
+++ b/gr2/src/args.rs
@@ -0,0 +1,85 @@
+use clap::{Parser, Subcommand};
+
+#[derive(Parser, Debug)]
+#[command(
+    name = "gr2",
+    about = "Clean-break gitgrip CLI for clone-backed team workspaces",
+    long_about = "gr2 is the clean-break gitgrip CLI for the new team-workspace, cache, and checkout model.",
+    version,
+    arg_required_else_help = true
+)]
+pub struct Cli {
+    /// Enable verbose logging
+    #[arg(short, long)]
+    pub verbose: bool,
+
+    #[command(subcommand)]
+    pub command: Commands,
+}
+
+#[derive(Subcommand, Debug)]
+pub enum Commands {
+    /// Initialize a new team workspace root
+    Init {
+        /// Path to create the workspace in
+        path: String,
+
+        /// Optional logical workspace name
+        #[arg(long)]
+        name: Option<String>,
+    },
+
+    /// Verify the gr2 bootstrap binary is wired correctly
+    Doctor,
+
+    /// Team workspace operations
+    Team {
+        #[command(subcommand)]
+        command: TeamCommands,
+    },
+
+    /// Repo registry operations
+    Repo {
+        #[command(subcommand)]
+        command: RepoCommands,
+    },
+}
+
+#[derive(Subcommand, Debug)]
+pub enum TeamCommands {
+    /// Register an agent workspace under agents/
+    Add {
+        /// Agent workspace name
+        name: String,
+    },
+
+    /// List registered agent workspaces
+    List,
+
+    /// Remove a registered agent workspace
+    Remove {
+        /// Agent workspace name
+        name: String,
+    },
+}
+
+#[derive(Subcommand, Debug)]
+pub enum RepoCommands {
+    /// Register a repo in the team workspace
+    Add {
+        /// Logical repo name
+        name: String,
+
+        /// Canonical remote URL
+        url: String,
+    },
+
+    /// List registered repos
+    List,
+
+    /// Remove a registered repo
+    Remove {
+        /// Logical repo name
+        name: String,
+    },
+}
diff --git a/gr2/src/dispatch.rs b/gr2/src/dispatch.rs
new file mode 100644
index 00000000..29273f4d
--- /dev/null
+++ b/gr2/src/dispatch.rs
@@ -0,0 +1,239 @@
+use anyhow::Result;
+use std::fs;
+use std::path::PathBuf;
+
+use crate::args::{Commands, RepoCommands, TeamCommands};
+
+pub async fn dispatch_command(command: Commands, verbose: bool) -> Result<()> {
+    match command {
+        Commands::Init { path, name } => {
+            let workspace_root = PathBuf::from(path);
+            let workspace_name = name.unwrap_or_else(|| {
+                workspace_root
+                    .file_name()
+                    .map(|name| name.to_string_lossy().into_owned())
+                    .unwrap_or_else(|| "workspace".to_string())
+            });
+
+            if workspace_root.exists() {
+                anyhow::bail!(
+                    "workspace path already exists: {}",
+                    workspace_root.display()
+                );
+            }
+
+            fs::create_dir_all(workspace_root.join(".grip"))?;
+            fs::create_dir_all(workspace_root.join("config"))?;
+            fs::create_dir_all(workspace_root.join("agents"))?;
+            fs::create_dir_all(workspace_root.join("repos"))?;
+
+            let workspace_toml = format!(
+                "version = 2\nname = \"{}\"\nlayout = \"team-workspace\"\n",
+                workspace_name
+            );
+            fs::write(workspace_root.join(".grip/workspace.toml"), workspace_toml)?;
+
+            println!(
+                "Initialized gr2 team workspace '{}' at {}",
+                workspace_name,
+                workspace_root.display()
+            );
+            Ok(())
+        }
+        Commands::Doctor => {
+            if verbose {
+                println!("gr2 bootstrap OK (verbose)");
+            } else {
+                println!("gr2 bootstrap OK");
+            }
+            Ok(())
+        }
+        Commands::Team { command } => match command {
+            TeamCommands::Add { name } => {
+                let workspace_root = require_workspace_root()?;
+
+                let agent_root = workspace_root.join("agents").join(&name);
+                if agent_root.exists() {
+                    anyhow::bail!("agent '{}' already exists", name);
+                }
+
+                fs::create_dir_all(&agent_root)?;
+                fs::write(
+                    agent_root.join("agent.toml"),
+                    format!("name = \"{}\"\nkind = \"agent-workspace\"\n", name),
+                )?;
+
+                println!("Added gr2 agent workspace '{}'", name);
+                Ok(())
+            }
+            TeamCommands::List => {
+                let workspace_root = require_workspace_root()?;
+                let agents_root = workspace_root.join("agents");
+
+                let mut names = Vec::new();
+                for entry in fs::read_dir(&agents_root)? {
+                    let entry = entry?;
+                    if entry.file_type()?.is_dir() && entry.path().join("agent.toml").exists() {
+                        names.push(entry.file_name().to_string_lossy().into_owned());
+                    }
+                }
+
+                names.sort();
+
+                if names.is_empty() {
+                    println!("No gr2 agent workspaces registered.");
+                } else {
+                    println!("Agent workspaces");
+                    for name in names {
+                        println!("- {}", name);
+                    }
+                }
+
+                Ok(())
+            }
+            TeamCommands::Remove { name } => {
+                let workspace_root = require_workspace_root()?;
+                let agent_root = workspace_root.join("agents").join(&name);
+
+                if !agent_root.join("agent.toml").exists() {
+                    anyhow::bail!("agent '{}' not found", name);
+                }
+
+                fs::remove_dir_all(&agent_root)?;
+                println!("Removed gr2 agent workspace '{}'", name);
+                Ok(())
+            }
+        },
+        Commands::Repo { command } => match command {
+            RepoCommands::Add { name, url } => {
+                let workspace_root = require_workspace_root()?;
+                let repos_root = workspace_root.join("repos");
+                let registry_path = workspace_root.join(".grip/repos.toml");
+                let repo_dir = repos_root.join(&name);
+
+                if repo_dir.exists() {
+                    anyhow::bail!("repo '{}' already exists", name);
+                }
+
+                fs::create_dir_all(&repo_dir)?;
+                fs::write(
+                    repo_dir.join("repo.toml"),
+                    format!("name = \"{}\"\nurl = \"{}\"\n", name, url),
+                )?;
+
+                let mut entries = Vec::new();
+                if registry_path.exists() {
+                    entries.push(fs::read_to_string(&registry_path)?);
+                }
+                entries.push(format!(
+                    "[[repo]]\nname = \"{}\"\nurl = \"{}\"\n",
+                    name, url
+                ));
+                fs::write(&registry_path, entries.join("\n"))?;
+
+                println!("Added gr2 repo '{}' -> {}", name, url);
+                Ok(())
+            }
+            RepoCommands::List => {
+                let workspace_root = require_workspace_root()?;
+                let repos_root = workspace_root.join("repos");
+
+                let mut repos = Vec::new();
+                for entry in fs::read_dir(&repos_root)? {
+                    let entry = entry?;
+                    let repo_toml = entry.path().join("repo.toml");
+                    if entry.file_type()?.is_dir() && repo_toml.exists() {
+                        let content = fs::read_to_string(repo_toml)?;
+                        let fallback_name = entry.file_name().to_string_lossy().into_owned();
+                        let name = content
+                            .lines()
+                            .find_map(|line| line.strip_prefix("name = \""))
+                            .and_then(|line| line.strip_suffix('"'))
+                            .map(str::to_owned)
+                            .unwrap_or(fallback_name);
+                        let url = content
+                            .lines()
+                            .find_map(|line| line.strip_prefix("url = \""))
+                            .and_then(|line| line.strip_suffix('"'))
+                            .unwrap_or("")
+                            .to_string();
+                        repos.push((name, url));
+                    }
+                }
+
+                repos.sort_by(|a, b| a.0.cmp(&b.0));
+
+                if repos.is_empty() {
+                    println!("No gr2 repos registered.");
+                } else {
+                    println!("Repos");
+                    for (name, url) in repos {
+                        println!("- {} -> {}", name, url);
+                    }
+                }
+
+                Ok(())
+            }
+            RepoCommands::Remove { name } => {
+                let workspace_root = require_workspace_root()?;
+                let repos_root = workspace_root.join("repos");
+                let repo_root = repos_root.join(&name);
+                let repo_toml = repo_root.join("repo.toml");
+
+                if !repo_toml.exists() {
+                    anyhow::bail!("repo '{}' not found", name);
+                }
+
+                fs::remove_dir_all(&repo_root)?;
+
+                let registry_path = workspace_root.join(".grip/repos.toml");
+                if registry_path.exists() {
+                    let registry = fs::read_to_string(&registry_path)?;
+                    let kept_entries = registry
+                        .split("\n[[repo]]\n")
+                        .filter_map(|chunk| {
+                            let chunk = chunk.trim();
+                            if chunk.is_empty() {
+                                return None;
+                            }
+                            let normalized = if chunk.starts_with("[[repo]]") {
+                                chunk.to_string()
+                            } else {
+                                format!("[[repo]]\n{}", chunk)
+                            };
+                            let matches_name = normalized
+                                .lines()
+                                .find_map(|line| line.strip_prefix("name = \""))
+                                .and_then(|line| line.strip_suffix('"'))
+                                .map(|entry_name| entry_name == name)
+                                .unwrap_or(false);
+                            if matches_name {
+                                None
+                            } else {
+                                Some(normalized)
+                            }
+                        })
+                        .collect::<Vec<_>>();
+
+                    if kept_entries.is_empty() {
+                        fs::remove_file(&registry_path)?;
+                    } else {
+                        fs::write(&registry_path, kept_entries.join("\n\n"))?;
+                    }
+                }
+
+                println!("Removed gr2 repo '{}'", name);
+                Ok(())
+            }
+        },
+    }
+}
+
+fn require_workspace_root() -> Result<PathBuf> {
+    let workspace_root = std::env::current_dir()?;
+    let workspace_toml = workspace_root.join(".grip/workspace.toml");
+    if !workspace_toml.exists() {
+        anyhow::bail!("not in a gr2 workspace: missing .grip/workspace.toml");
+    }
+    Ok(workspace_root)
+}
diff --git a/gr2/src/lib.rs b/gr2/src/lib.rs
new file mode 100644
index 00000000..7a8cd2b8
--- /dev/null
+++ b/gr2/src/lib.rs
@@ -0,0 +1,6 @@
+//! gr2 CLI namespace
+//!
+//! This crate is the clean-break CLI surface for the new team-workspace model.
+
+pub mod args;
+pub mod dispatch;
diff --git a/src/bin/gr2.rs b/src/bin/gr2.rs
new file mode 100644
index 00000000..344dfd48
--- /dev/null
+++ b/src/bin/gr2.rs
@@ -0,0 +1,22 @@
+//! gr2 CLI entry point
+
+use clap::Parser;
+use gr2_cli::args::Cli;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let cli = Cli::parse();
+
+    if cli.verbose {
+        tracing_subscriber::fmt()
+            .with_env_filter("gitgrip=debug")
+            .with_target(false)
+            .init();
+    } else {
+        tracing_subscriber::fmt()
+            .with_env_filter(tracing_subscriber::EnvFilter::from_default_env())
+            .init();
+    }
+
+    gr2_cli::dispatch::dispatch_command(cli.command, cli.verbose).await
+}
diff --git a/tests/cli_tests.rs b/tests/cli_tests.rs
index 4f8ac0f9..e23ad564 100644
--- a/tests/cli_tests.rs
+++ b/tests/cli_tests.rs
@@ -32,6 +32,519 @@ fn test_version() {
         .stdout(predicate::str::contains(env!("CARGO_PKG_VERSION")));
 }
 
+#[test]
+fn test_gr2_help() {
+    let mut cmd = Command::cargo_bin("gr2").unwrap();
+    cmd.arg("--help")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "gr2 is the clean-break gitgrip CLI for the new team-workspace, cache, and checkout model.",
+        ))
+        .stdout(predicate::str::contains("doctor"))
+        .stdout(predicate::str::contains("gr2"));
+}
+
+#[test]
+fn test_gr2_version() {
+    let mut cmd = Command::cargo_bin("gr2").unwrap();
+    cmd.arg("--version")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("gr2 0.1.0"));
+}
+
+#[test]
+fn test_gr2_doctor() {
+    let mut cmd = Command::cargo_bin("gr2").unwrap();
+    cmd.arg("doctor")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("gr2 bootstrap OK"));
+}
+
+#[test]
+fn test_gr2_init_scaffolds_team_workspace() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut cmd = Command::cargo_bin("gr2").unwrap();
+    cmd.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "Initialized gr2 team workspace 'demo'",
+        ));
+
+    assert!(workspace_root.join(".grip").is_dir());
+    assert!(workspace_root.join("config").is_dir());
+    assert!(workspace_root.join("agents").is_dir());
+    assert!(workspace_root.join("repos").is_dir());
+
+    let workspace_toml =
+        std::fs::read_to_string(workspace_root.join(".grip/workspace.toml")).unwrap();
+    assert!(workspace_toml.contains("version = 2"));
+    assert!(workspace_toml.contains("name = \"demo\""));
+    assert!(workspace_toml.contains("layout = \"team-workspace\""));
+}
+
+#[test]
+fn test_gr2_init_rejects_existing_path() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+    std::fs::create_dir_all(&workspace_root).unwrap();
+
+    let mut cmd = Command::cargo_bin("gr2").unwrap();
+    cmd.arg("init")
+        .arg(&workspace_root)
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("workspace path already exists"));
+}
+
+#[test]
+fn test_gr2_team_add_registers_agent_workspace() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut team_add = Command::cargo_bin("gr2").unwrap();
+    team_add
+        .current_dir(&workspace_root)
+        .arg("team")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "Added gr2 agent workspace 'atlas'",
+        ));
+
+    let agent_toml =
+        std::fs::read_to_string(workspace_root.join("agents/atlas/agent.toml")).unwrap();
+    assert!(agent_toml.contains("name = \"atlas\""));
+    assert!(agent_toml.contains("kind = \"agent-workspace\""));
+}
+
+#[test]
+fn test_gr2_team_add_rejects_duplicate_agent() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut first = Command::cargo_bin("gr2").unwrap();
+    first
+        .current_dir(&workspace_root)
+        .arg("team")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let mut duplicate = Command::cargo_bin("gr2").unwrap();
+    duplicate
+        .current_dir(&workspace_root)
+        .arg("team")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("agent 'atlas' already exists"));
+}
+
+#[test]
+fn test_gr2_team_add_requires_gr2_workspace() {
+    let temp = TempDir::new().unwrap();
+
+    let mut team_add = Command::cargo_bin("gr2").unwrap();
+    team_add
+        .current_dir(temp.path())
+        .arg("team")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "not in a gr2 workspace: missing .grip/workspace.toml",
+        ));
+}
+
+#[test]
+fn test_gr2_team_list_shows_registered_agents() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut add_atlas = Command::cargo_bin("gr2").unwrap();
+    add_atlas
+        .current_dir(&workspace_root)
+        .arg("team")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let mut add_opus = Command::cargo_bin("gr2").unwrap();
+    add_opus
+        .current_dir(&workspace_root)
+        .arg("team")
+        .arg("add")
+        .arg("opus")
+        .assert()
+        .success();
+
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(&workspace_root)
+        .arg("team")
+        .arg("list")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Agent workspaces"))
+        .stdout(predicate::str::contains("- atlas"))
+        .stdout(predicate::str::contains("- opus"));
+}
+
+#[test]
+fn test_gr2_team_list_reports_empty_state() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(&workspace_root)
+        .arg("team")
+        .arg("list")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "No gr2 agent workspaces registered.",
+        ));
+}
+
+#[test]
+fn test_gr2_team_list_requires_gr2_workspace() {
+    let temp = TempDir::new().unwrap();
+
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(temp.path())
+        .arg("team")
+        .arg("list")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "not in a gr2 workspace: missing .grip/workspace.toml",
+        ));
+}
+
+#[test]
+fn test_gr2_team_remove_deletes_registered_agent() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut add = Command::cargo_bin("gr2").unwrap();
+    add.current_dir(&workspace_root)
+        .arg("team")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let agent_root = workspace_root.join("agents/atlas");
+    assert!(agent_root.join("agent.toml").exists());
+
+    let mut remove = Command::cargo_bin("gr2").unwrap();
+    remove
+        .current_dir(&workspace_root)
+        .arg("team")
+        .arg("remove")
+        .arg("atlas")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "Removed gr2 agent workspace 'atlas'",
+        ));
+
+    assert!(!agent_root.exists());
+}
+
+#[test]
+fn test_gr2_team_remove_rejects_missing_agent() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut remove = Command::cargo_bin("gr2").unwrap();
+    remove
+        .current_dir(&workspace_root)
+        .arg("team")
+        .arg("remove")
+        .arg("atlas")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("agent 'atlas' not found"));
+}
+
+#[test]
+fn test_gr2_team_remove_requires_gr2_workspace() {
+    let temp = TempDir::new().unwrap();
+
+    let mut remove = Command::cargo_bin("gr2").unwrap();
+    remove
+        .current_dir(temp.path())
+        .arg("team")
+        .arg("remove")
+        .arg("atlas")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "not in a gr2 workspace: missing .grip/workspace.toml",
+        ));
+}
+
+#[test]
+fn test_gr2_repo_add_registers_repo() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "Added gr2 repo 'app' -> https://github.com/synapt-dev/app.git",
+        ));
+
+    let repo_toml = std::fs::read_to_string(workspace_root.join("repos/app/repo.toml")).unwrap();
+    assert!(repo_toml.contains("name = \"app\""));
+    assert!(repo_toml.contains("url = \"https://github.com/synapt-dev/app.git\""));
+
+    let registry = std::fs::read_to_string(workspace_root.join(".grip/repos.toml")).unwrap();
+    assert!(registry.contains("[[repo]]"));
+    assert!(registry.contains("name = \"app\""));
+}
+
+#[test]
+fn test_gr2_repo_add_rejects_duplicate_repo() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut first = Command::cargo_bin("gr2").unwrap();
+    first
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .success();
+
+    let mut duplicate = Command::cargo_bin("gr2").unwrap();
+    duplicate
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("repo 'app' already exists"));
+}
+
+#[test]
+fn test_gr2_repo_add_requires_gr2_workspace() {
+    let temp = TempDir::new().unwrap();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(temp.path())
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "not in a gr2 workspace: missing .grip/workspace.toml",
+        ));
+}
+
+#[test]
+fn test_gr2_repo_list_shows_registered_repos() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut add_app = Command::cargo_bin("gr2").unwrap();
+    add_app
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .success();
+
+    let mut add_docs = Command::cargo_bin("gr2").unwrap();
+    add_docs
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("docs")
+        .arg("https://github.com/synapt-dev/docs.git")
+        .assert()
+        .success();
+
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(&workspace_root)
+        .arg("repo")
+        .arg("list")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Repos"))
+        .stdout(predicate::str::contains(
+            "- app -> https://github.com/synapt-dev/app.git",
+        ))
+        .stdout(predicate::str::contains(
+            "- docs -> https://github.com/synapt-dev/docs.git",
+        ));
+}
+
+#[test]
+fn test_gr2_repo_list_reports_empty_state() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(&workspace_root)
+        .arg("repo")
+        .arg("list")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("No gr2 repos registered."));
+}
+
+#[test]
+fn test_gr2_repo_list_requires_gr2_workspace() {
+    let temp = TempDir::new().unwrap();
+
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(temp.path())
+        .arg("repo")
+        .arg("list")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "not in a gr2 workspace: missing .grip/workspace.toml",
+        ));
+}
+
+#[test]
+fn test_gr2_repo_remove_deletes_registered_repo() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut add = Command::cargo_bin("gr2").unwrap();
+    add.current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .success();
+
+    let repo_root = workspace_root.join("repos/app");
+    assert!(repo_root.join("repo.toml").exists());
+
+    let mut remove = Command::cargo_bin("gr2").unwrap();
+    remove
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("remove")
+        .arg("app")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Removed gr2 repo 'app'"));
+
+    assert!(!repo_root.exists());
+    assert!(!workspace_root.join(".grip/repos.toml").exists());
+}
+
+#[test]
+fn test_gr2_repo_remove_rejects_missing_repo() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut remove = Command::cargo_bin("gr2").unwrap();
+    remove
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("remove")
+        .arg("app")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("repo 'app' not found"));
+}
+
+#[test]
+fn test_gr2_repo_remove_requires_gr2_workspace() {
+    let temp = TempDir::new().unwrap();
+
+    let mut remove = Command::cargo_bin("gr2").unwrap();
+    remove
+        .current_dir(temp.path())
+        .arg("repo")
+        .arg("remove")
+        .arg("app")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "not in a gr2 workspace: missing .grip/workspace.toml",
+        ));
+}
+
 /// Test that `gr status` fails gracefully outside a workspace
 #[test]
 fn test_status_outside_workspace() {

From 1035a6f55f559be1f34a76a123e40e95bffd0be0 Mon Sep 17 00:00:00 2001
From: Layne Penney <dev@layne.pro>
Date: Wed, 8 Apr 2026 11:51:33 -0500
Subject: [PATCH 02/15] ci: split Windows tests into non-blocking lane (#487)

---
 .github/workflows/ci.yml | 32 +++++++++++++++++++++++---------
 1 file changed, 23 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c51b4b26..d18ed5c8 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -70,7 +70,22 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache cargo
+        uses: Swatinem/rust-cache@v2
+
+      - name: Run tests
+        run: cargo test --all-features
+
+  test-windows:
+    name: Test (windows-latest)
+    runs-on: windows-latest
     steps:
       - uses: actions/checkout@v4
 
@@ -83,10 +98,7 @@ jobs:
       - name: Run tests
         run: cargo test --all-features
         env:
-          # Windows: link advapi32 for libgit2-sys (needed for test crates that
-          # don't go through build.rs) and increase stack to 8 MB (debug builds
-          # overflow the default 1 MB Windows stack during clap parsing)
-          RUSTFLAGS: ${{ matrix.os == 'windows-latest' && '-C link-arg=advapi32.lib -C link-arg=/STACK:8388608' || '' }}
+          RUSTFLAGS: '-C link-arg=advapi32.lib -C link-arg=/STACK:8388608'
 
   build:
     name: Build Release
@@ -149,14 +161,16 @@ jobs:
       - name: Run spawn integration tests
         run: GR=./target/debug/gr ./tests/spawn_graceful_shutdown.sh
 
-  # Summary job for branch protection - requires all other jobs to pass
+  # Summary job for branch protection - requires all jobs except Windows to pass.
+  # Windows tests run separately (test-windows) and are visible but non-blocking,
+  # since they are significantly slower and should not gate PR merges.
   ci:
     name: CI
     runs-on: ubuntu-latest
     needs: [check, fmt, clippy, test, build, bench, integration]
     if: always()
     steps:
-      - name: Check all jobs passed
+      - name: Check all required jobs passed
         run: |
           if [[ "${{ needs.check.result }}" != "success" ]] || \
              [[ "${{ needs.fmt.result }}" != "success" ]] || \
@@ -165,7 +179,7 @@ jobs:
              [[ "${{ needs.build.result }}" != "success" ]] || \
              [[ "${{ needs.bench.result }}" != "success" ]] || \
              [[ "${{ needs.integration.result }}" != "success" ]]; then
-            echo "One or more jobs failed"
+            echo "One or more required jobs failed"
             exit 1
           fi
-          echo "All jobs passed"
+          echo "All required jobs passed"

From a8f6a3f0d41bdc38faa48f323c42fe83d75fe0d2 Mon Sep 17 00:00:00 2001
From: Layne Penney <dev@layne.pro>
Date: Wed, 8 Apr 2026 12:00:48 -0500
Subject: [PATCH 03/15] feat: add machine-level manifest repo caches (#484)

---
 README.md                      |  31 +++
 src/cli/args.rs                |   2 +-
 src/cli/commands/cache.rs      |  26 ++-
 src/core/workspace_cache.rs    | 356 ++++++++++++++++++++++++---------
 src/core/workspace_checkout.rs | 206 +++++++++++--------
 5 files changed, 426 insertions(+), 195 deletions(-)

diff --git a/README.md b/README.md
index bb5751ff..f7c01a28 100644
--- a/README.md
+++ b/README.md
@@ -183,6 +183,9 @@ gr sync
 | `gr link` | Manage file links |
 | `gr run <script>` | Run workspace scripts |
 | `gr env` | Show environment variables |
+| `gr cache status` | Show machine-level cache state for workspace repos |
+| `gr cache bootstrap` | Materialize missing machine-level repo caches |
+| `gr cache update` | Fetch updates into existing machine-level repo caches |
 | `gr bench` | Run performance benchmarks |
 | `gr completions <shell>` | Generate shell completions |
 
@@ -223,6 +226,34 @@ Pull latest changes from the manifest and all repositories. Syncs in parallel by
 
 Show status of all repositories including branch, changes, and sync state.
 
+#### `gr cache <subcommand>`
+
+Manage the machine-level bare-repo cache used by workspace repos.
+
+By default caches live under `~/.grip/cache/`, keyed by canonical repo identity.
+You can override the cache root with `GRIP_CACHE_DIR` when you need a custom or
+isolated cache location.
+
+| Subcommand | Description |
+|-----------|-------------|
+| `gr cache status` | Show whether each workspace repo has a cache and where it lives |
+| `gr cache bootstrap` | Create missing caches without touching existing ones |
+| `gr cache update` | Fetch updates into existing caches |
+| `gr cache remove <repo>` | Remove one repo cache explicitly |
+
+**Examples:**
+
+```bash
+# See where caches are currently resolved
+gr cache status
+
+# Create missing caches before materializing child checkouts
+gr cache bootstrap
+
+# Use a custom cache root for an isolated environment
+GRIP_CACHE_DIR=/tmp/grip-cache gr cache status
+```
+
 #### `gr checkout <branch>`
 
 Checkout a branch across all repos. Can also create branches with the `-b` flag.
diff --git a/src/cli/args.rs b/src/cli/args.rs
index b039b61d..b840f020 100644
--- a/src/cli/args.rs
+++ b/src/cli/args.rs
@@ -349,7 +349,7 @@ pub enum Commands {
         #[command(subcommand)]
         action: TargetCommands,
     },
-    /// Manage workspace repo caches (.grip/cache/)
+    /// Manage machine-level repo caches (~/.grip/cache/ by default)
     Cache {
         #[command(subcommand)]
         action: CacheCommands,
diff --git a/src/cli/commands/cache.rs b/src/cli/commands/cache.rs
index 54c58772..f2d1f182 100644
--- a/src/cli/commands/cache.rs
+++ b/src/cli/commands/cache.rs
@@ -1,6 +1,6 @@
 //! Cache command implementation
 //!
-//! Manages bare-repo caches under `.grip/cache/` for workspace repos.
+//! Manages bare-repo caches under the machine-level cache root for workspace repos.
 
 use crate::cli::args::CacheCommands;
 use crate::cli::output::Output;
@@ -50,7 +50,12 @@ pub fn run_cache(
                 Output::info("Updating all caches...");
             }
 
-            let count = workspace_cache::update_all(workspace_root)?;
+            let repo_pairs: Vec<(&str, &str)> = repos
+                .iter()
+                .map(|r| (r.name.as_str(), r.url.as_str()))
+                .collect();
+
+            let count = workspace_cache::update_all(workspace_root, repo_pairs.into_iter())?;
 
             if !quiet {
                 Output::success(&format!("Updated {} cache(s)", count));
@@ -58,12 +63,6 @@ pub fn run_cache(
         }
 
         CacheCommands::Status => {
-            let cache_dir = workspace_root.join(".grip").join("cache");
-            if !cache_dir.is_dir() {
-                Output::info("No caches exist yet. Run 'gr cache bootstrap' to create them.");
-                return Ok(());
-            }
-
             println!(
                 "{:<20} {:<8} {}",
                 "Repo".bold(),
@@ -73,8 +72,9 @@ pub fn run_cache(
             println!("{}", "─".repeat(70));
 
             for repo in &repos {
-                let exists = workspace_cache::cache_exists(workspace_root, &repo.name);
-                let path = workspace_cache::cache_path(workspace_root, &repo.name);
+                let exists = workspace_cache::cache_exists(workspace_root, &repo.name, &repo.url)?;
+                let path =
+                    workspace_cache::resolve_cache_path(workspace_root, &repo.name, &repo.url)?;
                 let status = if exists {
                     "cached".green().to_string()
                 } else {
@@ -85,7 +85,11 @@ pub fn run_cache(
         }
 
         CacheCommands::Remove { repo } => {
-            let removed = workspace_cache::remove_cache(workspace_root, &repo)?;
+            let Some(repo_info) = repos.iter().find(|r| r.name == repo) else {
+                anyhow::bail!("repo '{}' is not in this manifest", repo);
+            };
+            let removed =
+                workspace_cache::remove_cache(workspace_root, &repo_info.name, &repo_info.url)?;
             if removed {
                 Output::success(&format!("Removed cache for {}", repo));
             } else {
diff --git a/src/core/workspace_cache.rs b/src/core/workspace_cache.rs
index c60cae8a..7c2ce6dd 100644
--- a/src/core/workspace_cache.rs
+++ b/src/core/workspace_cache.rs
@@ -1,45 +1,139 @@
 //! Workspace cache — bare-repo cache layer for manifest repos
 //!
-//! Each manifest repo gets a bare clone under `.grip/cache/<name>.git`.
-//! These caches serve as fast local references for creating agent workspaces
-//! and manual checkouts without sharing mutable .git state.
+//! Caches now live at a machine-level root by default (`~/.grip/cache/`),
+//! keyed by normalized remote URL rather than workspace-local repo name.
+//! This lets multiple workspaces reuse the same object store without sharing
+//! mutable `.git` state between checkouts.
 
 use anyhow::{Context, Result};
+use std::env;
 use std::path::{Path, PathBuf};
 use std::process::Command;
 
 use crate::util::log_cmd;
 
-/// Directory name under .grip/ where bare caches live.
+const CACHE_ENV_VAR: &str = "GRIP_CACHE_DIR";
+const GRIP_DIR: &str = ".grip";
 const CACHE_DIR: &str = "cache";
 
-/// Resolve the cache path for a repo: `<workspace_root>/.grip/cache/<name>.git`
-pub fn cache_path(workspace_root: &Path, repo_name: &str) -> PathBuf {
+fn home_dir() -> Result<PathBuf> {
+    if let Some(home) = env::var_os("HOME") {
+        return Ok(PathBuf::from(home));
+    }
+    if let Some(profile) = env::var_os("USERPROFILE") {
+        return Ok(PathBuf::from(profile));
+    }
+    anyhow::bail!("could not resolve home directory for global cache root")
+}
+
+/// Resolve the machine-level cache root.
+pub fn cache_root() -> Result<PathBuf> {
+    if let Some(override_dir) = env::var_os(CACHE_ENV_VAR) {
+        return Ok(PathBuf::from(override_dir));
+    }
+    Ok(home_dir()?.join(GRIP_DIR).join(CACHE_DIR))
+}
+
+fn legacy_cache_path(workspace_root: &Path, repo_name: &str) -> PathBuf {
     workspace_root
-        .join(".grip")
+        .join(GRIP_DIR)
         .join(CACHE_DIR)
         .join(format!("{}.git", repo_name))
 }
 
-/// Check whether a bare cache exists for the given repo.
-pub fn cache_exists(workspace_root: &Path, repo_name: &str) -> bool {
-    let path = cache_path(workspace_root, repo_name);
-    // A valid bare repo has a HEAD file
+fn normalize_git_url(url: &str) -> String {
+    let trimmed = url.trim().trim_end_matches('/').trim_end_matches(".git");
+
+    if !trimmed.contains("://") {
+        if let Some((user_host, path)) = trimmed.split_once(':') {
+            let host = user_host.rsplit('@').next().unwrap_or(user_host);
+            if !host.is_empty() && !path.is_empty() {
+                return format!(
+                    "{}:{}",
+                    host.to_ascii_lowercase(),
+                    path.trim_start_matches('/')
+                );
+            }
+        }
+    }
+
+    if let Some((_, rest)) = trimmed.split_once("://") {
+        if let Some((host_user, path)) = rest.split_once('/') {
+            let host = host_user.rsplit('@').next().unwrap_or(host_user);
+            if !host.is_empty() && !path.is_empty() {
+                return format!(
+                    "{}:{}",
+                    host.to_ascii_lowercase(),
+                    path.trim_start_matches('/')
+                );
+            }
+        }
+    }
+
+    trimmed.to_string()
+}
+
+/// Stable filesystem-safe cache key derived from a normalized remote URL.
+pub fn cache_key(url: &str) -> String {
+    let normalized = normalize_git_url(url);
+    let mut key = String::with_capacity(normalized.len());
+    let mut last_was_sep = false;
+
+    for ch in normalized.chars() {
+        if ch.is_ascii_alphanumeric() {
+            key.push(ch.to_ascii_lowercase());
+            last_was_sep = false;
+        } else if !last_was_sep {
+            key.push('_');
+            last_was_sep = true;
+        }
+    }
+
+    key.trim_matches('_').to_string()
+}
+
+/// Resolve the primary global cache path for a repo URL.
+pub fn cache_path(url: &str) -> Result<PathBuf> {
+    Ok(cache_root()?.join(format!("{}.git", cache_key(url))))
+}
+
+fn cache_is_valid(path: &Path) -> bool {
     path.join("HEAD").is_file()
 }
 
+/// Resolve the cache path to use, preferring the global cache but falling back
+/// to an existing legacy workspace-local cache.
+pub fn resolve_cache_path(workspace_root: &Path, repo_name: &str, url: &str) -> Result<PathBuf> {
+    let global = cache_path(url)?;
+    if cache_is_valid(&global) {
+        return Ok(global);
+    }
+
+    let legacy = legacy_cache_path(workspace_root, repo_name);
+    if cache_is_valid(&legacy) {
+        return Ok(legacy);
+    }
+
+    Ok(global)
+}
+
+/// Check whether a cache exists for the given repo.
+pub fn cache_exists(workspace_root: &Path, repo_name: &str, url: &str) -> Result<bool> {
+    Ok(cache_is_valid(&resolve_cache_path(
+        workspace_root,
+        repo_name,
+        url,
+    )?))
+}
+
 /// Bootstrap a bare cache by cloning from the canonical remote.
-///
-/// Creates `.grip/cache/<name>.git` as a bare clone of `url`.
-/// If the cache already exists, this is a no-op (use `update_cache` to fetch).
 pub fn bootstrap_cache(workspace_root: &Path, repo_name: &str, url: &str) -> Result<()> {
-    let path = cache_path(workspace_root, repo_name);
-
-    if cache_exists(workspace_root, repo_name) {
+    let existing = resolve_cache_path(workspace_root, repo_name, url)?;
+    if cache_is_valid(&existing) {
         return Ok(());
     }
 
-    // Ensure parent directory exists
+    let path = cache_path(url)?;
     if let Some(parent) = path.parent() {
         std::fs::create_dir_all(parent)
             .with_context(|| format!("creating cache directory: {}", parent.display()))?;
@@ -66,12 +160,10 @@ pub fn bootstrap_cache(workspace_root: &Path, repo_name: &str, url: &str) -> Res
 }
 
 /// Fetch latest refs into an existing bare cache.
-///
-/// Runs `git fetch --all --prune` inside the bare repo to bring it up to date.
-pub fn update_cache(workspace_root: &Path, repo_name: &str) -> Result<()> {
-    let path = cache_path(workspace_root, repo_name);
+pub fn update_cache(workspace_root: &Path, repo_name: &str, url: &str) -> Result<()> {
+    let path = resolve_cache_path(workspace_root, repo_name, url)?;
 
-    if !cache_exists(workspace_root, repo_name) {
+    if !cache_is_valid(&path) {
         anyhow::bail!("cache does not exist for {}: {}", repo_name, path.display());
     }
 
@@ -96,10 +188,14 @@ pub fn update_cache(workspace_root: &Path, repo_name: &str) -> Result<()> {
 }
 
 /// Get the remote URL stored in a bare cache.
-pub fn cache_remote_url(workspace_root: &Path, repo_name: &str) -> Result<Option<String>> {
-    let path = cache_path(workspace_root, repo_name);
+pub fn cache_remote_url(
+    workspace_root: &Path,
+    repo_name: &str,
+    url: &str,
+) -> Result<Option<String>> {
+    let path = resolve_cache_path(workspace_root, repo_name, url)?;
 
-    if !cache_exists(workspace_root, repo_name) {
+    if !cache_is_valid(&path) {
         return Ok(None);
     }
 
@@ -121,16 +217,13 @@ pub fn cache_remote_url(workspace_root: &Path, repo_name: &str) -> Result<Option
 }
 
 /// Bootstrap caches for all repos in a manifest.
-///
-/// Takes an iterator of (name, url) pairs. Skips repos that already have caches.
-/// Returns the count of newly bootstrapped caches.
 pub fn bootstrap_all<'a>(
     workspace_root: &Path,
     repos: impl Iterator<Item = (&'a str, &'a str)>,
 ) -> Result<usize> {
     let mut count = 0;
     for (name, url) in repos {
-        if !cache_exists(workspace_root, name) {
+        if !cache_exists(workspace_root, name, url)? {
             bootstrap_cache(workspace_root, name, url)?;
             count += 1;
         }
@@ -138,24 +231,15 @@ pub fn bootstrap_all<'a>(
     Ok(count)
 }
 
-/// Update all existing caches under `.grip/cache/`.
-///
-/// Returns the count of caches updated.
-pub fn update_all(workspace_root: &Path) -> Result<usize> {
-    let cache_dir = workspace_root.join(".grip").join(CACHE_DIR);
-    if !cache_dir.is_dir() {
-        return Ok(0);
-    }
-
+/// Update all caches for repos in the current manifest.
+pub fn update_all<'a>(
+    workspace_root: &Path,
+    repos: impl Iterator<Item = (&'a str, &'a str)>,
+) -> Result<usize> {
     let mut count = 0;
-    for entry in std::fs::read_dir(&cache_dir)? {
-        let entry = entry?;
-        let name = entry.file_name();
-        let name_str = name.to_string_lossy();
-        // Cache dirs are named <repo>.git
-        if name_str.ends_with(".git") && entry.path().join("HEAD").is_file() {
-            let repo_name = name_str.trim_end_matches(".git");
-            update_cache(workspace_root, repo_name)?;
+    for (name, url) in repos {
+        if cache_exists(workspace_root, name, url)? {
+            update_cache(workspace_root, name, url)?;
             count += 1;
         }
     }
@@ -163,8 +247,8 @@ pub fn update_all(workspace_root: &Path) -> Result<usize> {
 }
 
 /// Remove a single repo cache.
-pub fn remove_cache(workspace_root: &Path, repo_name: &str) -> Result<bool> {
-    let path = cache_path(workspace_root, repo_name);
+pub fn remove_cache(workspace_root: &Path, repo_name: &str, url: &str) -> Result<bool> {
+    let path = resolve_cache_path(workspace_root, repo_name, url)?;
     if path.is_dir() {
         std::fs::remove_dir_all(&path)
             .with_context(|| format!("removing cache: {}", path.display()))?;
@@ -174,22 +258,41 @@ pub fn remove_cache(workspace_root: &Path, repo_name: &str) -> Result<bool> {
     }
 }
 
+#[cfg(test)]
+pub(crate) mod test_support {
+    use once_cell::sync::Lazy;
+    use std::sync::Mutex;
+
+    pub(crate) static ENV_LOCK: Lazy<Mutex<()>> = Lazy::new(|| Mutex::new(()));
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
     use std::fs;
 
-    /// Helper: create a temporary "remote" repo to clone from
+    fn with_cache_dir<T>(cache_dir: &Path, f: impl FnOnce() -> T) -> T {
+        let _guard = test_support::ENV_LOCK
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        let previous = env::var_os(CACHE_ENV_VAR);
+        env::set_var(CACHE_ENV_VAR, cache_dir);
+        let result = f();
+        match previous {
+            Some(value) => env::set_var(CACHE_ENV_VAR, value),
+            None => env::remove_var(CACHE_ENV_VAR),
+        }
+        result
+    }
+
     fn create_test_remote(dir: &Path) -> PathBuf {
         let remote_path = dir.join("remote-repo.git");
-        // Init a bare repo to act as the remote
         Command::new("git")
             .args(["init", "--bare"])
             .arg(&remote_path)
             .output()
             .expect("git init --bare");
 
-        // Create a non-bare repo, add a commit, push to the bare repo
         let work_path = dir.join("work-repo");
         Command::new("git")
             .args(["init"])
@@ -227,7 +330,7 @@ mod tests {
             .args(["push", "origin", "main"])
             .current_dir(&work_path)
             .output()
-            .ok(); // might be master, not main
+            .ok();
         Command::new("git")
             .args(["push", "origin", "master"])
             .current_dir(&work_path)
@@ -238,16 +341,37 @@ mod tests {
     }
 
     #[test]
-    fn test_cache_path() {
-        let root = Path::new("/workspace");
-        let path = cache_path(root, "myrepo");
-        assert_eq!(path, PathBuf::from("/workspace/.grip/cache/myrepo.git"));
+    fn test_cache_key_normalizes_remote_url_forms() {
+        let ssh = cache_key("git@github.com:OpenAI/myrepo.git");
+        let https = cache_key("https://github.com/OpenAI/myrepo.git");
+        assert_eq!(ssh, "github_com_openai_myrepo");
+        assert_eq!(ssh, https);
+    }
+
+    #[test]
+    fn test_cache_path_uses_global_root() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let cache_dir = tmp.path().join("global-cache");
+        with_cache_dir(&cache_dir, || {
+            let path = cache_path("git@github.com:OpenAI/myrepo.git").expect("cache path");
+            assert_eq!(path, cache_dir.join("github_com_openai_myrepo.git"));
+        });
     }
 
     #[test]
     fn test_cache_does_not_exist_initially() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        assert!(!cache_exists(tmp.path(), "nonexistent"));
+        let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
+        fs::create_dir_all(&workspace).expect("mkdir workspace");
+        with_cache_dir(&cache_dir, || {
+            assert!(!cache_exists(
+                &workspace,
+                "nonexistent",
+                "git@github.com:user/nonexistent.git"
+            )
+            .expect("cache exists"));
+        });
     }
 
     #[test]
@@ -255,18 +379,20 @@ mod tests {
         let tmp = tempfile::tempdir().expect("tempdir");
         let remote = create_test_remote(tmp.path());
         let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
         fs::create_dir_all(&workspace).expect("mkdir workspace");
 
         let url = remote.to_string_lossy().to_string();
-        assert!(!cache_exists(&workspace, "testrepo"));
+        with_cache_dir(&cache_dir, || {
+            assert!(!cache_exists(&workspace, "testrepo", &url).expect("cache exists before"));
 
-        bootstrap_cache(&workspace, "testrepo", &url).expect("bootstrap");
-        assert!(cache_exists(&workspace, "testrepo"));
+            bootstrap_cache(&workspace, "testrepo", &url).expect("bootstrap");
+            assert!(cache_exists(&workspace, "testrepo", &url).expect("cache exists after"));
 
-        // Verify it's a bare repo
-        let cp = cache_path(&workspace, "testrepo");
-        assert!(cp.join("HEAD").is_file());
-        assert!(!cp.join(".git").exists()); // bare repos don't have .git subdir
+            let cp = cache_path(&url).expect("cache path");
+            assert!(cp.join("HEAD").is_file());
+            assert!(!cp.join(".git").exists());
+        });
     }
 
     #[test]
@@ -274,12 +400,15 @@ mod tests {
         let tmp = tempfile::tempdir().expect("tempdir");
         let remote = create_test_remote(tmp.path());
         let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
         fs::create_dir_all(&workspace).expect("mkdir workspace");
 
         let url = remote.to_string_lossy().to_string();
-        bootstrap_cache(&workspace, "repo", &url).expect("bootstrap 1");
-        bootstrap_cache(&workspace, "repo", &url).expect("bootstrap 2"); // no-op
-        assert!(cache_exists(&workspace, "repo"));
+        with_cache_dir(&cache_dir, || {
+            bootstrap_cache(&workspace, "repo", &url).expect("bootstrap 1");
+            bootstrap_cache(&workspace, "repo", &url).expect("bootstrap 2");
+            assert!(cache_exists(&workspace, "repo", &url).expect("cache exists"));
+        });
     }
 
     #[test]
@@ -287,18 +416,26 @@ mod tests {
         let tmp = tempfile::tempdir().expect("tempdir");
         let remote = create_test_remote(tmp.path());
         let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
         fs::create_dir_all(&workspace).expect("mkdir workspace");
 
         let url = remote.to_string_lossy().to_string();
-        bootstrap_cache(&workspace, "repo", &url).expect("bootstrap");
-        update_cache(&workspace, "repo").expect("update");
+        with_cache_dir(&cache_dir, || {
+            bootstrap_cache(&workspace, "repo", &url).expect("bootstrap");
+            update_cache(&workspace, "repo", &url).expect("update");
+        });
     }
 
     #[test]
     fn test_update_nonexistent_fails() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let result = update_cache(tmp.path(), "nope");
-        assert!(result.is_err());
+        let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
+        fs::create_dir_all(&workspace).expect("mkdir workspace");
+        with_cache_dir(&cache_dir, || {
+            let result = update_cache(&workspace, "nope", "git@github.com:user/nope.git");
+            assert!(result.is_err());
+        });
     }
 
     #[test]
@@ -306,15 +443,18 @@ mod tests {
         let tmp = tempfile::tempdir().expect("tempdir");
         let remote = create_test_remote(tmp.path());
         let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
         fs::create_dir_all(&workspace).expect("mkdir workspace");
 
         let url = remote.to_string_lossy().to_string();
-        bootstrap_cache(&workspace, "repo", &url).expect("bootstrap");
-
-        let stored_url = cache_remote_url(&workspace, "repo")
-            .expect("get url")
-            .expect("has url");
-        assert_eq!(stored_url, url);
+        with_cache_dir(&cache_dir, || {
+            bootstrap_cache(&workspace, "repo", &url).expect("bootstrap");
+
+            let stored_url = cache_remote_url(&workspace, "repo", &url)
+                .expect("get url")
+                .expect("has url");
+            assert_eq!(stored_url, url);
+        });
     }
 
     #[test]
@@ -322,22 +462,31 @@ mod tests {
         let tmp = tempfile::tempdir().expect("tempdir");
         let remote = create_test_remote(tmp.path());
         let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
         fs::create_dir_all(&workspace).expect("mkdir workspace");
 
         let url = remote.to_string_lossy().to_string();
-        bootstrap_cache(&workspace, "repo", &url).expect("bootstrap");
-        assert!(cache_exists(&workspace, "repo"));
-
-        let removed = remove_cache(&workspace, "repo").expect("remove");
-        assert!(removed);
-        assert!(!cache_exists(&workspace, "repo"));
+        with_cache_dir(&cache_dir, || {
+            bootstrap_cache(&workspace, "repo", &url).expect("bootstrap");
+            assert!(cache_exists(&workspace, "repo", &url).expect("cache exists"));
+
+            let removed = remove_cache(&workspace, "repo", &url).expect("remove");
+            assert!(removed);
+            assert!(!cache_exists(&workspace, "repo", &url).expect("cache removed"));
+        });
     }
 
     #[test]
     fn test_remove_nonexistent_returns_false() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let removed = remove_cache(tmp.path(), "nope").expect("remove");
-        assert!(!removed);
+        let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
+        fs::create_dir_all(&workspace).expect("mkdir workspace");
+        with_cache_dir(&cache_dir, || {
+            let removed =
+                remove_cache(&workspace, "nope", "git@github.com:user/nope.git").expect("remove");
+            assert!(!removed);
+        });
     }
 
     #[test]
@@ -345,18 +494,33 @@ mod tests {
         let tmp = tempfile::tempdir().expect("tempdir");
         let remote = create_test_remote(tmp.path());
         let workspace = tmp.path().join("workspace");
+        let cache_dir = tmp.path().join("global-cache");
         fs::create_dir_all(&workspace).expect("mkdir workspace");
 
         let url = remote.to_string_lossy().to_string();
-        let repos = vec![("repo1", url.as_str()), ("repo2", url.as_str())];
-        let count = bootstrap_all(&workspace, repos.into_iter()).expect("bootstrap all");
-        assert_eq!(count, 2);
-        assert!(cache_exists(&workspace, "repo1"));
-        assert!(cache_exists(&workspace, "repo2"));
-
-        // Second call: no new bootstraps
-        let repos2 = vec![("repo1", url.as_str()), ("repo2", url.as_str())];
-        let count2 = bootstrap_all(&workspace, repos2.into_iter()).expect("bootstrap all 2");
-        assert_eq!(count2, 0);
+        with_cache_dir(&cache_dir, || {
+            let repos = vec![("repo1", url.as_str()), ("repo2", url.as_str())];
+            let count = bootstrap_all(&workspace, repos.into_iter()).expect("bootstrap all");
+            assert_eq!(count, 1);
+            assert!(cache_exists(&workspace, "repo1", &url).expect("repo1 cached"));
+            assert!(cache_exists(&workspace, "repo2", &url).expect("repo2 cached"));
+
+            let repos2 = vec![("repo1", url.as_str()), ("repo2", url.as_str())];
+            let count2 = bootstrap_all(&workspace, repos2.into_iter()).expect("bootstrap all 2");
+            assert_eq!(count2, 0);
+        });
+    }
+
+    #[test]
+    fn test_resolve_cache_path_falls_back_to_legacy_workspace_cache() {
+        let tmp = tempfile::tempdir().expect("tempdir");
+        let workspace = tmp.path().join("workspace");
+        let legacy = workspace.join(".grip/cache/repo.git");
+        fs::create_dir_all(&legacy).expect("mkdir legacy cache");
+        fs::write(legacy.join("HEAD"), "ref: refs/heads/main\n").expect("write head");
+
+        let resolved = resolve_cache_path(&workspace, "repo", "git@github.com:org/repo.git")
+            .expect("resolve path");
+        assert_eq!(resolved, legacy);
     }
 }
diff --git a/src/core/workspace_checkout.rs b/src/core/workspace_checkout.rs
index 1e31808b..cc7fe49b 100644
--- a/src/core/workspace_checkout.rs
+++ b/src/core/workspace_checkout.rs
@@ -69,8 +69,8 @@ pub fn materialize_repo(
             .with_context(|| format!("creating checkout dir: {}", parent.display()))?;
     }
 
-    let cache = workspace_cache::cache_path(workspace_root, repo_name);
-    let has_cache = workspace_cache::cache_exists(workspace_root, repo_name);
+    let cache = workspace_cache::resolve_cache_path(workspace_root, repo_name, repo_url)?;
+    let has_cache = workspace_cache::cache_exists(workspace_root, repo_name, repo_url)?;
 
     let mut cmd = Command::new("git");
     cmd.arg("clone");
@@ -200,8 +200,23 @@ pub fn remove_checkout(workspace_root: &Path, name: &str) -> Result<bool> {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::core::workspace_cache::test_support;
     use std::fs;
 
+    fn with_cache_dir<T>(cache_dir: &Path, f: impl FnOnce() -> T) -> T {
+        let _guard = test_support::ENV_LOCK
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        let previous = std::env::var_os("GRIP_CACHE_DIR");
+        std::env::set_var("GRIP_CACHE_DIR", cache_dir);
+        let result = f();
+        match previous {
+            Some(value) => std::env::set_var("GRIP_CACHE_DIR", value),
+            None => std::env::remove_var("GRIP_CACHE_DIR"),
+        }
+        result
+    }
+
     /// Helper: create a test remote repo and bootstrap its cache
     fn setup_cached_workspace(dir: &Path) -> (PathBuf, PathBuf) {
         let remote_path = dir.join("remote-repo.git");
@@ -279,111 +294,127 @@ mod tests {
     #[test]
     fn test_materialize_single_repo() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let (workspace, remote) = setup_cached_workspace(tmp.path());
-
-        let url = remote.to_string_lossy().to_string();
-        let target = materialize_repo(
-            &workspace,
-            "test-checkout",
-            "testrepo",
-            &url,
-            "testrepo",
-            None,
-        )
-        .expect("materialize");
-
-        assert!(target.join(".git").exists());
-        assert!(target.join("README.md").exists());
+        let cache_dir = tmp.path().join("global-cache");
+        with_cache_dir(&cache_dir, || {
+            let (workspace, remote) = setup_cached_workspace(tmp.path());
+
+            let url = remote.to_string_lossy().to_string();
+            let target = materialize_repo(
+                &workspace,
+                "test-checkout",
+                "testrepo",
+                &url,
+                "testrepo",
+                None,
+            )
+            .expect("materialize");
+
+            assert!(target.join(".git").exists());
+            assert!(target.join("README.md").exists());
+        });
     }
 
     #[test]
     fn test_materialize_is_independent_clone() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let (workspace, remote) = setup_cached_workspace(tmp.path());
-
-        let url = remote.to_string_lossy().to_string();
-        let target = materialize_repo(
-            &workspace,
-            "independent",
-            "testrepo",
-            &url,
-            "testrepo",
-            None,
-        )
-        .expect("materialize");
-
-        // The clone has its own .git directory (not a worktree link)
-        assert!(target.join(".git").is_dir());
-        // Not a file pointing elsewhere (that would be a worktree)
-        assert!(!target.join(".git").is_file());
+        let cache_dir = tmp.path().join("global-cache");
+        with_cache_dir(&cache_dir, || {
+            let (workspace, remote) = setup_cached_workspace(tmp.path());
+
+            let url = remote.to_string_lossy().to_string();
+            let target = materialize_repo(
+                &workspace,
+                "independent",
+                "testrepo",
+                &url,
+                "testrepo",
+                None,
+            )
+            .expect("materialize");
+
+            assert!(target.join(".git").is_dir());
+            assert!(!target.join(".git").is_file());
+        });
     }
 
     #[test]
     fn test_materialize_uses_cache_reference() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let (workspace, remote) = setup_cached_workspace(tmp.path());
-
-        let url = remote.to_string_lossy().to_string();
-        let target = materialize_repo(&workspace, "ref-test", "testrepo", &url, "testrepo", None)
-            .expect("materialize");
-
-        // Check alternates file exists (proves --reference was used)
-        let alternates = target.join(".git/objects/info/alternates");
-        assert!(alternates.is_file(), "alternates file should exist");
-        let content = fs::read_to_string(&alternates).expect("read alternates");
-        assert!(
-            content.contains("cache/testrepo.git"),
-            "alternates should reference the cache"
-        );
+        let cache_dir = tmp.path().join("global-cache");
+        with_cache_dir(&cache_dir, || {
+            let (workspace, remote) = setup_cached_workspace(tmp.path());
+
+            let url = remote.to_string_lossy().to_string();
+            let target =
+                materialize_repo(&workspace, "ref-test", "testrepo", &url, "testrepo", None)
+                    .expect("materialize");
+
+            let alternates = target.join(".git/objects/info/alternates");
+            assert!(alternates.is_file(), "alternates file should exist");
+            let content = fs::read_to_string(&alternates).expect("read alternates");
+            assert!(
+                content.contains(&workspace_cache::cache_key(&url)),
+                "alternates should reference the global cache path"
+            );
+        });
     }
 
     #[test]
     fn test_create_and_list_checkout() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let (workspace, remote) = setup_cached_workspace(tmp.path());
+        let cache_dir = tmp.path().join("global-cache");
+        with_cache_dir(&cache_dir, || {
+            let (workspace, remote) = setup_cached_workspace(tmp.path());
 
-        let url = remote.to_string_lossy().to_string();
-        let repos = vec![("testrepo", url.as_str(), "testrepo")];
+            let url = remote.to_string_lossy().to_string();
+            let repos = vec![("testrepo", url.as_str(), "testrepo")];
 
-        let info = create_checkout(&workspace, "feat-x", repos.into_iter(), None)
-            .expect("create checkout");
+            let info = create_checkout(&workspace, "feat-x", repos.into_iter(), None)
+                .expect("create checkout");
 
-        assert_eq!(info.name, "feat-x");
-        assert_eq!(info.repos.len(), 1);
-        assert!(checkout_exists(&workspace, "feat-x"));
+            assert_eq!(info.name, "feat-x");
+            assert_eq!(info.repos.len(), 1);
+            assert!(checkout_exists(&workspace, "feat-x"));
 
-        let all = list_checkouts(&workspace).expect("list");
-        assert_eq!(all.len(), 1);
-        assert_eq!(all[0].name, "feat-x");
+            let all = list_checkouts(&workspace).expect("list");
+            assert_eq!(all.len(), 1);
+            assert_eq!(all[0].name, "feat-x");
+        });
     }
 
     #[test]
     fn test_create_duplicate_fails() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let (workspace, remote) = setup_cached_workspace(tmp.path());
+        let cache_dir = tmp.path().join("global-cache");
+        with_cache_dir(&cache_dir, || {
+            let (workspace, remote) = setup_cached_workspace(tmp.path());
 
-        let url = remote.to_string_lossy().to_string();
-        let repos = vec![("testrepo", url.as_str(), "testrepo")];
-        create_checkout(&workspace, "dup", repos.into_iter(), None).expect("first");
+            let url = remote.to_string_lossy().to_string();
+            let repos = vec![("testrepo", url.as_str(), "testrepo")];
+            create_checkout(&workspace, "dup", repos.into_iter(), None).expect("first");
 
-        let repos2 = vec![("testrepo", url.as_str(), "testrepo")];
-        let result = create_checkout(&workspace, "dup", repos2.into_iter(), None);
-        assert!(result.is_err());
+            let repos2 = vec![("testrepo", url.as_str(), "testrepo")];
+            let result = create_checkout(&workspace, "dup", repos2.into_iter(), None);
+            assert!(result.is_err());
+        });
     }
 
     #[test]
     fn test_remove_checkout() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let (workspace, remote) = setup_cached_workspace(tmp.path());
-
-        let url = remote.to_string_lossy().to_string();
-        let repos = vec![("testrepo", url.as_str(), "testrepo")];
-        create_checkout(&workspace, "removeme", repos.into_iter(), None).expect("create");
-
-        assert!(checkout_exists(&workspace, "removeme"));
-        let removed = remove_checkout(&workspace, "removeme").expect("remove");
-        assert!(removed);
-        assert!(!checkout_exists(&workspace, "removeme"));
+        let cache_dir = tmp.path().join("global-cache");
+        with_cache_dir(&cache_dir, || {
+            let (workspace, remote) = setup_cached_workspace(tmp.path());
+
+            let url = remote.to_string_lossy().to_string();
+            let repos = vec![("testrepo", url.as_str(), "testrepo")];
+            create_checkout(&workspace, "removeme", repos.into_iter(), None).expect("create");
+
+            assert!(checkout_exists(&workspace, "removeme"));
+            let removed = remove_checkout(&workspace, "removeme").expect("remove");
+            assert!(removed);
+            assert!(!checkout_exists(&workspace, "removeme"));
+        });
     }
 
     #[test]
@@ -396,19 +427,20 @@ mod tests {
     #[test]
     fn test_cache_survives_checkout_removal() {
         let tmp = tempfile::tempdir().expect("tempdir");
-        let (workspace, remote) = setup_cached_workspace(tmp.path());
+        let cache_dir = tmp.path().join("global-cache");
+        with_cache_dir(&cache_dir, || {
+            let (workspace, remote) = setup_cached_workspace(tmp.path());
 
-        let url = remote.to_string_lossy().to_string();
-        let repos = vec![("testrepo", url.as_str(), "testrepo")];
-        create_checkout(&workspace, "ephemeral", repos.into_iter(), None).expect("create");
+            let url = remote.to_string_lossy().to_string();
+            let repos = vec![("testrepo", url.as_str(), "testrepo")];
+            create_checkout(&workspace, "ephemeral", repos.into_iter(), None).expect("create");
 
-        // Remove the checkout
-        remove_checkout(&workspace, "ephemeral").expect("remove");
+            remove_checkout(&workspace, "ephemeral").expect("remove");
 
-        // Cache must still exist — this is a first-class guarantee
-        assert!(
-            workspace_cache::cache_exists(&workspace, "testrepo"),
-            "cache must survive checkout deletion"
-        );
+            assert!(
+                workspace_cache::cache_exists(&workspace, "testrepo", &url).expect("cache exists"),
+                "cache must survive checkout deletion"
+            );
+        });
     }
 }

From 737da04ea8bd3847a64ab540b96248c6a0145bf0 Mon Sep 17 00:00:00 2001
From: Layne Penney <dev@layne.pro>
Date: Wed, 8 Apr 2026 12:09:45 -0500
Subject: [PATCH 04/15] feat: add cache-backed checkout creation (#485)

---
 README.md                    |  28 +++++
 src/cli/args.rs              |  10 +-
 src/cli/commands/checkout.rs |  50 +++++++++
 src/cli/dispatch.rs          |  53 ++++++---
 tests/cli_tests.rs           | 209 +++++++++++++++++++++++++++++++++++
 5 files changed, 333 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index f7c01a28..97cc73da 100644
--- a/README.md
+++ b/README.md
@@ -150,6 +150,7 @@ gr sync
 | `gr branch [name]` | Create or list branches |
 | `gr checkout <branch>` | Checkout branch across repos |
 | `gr checkout -b <branch>` | Create and checkout branch in one command |
+| `gr checkout add <name>` | Create an independent child checkout from cached repos |
 | `gr add [files]` | Stage changes across repos |
 | `gr diff` | Show diff across repos |
 | `gr commit -m "msg"` | Commit across repos |
@@ -263,6 +264,33 @@ Checkout a branch across all repos. Can also create branches with the `-b` flag.
 | `-b` | Create branch if it doesn't exist |
 | `--base` | Checkout the griptree base branch (griptree workspaces only) |
 
+#### `gr checkout add <name>`
+
+Create an independent child checkout under `.grip/checkouts/<name>/` using the
+workspace cache as an accelerator.
+
+Unlike `gr tree add`, this creates normal child clones with their own `.git`
+directories. The checkout keeps the canonical remote URL as `origin`; the cache
+is only used to speed up materialization.
+
+| Option | Description |
+|--------|-------------|
+| `--repo <name>` | Only materialize specific repos |
+| `--group <name>` | Only materialize repos in a group |
+
+**Examples:**
+
+```bash
+# Materialize all repos into an independent child checkout
+gr checkout add sandbox
+
+# Materialize only the docs group
+gr checkout add docs-only --group docs
+
+# Materialize just one repo
+gr checkout add app-only --repo app
+```
+
 #### `gr branch [name]`
 
 Create a new branch across all repositories, or list existing branches. Manifest repo is always included.
diff --git a/src/cli/args.rs b/src/cli/args.rs
index b840f020..a620a455 100644
--- a/src/cli/args.rs
+++ b/src/cli/args.rs
@@ -126,10 +126,16 @@ pub enum Commands {
         #[arg(long, value_delimiter = ',')]
         group: Option<Vec<String>>,
     },
-    /// Checkout a branch across repos
+    #[command(
+        after_help = "Examples:\n  gr checkout feat/login\n  gr checkout --base\n  gr checkout add sandbox\n  gr checkout add docs-only --group docs\n  gr checkout add app-only --repo app"
+    )]
+    /// Checkout a branch across repos or create an independent child checkout
     Checkout {
-        /// Branch name
+        /// Branch name, or `add` to create an independent child checkout
         name: Option<String>,
+        /// Additional checkout action args (e.g. `add <name>`)
+        #[arg(hide = true)]
+        extra: Vec<String>,
         /// Create branch if it doesn't exist
         #[arg(short = 'b', long)]
         create: bool,
diff --git a/src/cli/commands/checkout.rs b/src/cli/commands/checkout.rs
index ffa10269..c44ddd5d 100644
--- a/src/cli/commands/checkout.rs
+++ b/src/cli/commands/checkout.rs
@@ -3,6 +3,7 @@
 use crate::cli::output::Output;
 use crate::core::manifest::Manifest;
 use crate::core::repo::{filter_repos, get_manifest_repo_info, RepoInfo};
+use crate::core::workspace_checkout;
 use crate::git::{
     branch::{branch_exists, checkout_branch, create_and_checkout_branch},
     open_repo,
@@ -113,3 +114,52 @@ pub fn run_checkout(
 
     Ok(())
 }
+
+/// Materialize an independent child checkout from cached repos.
+///
+/// This reserves `gr checkout add <name>` while preserving the existing
+/// `gr checkout <branch>` behavior for cross-repo branch switching.
+pub fn run_checkout_add(
+    workspace_root: &Path,
+    manifest: &Manifest,
+    checkout_name: &str,
+    repos_filter: Option<&[String]>,
+    group_filter: Option<&[String]>,
+) -> anyhow::Result<()> {
+    let mut repos: Vec<RepoInfo> =
+        filter_repos(manifest, workspace_root, repos_filter, group_filter, false);
+
+    let include_manifest = match repos_filter {
+        None => true,
+        Some(filter) => filter.iter().any(|r| r == "manifest"),
+    };
+    if include_manifest {
+        if let Some(manifest_repo) = get_manifest_repo_info(manifest, workspace_root) {
+            repos.push(manifest_repo);
+        }
+    }
+
+    if repos.is_empty() {
+        anyhow::bail!("no repos matched checkout filters");
+    }
+
+    let repo_specs: Vec<(&str, &str, &str)> = repos
+        .iter()
+        .map(|repo| (repo.name.as_str(), repo.url.as_str(), repo.path.as_str()))
+        .collect();
+
+    let info = workspace_checkout::create_checkout(
+        workspace_root,
+        checkout_name,
+        repo_specs.into_iter(),
+        None,
+    )?;
+
+    Output::success(&format!(
+        "Created checkout '{}' with {} repo(s)",
+        info.name,
+        info.repos.len()
+    ));
+    Output::info(&format!("Path: {}", info.path.display()));
+    Ok(())
+}
diff --git a/src/cli/dispatch.rs b/src/cli/dispatch.rs
index b18bb3fb..8c430887 100644
--- a/src/cli/dispatch.rs
+++ b/src/cli/dispatch.rs
@@ -93,30 +93,53 @@ pub async fn dispatch_command(
         }
         Some(Commands::Checkout {
             name,
+            extra,
             create,
             base,
             repo,
             group,
         }) => {
             let ctx = load_workspace_context(quiet, verbose, json)?;
-            let branch = if base {
-                let config = crate::core::griptree::GriptreeConfig::load_from_workspace(
+
+            if matches!(name.as_deref(), Some("add")) {
+                // `add` is reserved for checkout materialization, not branch switching.
+                if create || base {
+                    anyhow::bail!("--create and --base are not valid with 'add'");
+                }
+                if extra.len() > 1 {
+                    anyhow::bail!("unexpected extra arguments after checkout name");
+                }
+                let checkout_name = extra.first().ok_or_else(|| {
+                    anyhow::anyhow!("Checkout name is required: gr checkout add <name>")
+                })?;
+
+                crate::cli::commands::checkout::run_checkout_add(
                     &ctx.workspace_root,
-                )?
-                .ok_or_else(|| anyhow::anyhow!("Not in a griptree workspace"))?;
-                config.branch
+                    &ctx.manifest,
+                    checkout_name,
+                    repo.as_deref(),
+                    group.as_deref(),
+                )?;
             } else {
-                name.ok_or_else(|| anyhow::anyhow!("Branch name is required"))?
-            };
+                let branch = if base {
+                    let config = crate::core::griptree::GriptreeConfig::load_from_workspace(
+                        &ctx.workspace_root,
+                    )?
+                    .ok_or_else(|| anyhow::anyhow!("Not in a griptree workspace"))?;
+                    config.branch
+                } else {
+                    name.ok_or_else(|| anyhow::anyhow!("Branch name is required"))?
+                };
 
-            crate::cli::commands::checkout::run_checkout(
-                &ctx.workspace_root,
-                &ctx.manifest,
-                &branch,
-                create,
-                repo.as_deref(),
-                group.as_deref(),
-            )?;
+                crate::cli::commands::checkout::run_checkout(
+                    &ctx.workspace_root,
+                    &ctx.manifest,
+                    &branch,
+                    create,
+                    repo.as_deref(),
+                    group.as_deref(),
+                )?;
+            }
         }
         Some(Commands::Add { files, repo, group }) => {
             let ctx = load_workspace_context(quiet, verbose, json)?;
diff --git a/tests/cli_tests.rs b/tests/cli_tests.rs
index e23ad564..d915e17f 100644
--- a/tests/cli_tests.rs
+++ b/tests/cli_tests.rs
@@ -545,6 +545,25 @@ fn test_gr2_repo_remove_requires_gr2_workspace() {
         ));
 }
 
+#[test]
+fn test_checkout_help_mentions_add_mode() {
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.arg("checkout")
+        .arg("--help")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "Checkout a branch across repos or create an independent child checkout",
+        ))
+        .stdout(predicate::str::contains(
+            "Branch name, or `add` to create an independent child checkout",
+        ))
+        .stdout(predicate::str::contains("gr checkout add sandbox"))
+        .stdout(predicate::str::contains(
+            "gr checkout add docs-only --group docs",
+        ));
+}
+
 /// Test that `gr status` fails gracefully outside a workspace
 #[test]
 fn test_status_outside_workspace() {
@@ -626,3 +645,193 @@ fn test_checkout_base_uses_griptree_config() {
         "feat/base"
     );
 }
+
+#[test]
+fn test_checkout_add_materializes_independent_child_checkout() {
+    let ws = WorkspaceBuilder::new()
+        .add_repo("app")
+        .add_repo("lib")
+        .build();
+
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("sandbox")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Created checkout 'sandbox'"));
+
+    let checkout_root = ws.workspace_root.join(".grip/checkouts/sandbox");
+    let app_checkout = checkout_root.join("app");
+    let lib_checkout = checkout_root.join("lib");
+    assert!(app_checkout.join(".git").is_dir());
+    assert!(!app_checkout.join(".git").is_file());
+    assert!(lib_checkout.join(".git").is_dir());
+    assert!(!lib_checkout.join(".git").is_file());
+
+    let origin = std::process::Command::new("git")
+        .args(["remote", "get-url", "origin"])
+        .current_dir(&app_checkout)
+        .output()
+        .expect("git remote get-url");
+    let origin = String::from_utf8_lossy(&origin.stdout).trim().to_string();
+    assert_eq!(origin, ws.remote_url("app"));
+}
+
+#[test]
+fn test_checkout_add_respects_repo_filter() {
+    let ws = WorkspaceBuilder::new()
+        .add_repo("app")
+        .add_repo("lib")
+        .build();
+
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("app-only")
+        .arg("--repo")
+        .arg("app")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "Created checkout 'app-only' with 1 repo(s)",
+        ));
+
+    let checkout_root = ws.workspace_root.join(".grip/checkouts/app-only");
+    assert!(checkout_root.join("app/.git").is_dir());
+    assert!(!checkout_root.join("lib").exists());
+}
+
+#[test]
+fn test_checkout_add_respects_group_filter() {
+    let ws = WorkspaceBuilder::new()
+        .add_repo_with_groups("app", vec!["product"])
+        .add_repo_with_groups("docs", vec!["docs"])
+        .build();
+
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("docs-only")
+        .arg("--group")
+        .arg("docs")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "Created checkout 'docs-only' with 1 repo(s)",
+        ));
+
+    let checkout_root = ws.workspace_root.join(".grip/checkouts/docs-only");
+    assert!(checkout_root.join("docs/.git").is_dir());
+    assert!(!checkout_root.join("app").exists());
+}
+
+#[test]
+fn test_checkout_add_requires_name() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "Checkout name is required: gr checkout add <name>",
+        ));
+}
+
+#[test]
+fn test_checkout_add_errors_when_filters_match_no_repos() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("empty")
+        .arg("--repo")
+        .arg("missing")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "no repos matched checkout filters",
+        ));
+}
+
+#[test]
+fn test_checkout_add_rejects_create_and_base_flags() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut create_cmd = Command::cargo_bin("gr").unwrap();
+    create_cmd
+        .current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("sandbox")
+        .arg("--create")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "--create and --base are not valid with 'add'",
+        ));
+
+    let mut base_cmd = Command::cargo_bin("gr").unwrap();
+    base_cmd
+        .current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("sandbox")
+        .arg("--base")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "--create and --base are not valid with 'add'",
+        ));
+}
+
+#[test]
+fn test_checkout_add_rejects_extra_positional_args() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut cmd = Command::cargo_bin("gr").unwrap();
+    cmd.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("sandbox")
+        .arg("extra")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "unexpected extra arguments after checkout name",
+        ));
+}
+
+#[test]
+fn test_checkout_add_rejects_duplicate_checkout_name() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut first = Command::cargo_bin("gr").unwrap();
+    first
+        .current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("sandbox")
+        .assert()
+        .success();
+
+    let mut duplicate = Command::cargo_bin("gr").unwrap();
+    duplicate
+        .current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("sandbox")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "checkout 'sandbox' already exists",
+        ));
+}

From af30ce96e84096d61d5f094e3782b8585dd7d66f Mon Sep 17 00:00:00 2001
From: Layne Penney <dev@layne.pro>
Date: Wed, 8 Apr 2026 12:14:22 -0500
Subject: [PATCH 05/15] feat: add checkout lifecycle commands (#489)

---
 README.md                    |  26 ++++++++
 src/cli/args.rs              |   6 +-
 src/cli/commands/checkout.rs |  32 ++++++++++
 src/cli/dispatch.rs          |  19 ++++++
 tests/cli_tests.rs           | 120 ++++++++++++++++++++++++++++++++++-
 5 files changed, 197 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 97cc73da..eba83f76 100644
--- a/README.md
+++ b/README.md
@@ -291,6 +291,32 @@ gr checkout add docs-only --group docs
 gr checkout add app-only --repo app
 ```
 
+#### `gr checkout list`
+
+Show the currently materialized child checkouts under
+`.grip/checkouts/`.
+
+**Examples:**
+
+```bash
+# List all materialized child checkouts
+gr checkout list
+```
+
+#### `gr checkout remove <name>`
+
+Remove a materialized child checkout under `.grip/checkouts/<name>/`.
+
+This deletes the child clone only. It does not delete the shared cache under
+`~/.grip/cache/`.
+
+**Examples:**
+
+```bash
+# Remove a disposable child checkout
+gr checkout remove sandbox
+```
+
 #### `gr branch [name]`
 
 Create a new branch across all repositories, or list existing branches. Manifest repo is always included.
diff --git a/src/cli/args.rs b/src/cli/args.rs
index a620a455..1dfa6ff2 100644
--- a/src/cli/args.rs
+++ b/src/cli/args.rs
@@ -127,11 +127,11 @@ pub enum Commands {
         group: Option<Vec<String>>,
     },
     #[command(
-        after_help = "Examples:\n  gr checkout feat/login\n  gr checkout --base\n  gr checkout add sandbox\n  gr checkout add docs-only --group docs\n  gr checkout add app-only --repo app"
+        after_help = "Examples:\n  gr checkout feat/login\n  gr checkout --base\n  gr checkout add sandbox\n  gr checkout add docs-only --group docs\n  gr checkout add app-only --repo app\n  gr checkout list\n  gr checkout remove sandbox"
     )]
-    /// Checkout a branch across repos or create an independent child checkout
+    /// Checkout a branch across repos or manage independent child checkouts
     Checkout {
-        /// Branch name, or `add` to create an independent child checkout
+        /// Branch name, or `add`/`list`/`remove` for child checkout lifecycle
         name: Option<String>,
         /// Additional checkout action args (e.g. `add <name>`)
         #[arg(hide = true)]
diff --git a/src/cli/commands/checkout.rs b/src/cli/commands/checkout.rs
index c44ddd5d..9b5dfd40 100644
--- a/src/cli/commands/checkout.rs
+++ b/src/cli/commands/checkout.rs
@@ -163,3 +163,35 @@ pub fn run_checkout_add(
     Output::info(&format!("Path: {}", info.path.display()));
     Ok(())
 }
+
+/// List cache-backed child checkouts.
+pub fn run_checkout_list(workspace_root: &Path) -> anyhow::Result<()> {
+    Output::header("Checkouts");
+    println!();
+
+    let checkouts = workspace_checkout::list_checkouts(workspace_root)?;
+    if checkouts.is_empty() {
+        println!("No checkouts configured.");
+        return Ok(());
+    }
+
+    for checkout in checkouts {
+        println!("{} -> {}", checkout.name, checkout.path.display());
+    }
+
+    Ok(())
+}
+
+/// Remove a cache-backed child checkout.
+pub fn run_checkout_remove(workspace_root: &Path, checkout_name: &str) -> anyhow::Result<()> {
+    Output::header(&format!("Removing checkout '{}'", checkout_name));
+    println!();
+
+    let removed = workspace_checkout::remove_checkout(workspace_root, checkout_name)?;
+    if removed {
+        Output::success(&format!("Removed checkout '{}'", checkout_name));
+        Ok(())
+    } else {
+        anyhow::bail!("Checkout '{}' not found", checkout_name);
+    }
+}
diff --git a/src/cli/dispatch.rs b/src/cli/dispatch.rs
index 8c430887..97e269c3 100644
--- a/src/cli/dispatch.rs
+++ b/src/cli/dispatch.rs
@@ -120,6 +120,25 @@ pub async fn dispatch_command(
                     repo.as_deref(),
                     group.as_deref(),
                 )?;
+            } else if matches!(name.as_deref(), Some("list")) {
+                if create || base || !extra.is_empty() {
+                    anyhow::bail!("`gr checkout list` does not accept extra arguments");
+                }
+                crate::cli::commands::checkout::run_checkout_list(&ctx.workspace_root)?;
+            } else if matches!(name.as_deref(), Some("remove")) {
+                if create || base {
+                    anyhow::bail!("--create and --base are not valid with 'remove'");
+                }
+                if extra.len() > 1 {
+                    anyhow::bail!("unexpected extra arguments after checkout name");
+                }
+                let checkout_name = extra.first().ok_or_else(|| {
+                    anyhow::anyhow!("Checkout name is required: gr checkout remove <name>")
+                })?;
+                crate::cli::commands::checkout::run_checkout_remove(
+                    &ctx.workspace_root,
+                    checkout_name,
+                )?;
             } else {
                 let branch = if base {
                     let config = crate::core::griptree::GriptreeConfig::load_from_workspace(
diff --git a/tests/cli_tests.rs b/tests/cli_tests.rs
index d915e17f..e58abc81 100644
--- a/tests/cli_tests.rs
+++ b/tests/cli_tests.rs
@@ -553,15 +553,17 @@ fn test_checkout_help_mentions_add_mode() {
         .assert()
         .success()
         .stdout(predicate::str::contains(
-            "Checkout a branch across repos or create an independent child checkout",
+            "Checkout a branch across repos or manage independent child checkouts",
         ))
         .stdout(predicate::str::contains(
-            "Branch name, or `add` to create an independent child checkout",
+            "Branch name, or `add`/`list`/`remove` for child checkout lifecycle",
         ))
         .stdout(predicate::str::contains("gr checkout add sandbox"))
         .stdout(predicate::str::contains(
             "gr checkout add docs-only --group docs",
-        ));
+        ))
+        .stdout(predicate::str::contains("gr checkout list"))
+        .stdout(predicate::str::contains("gr checkout remove sandbox"));
 }
 
 /// Test that `gr status` fails gracefully outside a workspace
@@ -835,3 +837,115 @@ fn test_checkout_add_rejects_duplicate_checkout_name() {
             "checkout 'sandbox' already exists",
         ));
 }
+
+#[test]
+fn test_checkout_list_shows_materialized_checkouts() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut add = Command::cargo_bin("gr").unwrap();
+    add.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("sandbox")
+        .assert()
+        .success();
+
+    let mut list = Command::cargo_bin("gr").unwrap();
+    list.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("list")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Checkouts"))
+        .stdout(predicate::str::contains("sandbox ->"));
+}
+
+#[test]
+fn test_checkout_list_reports_empty_state() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut list = Command::cargo_bin("gr").unwrap();
+    list.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("list")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("No checkouts configured."));
+}
+
+#[test]
+fn test_checkout_list_rejects_extra_positional_args() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut list = Command::cargo_bin("gr").unwrap();
+    list.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("list")
+        .arg("extra")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "`gr checkout list` does not accept extra arguments",
+        ));
+}
+
+#[test]
+fn test_checkout_remove_deletes_materialized_checkout() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+    let checkout_root = ws.workspace_root.join(".grip/checkouts/sandbox");
+
+    let mut add = Command::cargo_bin("gr").unwrap();
+    add.current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("add")
+        .arg("sandbox")
+        .assert()
+        .success();
+
+    assert!(checkout_root.is_dir());
+
+    let mut remove = Command::cargo_bin("gr").unwrap();
+    remove
+        .current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("remove")
+        .arg("sandbox")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Removed checkout 'sandbox'"));
+
+    assert!(!checkout_root.exists());
+}
+
+#[test]
+fn test_checkout_remove_errors_for_missing_checkout() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut remove = Command::cargo_bin("gr").unwrap();
+    remove
+        .current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("remove")
+        .arg("missing")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("Checkout 'missing' not found"));
+}
+
+#[test]
+fn test_checkout_remove_rejects_extra_positional_args() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+
+    let mut remove = Command::cargo_bin("gr").unwrap();
+    remove
+        .current_dir(&ws.workspace_root)
+        .arg("checkout")
+        .arg("remove")
+        .arg("sandbox")
+        .arg("extra")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "unexpected extra arguments after checkout name",
+        ));
+}

From 6f5b10e2b95241cfd6e9ad1102dd22c97cf8620b Mon Sep 17 00:00:00 2001
From: Layne Penney <dev@layne.pro>
Date: Thu, 9 Apr 2026 15:39:36 -0500
Subject: [PATCH 06/15] refactor: strip premium prompts from migrate flow
 (#510)

---
 src/cli/commands/migrate.rs | 30 ++++--------------------------
 1 file changed, 4 insertions(+), 26 deletions(-)

diff --git a/src/cli/commands/migrate.rs b/src/cli/commands/migrate.rs
index bb7dbd9c..6b56e447 100644
--- a/src/cli/commands/migrate.rs
+++ b/src/cli/commands/migrate.rs
@@ -99,19 +99,9 @@ pub async fn run_migrate_from_repos(
         Vec::new()
     };
 
-    let premium = if interactive {
-        let theme = ColorfulTheme::default();
-        Confirm::with_theme(&theme)
-            .with_prompt("Enable premium features (persistent agents, team sharing)?")
-            .default(false)
-            .interact()?
-    } else {
-        false
-    };
-
     // Generate all files
     let manifest_yaml = generate_manifest_yaml(&parsed_repos, org_str, prefix_str);
-    let claude_md = generate_claude_md(&parsed_repos, prefix_str, &agents, premium);
+    let claude_md = generate_claude_md(&parsed_repos, prefix_str, &agents);
     let agents_toml = generate_agents_toml(prefix_str, &agents);
     let prompts: Vec<(String, String)> = agents
         .iter()
@@ -157,7 +147,6 @@ pub async fn run_migrate_from_repos(
             "target_dir": target_dir.display().to_string(),
             "repos": repos,
             "agents": agents.iter().map(|a| &a.name).collect::<Vec<_>>(),
-            "premium": premium,
             "manifest": ".gitgrip/spaces/main/gripspace.yml",
             "config": "config/",
         });
@@ -281,7 +270,6 @@ fn generate_claude_md(
     repos: &[(String, String)],
     prefix: &str,
     agents: &[AgentSpec],
-    premium: bool,
 ) -> String {
     let mut md = String::new();
     md.push_str(&format!("# {}\n\n", prefix));
@@ -317,16 +305,6 @@ fn generate_claude_md(
     md.push_str("gr pr merge              # Merge linked PRs\n");
     md.push_str("```\n");
 
-    if premium {
-        md.push_str("\n## Premium Features\n\n");
-        md.push_str("This workspace has premium features enabled:\n");
-        md.push_str("- `recall_identity` — persistent agent identity\n");
-        md.push_str("- `recall_career` — cross-project career memory\n");
-        md.push_str("- `recall_promote` — share knowledge across team\n");
-        md.push_str("- `recall_approve` — approve promoted knowledge\n\n");
-        md.push_str("Use `recall_promote` after learning something reusable across projects.\n");
-    }
-
     md
 }
 
@@ -1068,12 +1046,12 @@ mod tests {
             model: "claude-opus-4-6".to_string(),
             tool: "claude".to_string(),
         }];
-        let md = generate_claude_md(&repos, "myproject", &agents, true);
+        let md = generate_claude_md(&repos, "myproject", &agents);
         assert!(md.contains("# myproject"));
         assert!(md.contains("| **myrepo**"));
         assert!(md.contains("| **atlas**"));
-        assert!(md.contains("Premium Features"));
-        assert!(md.contains("recall_identity"));
+        assert!(!md.contains("Premium Features"));
+        assert!(!md.contains("recall_identity"));
     }
 
     #[test]

From 8ce00e6ef609b4e90658d949459a0a45001be335 Mon Sep 17 00:00:00 2001
From: Layne Penney <dev@layne.pro>
Date: Fri, 10 Apr 2026 16:21:07 -0500
Subject: [PATCH 07/15] Sprint 16 ceremony: grip

---
 Cargo.lock          |   2 +
 gr2/Cargo.toml      |   2 +
 gr2/src/args.rs     |  53 ++++
 gr2/src/dispatch.rs | 205 +++++++++++-
 gr2/src/lib.rs      |   2 +
 gr2/src/plan.rs     | 236 ++++++++++++++
 gr2/src/spec.rs     | 236 ++++++++++++++
 tests/cli_tests.rs  | 752 ++++++++++++++++++++++++++++++++++++++++++++
 8 files changed, 1487 insertions(+), 1 deletion(-)
 create mode 100644 gr2/src/plan.rs
 create mode 100644 gr2/src/spec.rs

diff --git a/Cargo.lock b/Cargo.lock
index 31da8d59..1d8a78e2 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1593,6 +1593,8 @@ version = "0.1.0"
 dependencies = [
  "anyhow",
  "clap",
+ "serde",
+ "toml",
 ]
 
 [[package]]
diff --git a/gr2/Cargo.toml b/gr2/Cargo.toml
index b8b7067f..0ebfb544 100644
--- a/gr2/Cargo.toml
+++ b/gr2/Cargo.toml
@@ -11,3 +11,5 @@ path = "src/lib.rs"
 [dependencies]
 anyhow = "1"
 clap = { version = "4", features = ["derive"] }
+serde = { version = "1", features = ["derive"] }
+toml = "0.8"
diff --git a/gr2/src/args.rs b/gr2/src/args.rs
index f4f5916d..0945cb17 100644
--- a/gr2/src/args.rs
+++ b/gr2/src/args.rs
@@ -43,6 +43,32 @@ pub enum Commands {
         #[command(subcommand)]
         command: RepoCommands,
     },
+
+    /// Unit registry operations
+    Unit {
+        #[command(subcommand)]
+        command: UnitCommands,
+    },
+
+    /// Declarative workspace spec operations
+    Spec {
+        #[command(subcommand)]
+        command: SpecCommands,
+    },
+
+    /// Diff the workspace spec into an execution plan
+    Plan {
+        /// Pre-approve plans with more than 3 operations
+        #[arg(long)]
+        yes: bool,
+    },
+
+    /// Apply the current execution plan to the workspace
+    Apply {
+        /// Pre-approve plans with more than 3 operations
+        #[arg(long)]
+        yes: bool,
+    },
 }
 
 #[derive(Subcommand, Debug)]
@@ -83,3 +109,30 @@ pub enum RepoCommands {
         name: String,
     },
 }
+
+#[derive(Subcommand, Debug)]
+pub enum UnitCommands {
+    /// Register a local unit in the workspace materialization model
+    Add {
+        /// Unit name
+        name: String,
+    },
+
+    /// List registered units
+    List,
+
+    /// Remove a registered unit
+    Remove {
+        /// Unit name
+        name: String,
+    },
+}
+
+#[derive(Subcommand, Debug)]
+pub enum SpecCommands {
+    /// Print the current workspace spec
+    Show,
+
+    /// Validate the current workspace spec against the filesystem
+    Validate,
+}
diff --git a/gr2/src/dispatch.rs b/gr2/src/dispatch.rs
index 29273f4d..cc0bbbba 100644
--- a/gr2/src/dispatch.rs
+++ b/gr2/src/dispatch.rs
@@ -2,7 +2,9 @@ use anyhow::Result;
 use std::fs;
 use std::path::PathBuf;
 
-use crate::args::{Commands, RepoCommands, TeamCommands};
+use crate::args::{Commands, RepoCommands, SpecCommands, TeamCommands, UnitCommands};
+use crate::plan::ExecutionPlan;
+use crate::spec::{read_workspace_spec, workspace_spec_path, write_workspace_spec, WorkspaceSpec};
 
 pub async fn dispatch_command(command: Commands, verbose: bool) -> Result<()> {
     match command {
@@ -226,6 +228,189 @@ pub async fn dispatch_command(command: Commands, verbose: bool) -> Result<()> {
                 Ok(())
             }
         },
+        Commands::Unit { command } => match command {
+            UnitCommands::Add { name } => {
+                let workspace_root = require_workspace_root()?;
+                validate_unit_name(&name)?;
+                let units_root = workspace_root.join("agents");
+                let registry_path = workspace_root.join(".grip/units.toml");
+                let unit_root = units_root.join(&name);
+
+                if unit_root.exists() {
+                    anyhow::bail!("unit '{}' already exists", name);
+                }
+
+                fs::create_dir_all(&unit_root)?;
+                fs::write(
+                    unit_root.join("unit.toml"),
+                    format!("name = \"{}\"\nkind = \"unit\"\n", name),
+                )?;
+
+                let mut entries = Vec::new();
+                if registry_path.exists() {
+                    entries.push(fs::read_to_string(&registry_path)?);
+                }
+                entries.push(format!("[[unit]]\nname = \"{}\"\nkind = \"unit\"\n", name));
+                fs::write(&registry_path, entries.join("\n"))?;
+
+                println!("Added gr2 unit '{}'", name);
+                Ok(())
+            }
+            UnitCommands::List => {
+                let workspace_root = require_workspace_root()?;
+                let units_root = workspace_root.join("agents");
+
+                let mut names = Vec::new();
+                for entry in fs::read_dir(&units_root)? {
+                    let entry = entry?;
+                    if entry.file_type()?.is_dir() && entry.path().join("unit.toml").exists() {
+                        names.push(entry.file_name().to_string_lossy().into_owned());
+                    }
+                }
+
+                names.sort();
+
+                if names.is_empty() {
+                    println!("No gr2 units registered.");
+                } else {
+                    println!("Units");
+                    for name in names {
+                        println!("- {}", name);
+                    }
+                }
+
+                Ok(())
+            }
+            UnitCommands::Remove { name } => {
+                let workspace_root = require_workspace_root()?;
+                let units_root = workspace_root.join("agents");
+                let unit_root = units_root.join(&name);
+                let unit_toml = unit_root.join("unit.toml");
+
+                if !unit_toml.exists() {
+                    anyhow::bail!("unit '{}' not found", name);
+                }
+
+                fs::remove_dir_all(&unit_root)?;
+
+                let registry_path = workspace_root.join(".grip/units.toml");
+                if registry_path.exists() {
+                    let registry = fs::read_to_string(&registry_path)?;
+                    let kept_entries = registry
+                        .split("\n[[unit]]\n")
+                        .filter_map(|chunk| {
+                            let chunk = chunk.trim();
+                            if chunk.is_empty() {
+                                return None;
+                            }
+                            let normalized = if chunk.starts_with("[[unit]]") {
+                                chunk.to_string()
+                            } else {
+                                format!("[[unit]]\n{}", chunk)
+                            };
+                            let matches_name = normalized
+                                .lines()
+                                .find_map(|line| line.strip_prefix("name = \""))
+                                .and_then(|line| line.strip_suffix('"'))
+                                .map(|entry_name| entry_name == name)
+                                .unwrap_or(false);
+                            if matches_name {
+                                None
+                            } else {
+                                Some(normalized)
+                            }
+                        })
+                        .collect::<Vec<_>>();
+
+                    if kept_entries.is_empty() {
+                        fs::remove_file(&registry_path)?;
+                    } else {
+                        fs::write(&registry_path, kept_entries.join("\n\n"))?;
+                    }
+                }
+
+                println!("Removed gr2 unit '{}'", name);
+                Ok(())
+            }
+        },
+        Commands::Spec { command } => match command {
+            SpecCommands::Show => {
+                let workspace_root = require_workspace_root()?;
+                let spec_path = workspace_spec_path(&workspace_root);
+                let spec = if spec_path.exists() {
+                    read_workspace_spec(&workspace_root)?
+                } else {
+                    let spec = WorkspaceSpec::from_workspace(&workspace_root)?;
+                    write_workspace_spec(&workspace_root, &spec)?;
+                    spec
+                };
+
+                println!("{}", toml::to_string_pretty(&spec)?);
+                Ok(())
+            }
+            SpecCommands::Validate => {
+                let workspace_root = require_workspace_root()?;
+                let spec = read_workspace_spec(&workspace_root)?;
+                spec.validate(&workspace_root)?;
+                println!(
+                    "Workspace spec is valid: {}",
+                    workspace_spec_path(&workspace_root).display()
+                );
+                Ok(())
+            }
+        },
+        Commands::Plan { yes } => {
+            let workspace_root = require_workspace_root()?;
+            let build = ExecutionPlan::from_workspace_spec(&workspace_root)?;
+            let guard_report = build.plan.guard_for_apply(&workspace_root, yes)?;
+
+            if build.generated_spec {
+                println!(
+                    "Generated workspace spec at {} from current workspace state.",
+                    workspace_spec_path(&workspace_root).display()
+                );
+            }
+            println!("{}", build.plan.render_table());
+            for warning in guard_report.warnings {
+                println!("warning: {}", warning);
+            }
+            if guard_report.requires_confirmation {
+                println!("warning: plan contains more than 3 operations; apply will require --yes");
+            }
+            Ok(())
+        }
+        Commands::Apply { yes } => {
+            let workspace_root = require_workspace_root()?;
+            let build = ExecutionPlan::from_workspace_spec(&workspace_root)?;
+            let guard_report = build.plan.guard_for_apply(&workspace_root, yes)?;
+
+            if build.generated_spec {
+                println!(
+                    "Generated workspace spec at {} from current workspace state.",
+                    workspace_spec_path(&workspace_root).display()
+                );
+            }
+
+            if guard_report.requires_confirmation {
+                anyhow::bail!("plan contains more than 3 operations; rerun with --yes to apply it");
+            }
+
+            for warning in &guard_report.warnings {
+                println!("warning: {}", warning);
+            }
+
+            let applied = build.plan.apply(&workspace_root, &build.spec)?;
+            if applied.is_empty() {
+                println!("ExecutionPlan");
+                println!("- no changes required");
+            } else {
+                println!("Applied execution plan");
+                for line in applied {
+                    println!("- {}", line);
+                }
+            }
+            Ok(())
+        }
     }
 }
 
@@ -237,3 +422,21 @@ fn require_workspace_root() -> Result<PathBuf> {
     }
     Ok(workspace_root)
 }
+
+fn validate_unit_name(name: &str) -> Result<()> {
+    if name.is_empty() {
+        anyhow::bail!("unit name must not be empty");
+    }
+
+    if !name
+        .chars()
+        .all(|ch| ch.is_ascii_alphanumeric() || ch == '_' || ch == '-')
+    {
+        anyhow::bail!(
+            "invalid unit name '{}': use only ASCII letters, numbers, '_' or '-'",
+            name
+        );
+    }
+
+    Ok(())
+}
diff --git a/gr2/src/lib.rs b/gr2/src/lib.rs
index 7a8cd2b8..ba904930 100644
--- a/gr2/src/lib.rs
+++ b/gr2/src/lib.rs
@@ -4,3 +4,5 @@
 
 pub mod args;
 pub mod dispatch;
+pub mod plan;
+pub mod spec;
diff --git a/gr2/src/plan.rs b/gr2/src/plan.rs
new file mode 100644
index 00000000..64f19b55
--- /dev/null
+++ b/gr2/src/plan.rs
@@ -0,0 +1,236 @@
+use anyhow::{Context, Result};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+use std::fs;
+use std::path::Path;
+
+use crate::spec::{
+    read_workspace_spec, workspace_spec_path, write_workspace_spec, UnitSpec, WorkspaceSpec,
+};
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct ExecutionPlan {
+    pub operations: Vec<PlanOperation>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PlanBuild {
+    pub spec: WorkspaceSpec,
+    pub plan: ExecutionPlan,
+    pub generated_spec: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct PlanOperation {
+    pub unit_name: String,
+    pub operation: OperationType,
+    #[serde(default)]
+    pub parameters: BTreeMap<String, String>,
+    pub preview: String,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum OperationType {
+    Clone,
+    Configure,
+    Link,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PlanGuardReport {
+    pub warnings: Vec<String>,
+    pub requires_confirmation: bool,
+}
+
+impl ExecutionPlan {
+    pub fn from_workspace_spec(workspace_root: &Path) -> Result<PlanBuild> {
+        let spec_path = workspace_spec_path(workspace_root);
+        let (spec, generated_spec) = if spec_path.exists() {
+            (read_workspace_spec(workspace_root)?, false)
+        } else {
+            let generated = WorkspaceSpec::from_workspace(workspace_root)?;
+            write_workspace_spec(workspace_root, &generated)?;
+            (generated, true)
+        };
+
+        spec.validate_for_plan()?;
+
+        let mut operations = Vec::new();
+
+        for unit in &spec.units {
+            let unit_root = workspace_root.join(&unit.path);
+            let unit_toml = unit_root.join("unit.toml");
+
+            if !unit_toml.exists() {
+                let mut parameters = BTreeMap::new();
+                parameters.insert("path".to_string(), unit.path.clone());
+                parameters.insert("repos".to_string(), unit.repos.join(","));
+                operations.push(PlanOperation {
+                    unit_name: unit.name.clone(),
+                    operation: OperationType::Clone,
+                    parameters,
+                    preview: format!("clone unit '{}' into {}", unit.name, unit.path),
+                });
+                continue;
+            }
+
+            let expected_path = format!("agents/{}", unit.name);
+            if unit.path != expected_path {
+                let mut parameters = BTreeMap::new();
+                parameters.insert("path".to_string(), unit.path.clone());
+                parameters.insert("repos".to_string(), unit.repos.join(","));
+                operations.push(PlanOperation {
+                    unit_name: unit.name.clone(),
+                    operation: OperationType::Configure,
+                    parameters,
+                    preview: format!("reconfigure unit '{}' to match {}", unit.name, unit.path),
+                });
+            }
+        }
+
+        Ok(PlanBuild {
+            spec,
+            plan: Self { operations },
+            generated_spec,
+        })
+    }
+
+    pub fn apply(&self, workspace_root: &Path, spec: &WorkspaceSpec) -> Result<Vec<String>> {
+        let mut applied = Vec::new();
+
+        for operation in &self.operations {
+            let unit_spec = spec
+                .units
+                .iter()
+                .find(|unit| unit.name == operation.unit_name)
+                .with_context(|| {
+                    format!(
+                        "execution plan references unknown unit '{}'",
+                        operation.unit_name
+                    )
+                })?;
+
+            match operation.operation {
+                OperationType::Clone => {
+                    materialize_unit(workspace_root, unit_spec)?;
+                    applied.push(format!(
+                        "cloned unit '{}' into {}",
+                        unit_spec.name, unit_spec.path
+                    ));
+                }
+                OperationType::Configure => {
+                    materialize_unit(workspace_root, unit_spec)?;
+                    applied.push(format!(
+                        "configured unit '{}' at {}",
+                        unit_spec.name, unit_spec.path
+                    ));
+                }
+                OperationType::Link => {
+                    anyhow::bail!(
+                        "link operations are not implemented yet for unit '{}'",
+                        unit_spec.name
+                    );
+                }
+            }
+        }
+
+        Ok(applied)
+    }
+
+    pub fn guard_for_apply(
+        &self,
+        workspace_root: &Path,
+        assume_yes: bool,
+    ) -> Result<PlanGuardReport> {
+        let mut warnings = Vec::new();
+
+        for operation in &self.operations {
+            let path = operation
+                .parameters
+                .get("path")
+                .map(|value| workspace_root.join(value))
+                .unwrap_or_else(|| workspace_root.join(format!("agents/{}", operation.unit_name)));
+
+            if matches!(operation.operation, OperationType::Link) && path.exists() {
+                anyhow::bail!(
+                    "refusing to apply plan: link operation for '{}' would overwrite existing directory {}",
+                    operation.unit_name,
+                    path.display()
+                );
+            }
+
+            if path.join(".git").exists() {
+                warnings.push(format!(
+                    "unit '{}' has a git checkout at {} with possible uncommitted changes; inspect before apply",
+                    operation.unit_name,
+                    path.display()
+                ));
+            }
+        }
+
+        Ok(PlanGuardReport {
+            warnings,
+            requires_confirmation: self.operations.len() > 3 && !assume_yes,
+        })
+    }
+
+    pub fn render_table(&self) -> String {
+        if self.operations.is_empty() {
+            return "ExecutionPlan\n- no changes required\n".to_string();
+        }
+
+        let mut lines = vec![
+            "ExecutionPlan".to_string(),
+            "UNIT\tOPERATION\tPREVIEW".to_string(),
+        ];
+        for operation in &self.operations {
+            lines.push(format!(
+                "{}\t{}\t{}",
+                operation.unit_name,
+                operation.operation.as_str(),
+                operation.preview
+            ));
+        }
+        lines.join("\n")
+    }
+}
+
+impl OperationType {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Clone => "clone",
+            Self::Configure => "configure",
+            Self::Link => "link",
+        }
+    }
+}
+
+fn materialize_unit(workspace_root: &Path, unit: &UnitSpec) -> Result<()> {
+    let unit_root = workspace_root.join(&unit.path);
+    fs::create_dir_all(&unit_root)
+        .with_context(|| format!("create unit directory {}", unit_root.display()))?;
+    fs::write(unit_root.join("unit.toml"), render_unit_toml(unit))
+        .with_context(|| format!("write unit metadata for '{}'", unit.name))?;
+    Ok(())
+}
+
+fn render_unit_toml(unit: &UnitSpec) -> String {
+    let repos = if unit.repos.is_empty() {
+        "[]".to_string()
+    } else {
+        format!(
+            "[{}]",
+            unit.repos
+                .iter()
+                .map(|repo| format!("\"{}\"", repo))
+                .collect::<Vec<_>>()
+                .join(", ")
+        )
+    };
+
+    format!(
+        "name = \"{}\"\nkind = \"unit\"\nrepos = {}\n",
+        unit.name, repos
+    )
+}
diff --git a/gr2/src/spec.rs b/gr2/src/spec.rs
new file mode 100644
index 00000000..a1c6c2b4
--- /dev/null
+++ b/gr2/src/spec.rs
@@ -0,0 +1,236 @@
+use anyhow::{Context, Result};
+use serde::{Deserialize, Serialize};
+use std::collections::HashSet;
+use std::fs;
+use std::path::{Path, PathBuf};
+
+pub const WORKSPACE_SPEC_VERSION: u32 = 1;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct WorkspaceSpec {
+    pub schema_version: u32,
+    pub workspace_name: String,
+    pub cache: CacheSpec,
+    #[serde(default)]
+    pub repos: Vec<RepoSpec>,
+    #[serde(default)]
+    pub units: Vec<UnitSpec>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct CacheSpec {
+    pub root: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct RepoSpec {
+    pub name: String,
+    pub path: String,
+    pub url: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct UnitSpec {
+    pub name: String,
+    pub path: String,
+    #[serde(default)]
+    pub repos: Vec<String>,
+}
+
+impl WorkspaceSpec {
+    pub fn from_workspace(workspace_root: &Path) -> Result<Self> {
+        let workspace_name = read_workspace_name(workspace_root)?;
+        let repos = read_registered_repos(workspace_root)?;
+        let units = read_registered_units(workspace_root)?;
+
+        Ok(Self {
+            schema_version: WORKSPACE_SPEC_VERSION,
+            workspace_name,
+            cache: CacheSpec {
+                root: ".grip/cache".to_string(),
+            },
+            repos,
+            units,
+        })
+    }
+
+    pub fn validate_for_plan(&self) -> Result<()> {
+        if self.schema_version != WORKSPACE_SPEC_VERSION {
+            anyhow::bail!(
+                "unsupported workspace spec schema_version {}: expected {}",
+                self.schema_version,
+                WORKSPACE_SPEC_VERSION
+            );
+        }
+
+        if self.workspace_name.trim().is_empty() {
+            anyhow::bail!("workspace spec workspace_name must not be empty");
+        }
+
+        let mut repo_names = HashSet::new();
+        for repo in &self.repos {
+            if !repo_names.insert(repo.name.clone()) {
+                anyhow::bail!("workspace spec contains duplicate repo '{}'", repo.name);
+            }
+
+            if repo.path.trim().is_empty() || repo.url.trim().is_empty() {
+                anyhow::bail!("repo '{}' must include non-empty path and url", repo.name);
+            }
+        }
+
+        let mut unit_names = HashSet::new();
+        for unit in &self.units {
+            if !unit_names.insert(unit.name.clone()) {
+                anyhow::bail!("workspace spec contains duplicate unit '{}'", unit.name);
+            }
+
+            if unit.path.trim().is_empty() {
+                anyhow::bail!("unit '{}' must include a non-empty path", unit.name);
+            }
+
+            for repo_name in &unit.repos {
+                if !repo_names.contains(repo_name) {
+                    anyhow::bail!(
+                        "unit '{}' references missing repo '{}'",
+                        unit.name,
+                        repo_name
+                    );
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    pub fn validate(&self, workspace_root: &Path) -> Result<()> {
+        self.validate_for_plan()?;
+
+        for repo in &self.repos {
+            let repo_root = workspace_root.join(&repo.path);
+            if !repo_root.join("repo.toml").exists() {
+                anyhow::bail!(
+                    "workspace spec repo '{}' is missing repo metadata at {}",
+                    repo.name,
+                    repo_root.join("repo.toml").display()
+                );
+            }
+        }
+
+        for unit in &self.units {
+            let unit_root = workspace_root.join(&unit.path);
+            if !unit_root.join("unit.toml").exists() {
+                anyhow::bail!(
+                    "workspace spec unit '{}' is missing unit metadata at {}",
+                    unit.name,
+                    unit_root.join("unit.toml").display()
+                );
+            }
+        }
+
+        Ok(())
+    }
+}
+
+pub fn write_workspace_spec(workspace_root: &Path, spec: &WorkspaceSpec) -> Result<PathBuf> {
+    let spec_path = workspace_spec_path(workspace_root);
+    let content = toml::to_string_pretty(spec).context("serialize workspace spec")?;
+    fs::write(&spec_path, content)
+        .with_context(|| format!("write workspace spec to {}", spec_path.display()))?;
+    Ok(spec_path)
+}
+
+pub fn read_workspace_spec(workspace_root: &Path) -> Result<WorkspaceSpec> {
+    let spec_path = workspace_spec_path(workspace_root);
+    let content = fs::read_to_string(&spec_path)
+        .with_context(|| format!("read workspace spec from {}", spec_path.display()))?;
+    toml::from_str(&content).context("parse workspace spec")
+}
+
+pub fn workspace_spec_path(workspace_root: &Path) -> PathBuf {
+    workspace_root.join(".grip/workspace_spec.toml")
+}
+
+fn read_workspace_name(workspace_root: &Path) -> Result<String> {
+    let workspace_toml = fs::read_to_string(workspace_root.join(".grip/workspace.toml"))
+        .context("read .grip/workspace.toml")?;
+    workspace_toml
+        .lines()
+        .find_map(|line| line.strip_prefix("name = \""))
+        .and_then(|line| line.strip_suffix('"'))
+        .map(str::to_owned)
+        .context("workspace name missing from .grip/workspace.toml")
+}
+
+fn read_registered_repos(workspace_root: &Path) -> Result<Vec<RepoSpec>> {
+    let repos_root = workspace_root.join("repos");
+    let mut repos = Vec::new();
+
+    for entry in fs::read_dir(&repos_root)? {
+        let entry = entry?;
+        if !entry.file_type()?.is_dir() {
+            continue;
+        }
+
+        let repo_root = entry.path();
+        let repo_toml = repo_root.join("repo.toml");
+        if !repo_toml.exists() {
+            continue;
+        }
+
+        let content = fs::read_to_string(&repo_toml)?;
+        let fallback_name = entry.file_name().to_string_lossy().into_owned();
+        let name = content
+            .lines()
+            .find_map(|line| line.strip_prefix("name = \""))
+            .and_then(|line| line.strip_suffix('"'))
+            .map(str::to_owned)
+            .unwrap_or(fallback_name.clone());
+        let url = content
+            .lines()
+            .find_map(|line| line.strip_prefix("url = \""))
+            .and_then(|line| line.strip_suffix('"'))
+            .unwrap_or("")
+            .to_string();
+
+        repos.push(RepoSpec {
+            name,
+            path: format!("repos/{}", fallback_name),
+            url,
+        });
+    }
+
+    repos.sort_by(|a, b| a.name.cmp(&b.name));
+    Ok(repos)
+}
+
+fn read_registered_units(workspace_root: &Path) -> Result<Vec<UnitSpec>> {
+    let units_root = workspace_root.join("agents");
+    let mut units = Vec::new();
+
+    if !units_root.exists() {
+        return Ok(units);
+    }
+
+    for entry in fs::read_dir(&units_root)? {
+        let entry = entry?;
+        if !entry.file_type()?.is_dir() {
+            continue;
+        }
+
+        let unit_root = entry.path();
+        let unit_toml = unit_root.join("unit.toml");
+        if !unit_toml.exists() {
+            continue;
+        }
+
+        let fallback_name = entry.file_name().to_string_lossy().into_owned();
+        units.push(UnitSpec {
+            name: fallback_name.clone(),
+            path: format!("agents/{}", fallback_name),
+            repos: Vec::new(),
+        });
+    }
+
+    units.sort_by(|a, b| a.name.cmp(&b.name));
+    Ok(units)
+}
diff --git a/tests/cli_tests.rs b/tests/cli_tests.rs
index e58abc81..ca1b04c5 100644
--- a/tests/cli_tests.rs
+++ b/tests/cli_tests.rs
@@ -545,6 +545,758 @@ fn test_gr2_repo_remove_requires_gr2_workspace() {
         ));
 }
 
+#[test]
+fn test_gr2_unit_add_registers_unit() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Added gr2 unit 'atlas'"));
+
+    let unit_toml = std::fs::read_to_string(workspace_root.join("agents/atlas/unit.toml")).unwrap();
+    assert!(unit_toml.contains("name = \"atlas\""));
+    assert!(unit_toml.contains("kind = \"unit\""));
+
+    let registry = std::fs::read_to_string(workspace_root.join(".grip/units.toml")).unwrap();
+    assert!(registry.contains("[[unit]]"));
+    assert!(registry.contains("name = \"atlas\""));
+}
+
+#[test]
+fn test_gr2_unit_add_rejects_duplicate_unit() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut first = Command::cargo_bin("gr2").unwrap();
+    first
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let mut duplicate = Command::cargo_bin("gr2").unwrap();
+    duplicate
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("unit 'atlas' already exists"));
+}
+
+#[test]
+fn test_gr2_unit_add_rejects_invalid_name() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut invalid = Command::cargo_bin("gr2").unwrap();
+    invalid
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas/dev")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "invalid unit name 'atlas/dev': use only ASCII letters, numbers, '_' or '-'",
+        ));
+}
+
+#[test]
+fn test_gr2_unit_list_shows_registered_units() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut add_atlas = Command::cargo_bin("gr2").unwrap();
+    add_atlas
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let mut add_opus = Command::cargo_bin("gr2").unwrap();
+    add_opus
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("opus")
+        .assert()
+        .success();
+
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(&workspace_root)
+        .arg("unit")
+        .arg("list")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Units"))
+        .stdout(predicate::str::contains("- atlas"))
+        .stdout(predicate::str::contains("- opus"));
+}
+
+#[test]
+fn test_gr2_unit_list_reports_empty_state() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(&workspace_root)
+        .arg("unit")
+        .arg("list")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("No gr2 units registered."));
+}
+
+#[test]
+fn test_gr2_unit_remove_deletes_registered_unit() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut add = Command::cargo_bin("gr2").unwrap();
+    add.current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let unit_root = workspace_root.join("agents/atlas");
+    assert!(unit_root.join("unit.toml").exists());
+
+    let mut remove = Command::cargo_bin("gr2").unwrap();
+    remove
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("remove")
+        .arg("atlas")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Removed gr2 unit 'atlas'"));
+
+    assert!(!unit_root.exists());
+    assert!(!workspace_root.join(".grip/units.toml").exists());
+}
+
+#[test]
+fn test_gr2_unit_requires_gr2_workspace() {
+    let temp = TempDir::new().unwrap();
+
+    let mut add = Command::cargo_bin("gr2").unwrap();
+    add.current_dir(temp.path())
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "not in a gr2 workspace: missing .grip/workspace.toml",
+        ));
+}
+
+#[test]
+fn test_gr2_spec_show_round_trips_workspace_spec() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let mut show = Command::cargo_bin("gr2").unwrap();
+    show.current_dir(&workspace_root)
+        .arg("spec")
+        .arg("show")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("schema_version = 1"))
+        .stdout(predicate::str::contains("workspace_name = \"demo\""))
+        .stdout(predicate::str::contains("name = \"app\""))
+        .stdout(predicate::str::contains("name = \"atlas\""));
+
+    let spec = std::fs::read_to_string(workspace_root.join(".grip/workspace_spec.toml")).unwrap();
+    assert!(spec.contains("schema_version = 1"));
+    assert!(spec.contains("workspace_name = \"demo\""));
+    assert!(spec.contains("path = \"repos/app\""));
+    assert!(spec.contains("path = \"agents/atlas\""));
+
+    let mut validate = Command::cargo_bin("gr2").unwrap();
+    validate
+        .current_dir(&workspace_root)
+        .arg("spec")
+        .arg("validate")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Workspace spec is valid"));
+}
+
+#[test]
+fn test_gr2_spec_validate_detects_missing_repo_metadata() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .success();
+
+    let mut show = Command::cargo_bin("gr2").unwrap();
+    show.current_dir(&workspace_root)
+        .arg("spec")
+        .arg("show")
+        .assert()
+        .success();
+
+    std::fs::remove_file(workspace_root.join("repos/app/repo.toml")).unwrap();
+
+    let mut validate = Command::cargo_bin("gr2").unwrap();
+    validate
+        .current_dir(&workspace_root)
+        .arg("spec")
+        .arg("validate")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "workspace spec repo 'app' is missing repo metadata",
+        ));
+}
+
+#[test]
+fn test_gr2_spec_validate_detects_conflicting_unit_names() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let mut show = Command::cargo_bin("gr2").unwrap();
+    show.current_dir(&workspace_root)
+        .arg("spec")
+        .arg("show")
+        .assert()
+        .success();
+
+    let spec_path = workspace_root.join(".grip/workspace_spec.toml");
+    let spec = std::fs::read_to_string(&spec_path).unwrap();
+    let conflicting = format!(
+        "{}\n[[units]]\nname = \"atlas\"\npath = \"agents/atlas-copy\"\nrepos = []\n",
+        spec.trim_end()
+    );
+    std::fs::write(&spec_path, conflicting).unwrap();
+
+    let mut validate = Command::cargo_bin("gr2").unwrap();
+    validate
+        .current_dir(&workspace_root)
+        .arg("spec")
+        .arg("validate")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "workspace spec contains duplicate unit 'atlas'",
+        ));
+}
+
+#[test]
+fn test_gr2_plan_empty_workspace_produces_clone_all_plan() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://github.com/synapt-dev/app.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app"]
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = []
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+    std::fs::create_dir_all(workspace_root.join("repos/app")).unwrap();
+    std::fs::write(
+        workspace_root.join("repos/app/repo.toml"),
+        "name = \"app\"\nurl = \"https://github.com/synapt-dev/app.git\"\n",
+    )
+    .unwrap();
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("ExecutionPlan"))
+        .stdout(predicate::str::contains("atlas\tclone"))
+        .stdout(predicate::str::contains("apollo\tclone"));
+}
+
+#[test]
+fn test_gr2_plan_fully_materialized_workspace_produces_noop_plan() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let mut show = Command::cargo_bin("gr2").unwrap();
+    show.current_dir(&workspace_root)
+        .arg("spec")
+        .arg("show")
+        .assert()
+        .success();
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("no changes required"));
+}
+
+#[test]
+fn test_gr2_plan_does_not_flag_repo_attachment_presence_as_drift() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://github.com/synapt-dev/app.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app"]
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("no changes required"))
+        .stdout(predicate::str::contains("configure").not());
+}
+
+#[test]
+fn test_gr2_plan_missing_unit_produces_single_clone_plan() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .arg("repo")
+        .arg("add")
+        .arg("app")
+        .arg("https://github.com/synapt-dev/app.git")
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let mut show = Command::cargo_bin("gr2").unwrap();
+    show.current_dir(&workspace_root)
+        .arg("spec")
+        .arg("show")
+        .assert()
+        .success();
+
+    std::fs::create_dir_all(workspace_root.join("agents/apollo")).unwrap();
+    std::fs::write(
+        workspace_root.join("agents/apollo/unit.toml"),
+        "name = \"apollo\"\nkind = \"unit\"\n",
+    )
+    .unwrap();
+
+    let spec_path = workspace_root.join(".grip/workspace_spec.toml");
+    let spec = std::fs::read_to_string(&spec_path).unwrap();
+    let with_apollo = format!(
+        "{}\n[[units]]\nname = \"apollo\"\npath = \"agents/apollo\"\nrepos = []\n",
+        spec.trim_end()
+    );
+    std::fs::write(&spec_path, with_apollo).unwrap();
+    std::fs::remove_file(workspace_root.join("agents/apollo/unit.toml")).unwrap();
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("apollo\tclone"))
+        .stdout(predicate::str::contains("clone unit 'apollo'"));
+}
+
+#[test]
+fn test_gr2_plan_rejects_invalid_unit_repo_reference() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://github.com/synapt-dev/app.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["missing"]
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "unit 'atlas' references missing repo 'missing'",
+        ));
+}
+
+#[test]
+fn test_gr2_plan_reports_when_it_generates_a_missing_workspace_spec() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .arg("unit")
+        .arg("add")
+        .arg("atlas")
+        .assert()
+        .success();
+
+    let spec_path = workspace_root.join(".grip/workspace_spec.toml");
+    assert!(!spec_path.exists());
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Generated workspace spec at"))
+        .stdout(predicate::str::contains("no changes required"));
+
+    assert!(spec_path.exists());
+}
+
+#[test]
+fn test_gr2_apply_materializes_missing_units_from_plan() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://github.com/synapt-dev/app.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app"]
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+    std::fs::create_dir_all(workspace_root.join("repos/app")).unwrap();
+    std::fs::write(
+        workspace_root.join("repos/app/repo.toml"),
+        "name = \"app\"\nurl = \"https://github.com/synapt-dev/app.git\"\n",
+    )
+    .unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Applied execution plan"))
+        .stdout(predicate::str::contains("cloned unit 'atlas'"));
+
+    let unit_toml = std::fs::read_to_string(workspace_root.join("agents/atlas/unit.toml")).unwrap();
+    assert!(unit_toml.contains("name = \"atlas\""));
+    assert!(unit_toml.contains("kind = \"unit\""));
+    assert!(unit_toml.contains("repos = [\"app\"]"));
+}
+
+#[test]
+fn test_gr2_apply_requires_yes_for_large_plans() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = []
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = []
+
+[[units]]
+name = "sentinel"
+path = "agents/sentinel"
+repos = []
+
+[[units]]
+name = "opus"
+path = "agents/opus"
+repos = []
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains(
+            "plan contains more than 3 operations; rerun with --yes to apply it",
+        ));
+
+    assert!(!workspace_root.join("agents/atlas/unit.toml").exists());
+    assert!(!workspace_root.join("agents/apollo/unit.toml").exists());
+}
+
 #[test]
 fn test_checkout_help_mentions_add_mode() {
     let mut cmd = Command::cargo_bin("gr").unwrap();

From 8e5e4b64d3334fa3817cc0a37f51a8ac5f661bc5 Mon Sep 17 00:00:00 2001
From: Layne Penney <dev@layne.pro>
Date: Sat, 11 Apr 2026 07:54:33 -0500
Subject: [PATCH 08/15] Sprint 17 ceremony: grip (#531)

---
 Cargo.lock                    |   8 +
 Cargo.toml                    |   3 +
 gr2/Cargo.toml                |   1 +
 gr2/src/plan.rs               | 262 ++++++++++++++---
 gr2/src/spec.rs               |  42 +++
 src/cli/commands/branch.rs    |  50 +++-
 src/cli/commands/link.rs      | 516 ++++++++++++++++++++++-----------
 src/cli/commands/migrate.rs   |   6 +-
 src/cli/commands/release.rs   |   4 +-
 src/cli/commands/repo.rs      |   1 -
 src/cli/commands/tree.rs      |   2 +-
 src/core/griptree.rs          |   4 +-
 src/core/repo.rs              | 108 +++----
 src/git/branch.rs             |   8 +-
 src/git/remote.rs             |   2 +-
 src/platform/rate_limit.rs    |   2 +-
 src/telemetry/metrics.rs      |   2 +-
 tests/cli_tests.rs            | 518 +++++++++++++++++++++++++++++++++-
 tests/common/mock_platform.rs |   2 +-
 tests/griptree_tests.rs       |   4 +-
 tests/integration_agent_id.rs |   1 -
 tests/multi_provider_e2e.rs   |  10 +-
 tests/test_add.rs             |   1 -
 tests/test_branch.rs          |  52 +++-
 tests/test_commit.rs          |   1 -
 tests/test_status.rs          |   2 -
 26 files changed, 1297 insertions(+), 315 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 1d8a78e2..7bba51b8 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -826,6 +826,7 @@ dependencies = [
  "futures",
  "git2",
  "gix",
+ "glob",
  "gr2-cli",
  "indicatif",
  "octocrab",
@@ -1587,11 +1588,18 @@ dependencies = [
  "gix-validate 0.9.4",
 ]
 
+[[package]]
+name = "glob"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
+
 [[package]]
 name = "gr2-cli"
 version = "0.1.0"
 dependencies = [
  "anyhow",
+ "chrono",
  "clap",
  "serde",
  "toml",
diff --git a/Cargo.toml b/Cargo.toml
index aaa078cf..09ec58f6 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -93,6 +93,9 @@ quick-xml = { version = "0.37", features = ["serialize"] }
 # TOML parsing
 toml = "0.8"
 
+# Glob patterns (for linkfile/copyfile glob expansion)
+glob = "0.3"
+
 # Misc
 once_cell = "1"
 regex = "1"
diff --git a/gr2/Cargo.toml b/gr2/Cargo.toml
index 0ebfb544..6ed9e813 100644
--- a/gr2/Cargo.toml
+++ b/gr2/Cargo.toml
@@ -10,6 +10,7 @@ path = "src/lib.rs"
 
 [dependencies]
 anyhow = "1"
+chrono = { version = "0.4", features = ["serde"] }
 clap = { version = "4", features = ["derive"] }
 serde = { version = "1", features = ["derive"] }
 toml = "0.8"
diff --git a/gr2/src/plan.rs b/gr2/src/plan.rs
index 64f19b55..1e12dab8 100644
--- a/gr2/src/plan.rs
+++ b/gr2/src/plan.rs
@@ -5,7 +5,8 @@ use std::fs;
 use std::path::Path;
 
 use crate::spec::{
-    read_workspace_spec, workspace_spec_path, write_workspace_spec, UnitSpec, WorkspaceSpec,
+    read_workspace_spec, workspace_spec_path, write_workspace_spec, LinkKind, LinkSpec, UnitSpec,
+    WorkspaceSpec,
 };
 
 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
@@ -72,20 +73,44 @@ impl ExecutionPlan {
                     parameters,
                     preview: format!("clone unit '{}' into {}", unit.name, unit.path),
                 });
-                continue;
+                // Fall through to check links (they'll all be missing since the unit
+                // doesn't exist yet, but they should be planned alongside the Clone)
+            } else {
+                let expected_path = format!("agents/{}", unit.name);
+                if unit.path != expected_path {
+                    let mut parameters = BTreeMap::new();
+                    parameters.insert("path".to_string(), unit.path.clone());
+                    parameters.insert("repos".to_string(), unit.repos.join(","));
+                    operations.push(PlanOperation {
+                        unit_name: unit.name.clone(),
+                        operation: OperationType::Configure,
+                        parameters,
+                        preview: format!("reconfigure unit '{}' to match {}", unit.name, unit.path),
+                    });
+                }
             }
 
-            let expected_path = format!("agents/{}", unit.name);
-            if unit.path != expected_path {
-                let mut parameters = BTreeMap::new();
-                parameters.insert("path".to_string(), unit.path.clone());
-                parameters.insert("repos".to_string(), unit.repos.join(","));
-                operations.push(PlanOperation {
-                    unit_name: unit.name.clone(),
-                    operation: OperationType::Configure,
-                    parameters,
-                    preview: format!("reconfigure unit '{}' to match {}", unit.name, unit.path),
-                });
+            // Check declared links against filesystem
+            for link in &unit.links {
+                let dest_path = unit_root.join(&link.dest);
+                if !dest_path.exists() {
+                    let mut parameters = BTreeMap::new();
+                    parameters.insert("src".to_string(), link.src.clone());
+                    parameters.insert("dest".to_string(), link.dest.clone());
+                    parameters.insert("kind".to_string(), link.kind.as_str().to_string());
+                    operations.push(PlanOperation {
+                        unit_name: unit.name.clone(),
+                        operation: OperationType::Link,
+                        parameters,
+                        preview: format!(
+                            "{} {} -> {}/{}",
+                            link.kind.as_str(),
+                            link.src,
+                            unit.path,
+                            link.dest
+                        ),
+                    });
+                }
             }
         }
 
@@ -127,14 +152,39 @@ impl ExecutionPlan {
                     ));
                 }
                 OperationType::Link => {
-                    anyhow::bail!(
-                        "link operations are not implemented yet for unit '{}'",
-                        unit_spec.name
-                    );
+                    let src = operation
+                        .parameters
+                        .get("src")
+                        .context("link operation missing 'src' parameter")?;
+                    let dest = operation
+                        .parameters
+                        .get("dest")
+                        .context("link operation missing 'dest' parameter")?;
+                    let kind_str = operation
+                        .parameters
+                        .get("kind")
+                        .map(|s| s.as_str())
+                        .unwrap_or("symlink");
+                    let kind = kind_str.parse::<LinkKind>()?;
+
+                    let link_spec = LinkSpec {
+                        src: src.clone(),
+                        dest: dest.clone(),
+                        kind,
+                    };
+                    apply_link(workspace_root, unit_spec, &link_spec)?;
+                    applied.push(format!(
+                        "{} {} -> {}/{}",
+                        kind_str, src, unit_spec.path, dest
+                    ));
                 }
             }
         }
 
+        if !applied.is_empty() {
+            record_apply_state(workspace_root, &applied)?;
+        }
+
         Ok(applied)
     }
 
@@ -146,26 +196,42 @@ impl ExecutionPlan {
         let mut warnings = Vec::new();
 
         for operation in &self.operations {
-            let path = operation
-                .parameters
-                .get("path")
-                .map(|value| workspace_root.join(value))
-                .unwrap_or_else(|| workspace_root.join(format!("agents/{}", operation.unit_name)));
-
-            if matches!(operation.operation, OperationType::Link) && path.exists() {
-                anyhow::bail!(
-                    "refusing to apply plan: link operation for '{}' would overwrite existing directory {}",
-                    operation.unit_name,
-                    path.display()
-                );
-            }
+            match operation.operation {
+                OperationType::Link => {
+                    // For link operations, check the destination path inside the unit
+                    let unit_path = operation
+                        .parameters
+                        .get("path")
+                        .cloned()
+                        .unwrap_or_else(|| format!("agents/{}", operation.unit_name));
+                    if let Some(dest) = operation.parameters.get("dest") {
+                        let dest_path = workspace_root.join(&unit_path).join(dest);
+                        if dest_path.exists() {
+                            anyhow::bail!(
+                                "refusing to apply plan: link destination already exists for unit '{}': {}",
+                                operation.unit_name,
+                                dest_path.display()
+                            );
+                        }
+                    }
+                }
+                _ => {
+                    let path = operation
+                        .parameters
+                        .get("path")
+                        .map(|value| workspace_root.join(value))
+                        .unwrap_or_else(|| {
+                            workspace_root.join(format!("agents/{}", operation.unit_name))
+                        });
 
-            if path.join(".git").exists() {
-                warnings.push(format!(
-                    "unit '{}' has a git checkout at {} with possible uncommitted changes; inspect before apply",
-                    operation.unit_name,
-                    path.display()
-                ));
+                    if path.join(".git").exists() {
+                        warnings.push(format!(
+                            "unit '{}' has a git checkout at {} with possible uncommitted changes; inspect before apply",
+                            operation.unit_name,
+                            path.display()
+                        ));
+                    }
+                }
             }
         }
 
@@ -206,6 +272,98 @@ impl OperationType {
     }
 }
 
+fn apply_link(workspace_root: &Path, unit: &UnitSpec, link: &LinkSpec) -> Result<()> {
+    let src_path = workspace_root.join(&link.src);
+    let unit_root = workspace_root.join(&unit.path);
+    let dest_path = unit_root.join(&link.dest);
+
+    if !src_path.exists() {
+        anyhow::bail!(
+            "link source does not exist: {} (for unit '{}')",
+            src_path.display(),
+            unit.name
+        );
+    }
+
+    if let Some(parent) = dest_path.parent() {
+        fs::create_dir_all(parent).with_context(|| {
+            format!(
+                "create parent directory for link destination {}",
+                dest_path.display()
+            )
+        })?;
+    }
+
+    match link.kind {
+        LinkKind::Symlink => {
+            let abs_src = fs::canonicalize(&src_path).with_context(|| {
+                format!(
+                    "resolve absolute path for link source {}",
+                    src_path.display()
+                )
+            })?;
+            #[cfg(unix)]
+            std::os::unix::fs::symlink(&abs_src, &dest_path).with_context(|| {
+                format!(
+                    "create symlink {} -> {}",
+                    dest_path.display(),
+                    abs_src.display()
+                )
+            })?;
+            #[cfg(windows)]
+            {
+                if abs_src.is_dir() {
+                    std::os::windows::fs::symlink_dir(&abs_src, &dest_path)
+                } else {
+                    std::os::windows::fs::symlink_file(&abs_src, &dest_path)
+                }
+                .with_context(|| {
+                    format!(
+                        "create symlink {} -> {}",
+                        dest_path.display(),
+                        abs_src.display()
+                    )
+                })?;
+            }
+        }
+        LinkKind::Copy => {
+            if src_path.is_dir() {
+                copy_dir_recursive(&src_path, &dest_path).with_context(|| {
+                    format!(
+                        "copy directory {} -> {}",
+                        src_path.display(),
+                        dest_path.display()
+                    )
+                })?;
+            } else {
+                fs::copy(&src_path, &dest_path).with_context(|| {
+                    format!(
+                        "copy file {} -> {}",
+                        src_path.display(),
+                        dest_path.display()
+                    )
+                })?;
+            }
+        }
+    }
+
+    Ok(())
+}
+
+fn copy_dir_recursive(src: &Path, dest: &Path) -> Result<()> {
+    fs::create_dir_all(dest)?;
+    for entry in fs::read_dir(src)? {
+        let entry = entry?;
+        let entry_dest = dest.join(entry.file_name());
+        if entry.file_type()?.is_dir() {
+            copy_dir_recursive(&entry.path(), &entry_dest)?;
+        } else {
+            fs::copy(entry.path(), &entry_dest)?;
+        }
+    }
+    Ok(())
+}
+
 fn materialize_unit(workspace_root: &Path, unit: &UnitSpec) -> Result<()> {
     let unit_root = workspace_root.join(&unit.path);
     fs::create_dir_all(&unit_root)
@@ -215,6 +373,38 @@ fn materialize_unit(workspace_root: &Path, unit: &UnitSpec) -> Result<()> {
     Ok(())
 }
 
+fn record_apply_state(workspace_root: &Path, actions: &[String]) -> Result<()> {
+    let state_dir = workspace_root.join(".grip/state");
+    fs::create_dir_all(&state_dir)
+        .with_context(|| format!("create state directory {}", state_dir.display()))?;
+
+    let timestamp = chrono::Utc::now().to_rfc3339();
+    let mut content = format!("# Last apply: {}\n\n", timestamp);
+    content.push_str("[[applied]]\n");
+    content.push_str(&format!("timestamp = \"{}\"\n", timestamp));
+    content.push_str(&format!(
+        "actions = [{}]\n",
+        actions
+            .iter()
+            .map(|a| format!("\"{}\"", a.replace('"', "\\\"")))
+            .collect::<Vec<_>>()
+            .join(", ")
+    ));
+
+    let state_path = state_dir.join("applied.toml");
+
+    // Append to existing state file
+    if state_path.exists() {
+        let existing = fs::read_to_string(&state_path)?;
+        content = format!("{}\n{}", existing.trim_end(), content);
+    }
+
+    fs::write(&state_path, content)
+        .with_context(|| format!("write apply state to {}", state_path.display()))?;
+
+    Ok(())
+}
+
 fn render_unit_toml(unit: &UnitSpec) -> String {
     let repos = if unit.repos.is_empty() {
         "[]".to_string()
diff --git a/gr2/src/spec.rs b/gr2/src/spec.rs
index a1c6c2b4..b21c32cf 100644
--- a/gr2/src/spec.rs
+++ b/gr2/src/spec.rs
@@ -35,6 +35,47 @@ pub struct UnitSpec {
     pub path: String,
     #[serde(default)]
     pub repos: Vec<String>,
+    #[serde(default)]
+    pub links: Vec<LinkSpec>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct LinkSpec {
+    /// Source path relative to workspace root
+    pub src: String,
+    /// Destination path relative to unit root
+    pub dest: String,
+    #[serde(default)]
+    pub kind: LinkKind,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
+#[serde(rename_all = "snake_case")]
+pub enum LinkKind {
+    #[default]
+    Symlink,
+    Copy,
+}
+
+impl LinkKind {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Symlink => "symlink",
+            Self::Copy => "copy",
+        }
+    }
+}
+
+impl std::str::FromStr for LinkKind {
+    type Err = anyhow::Error;
+
+    fn from_str(s: &str) -> anyhow::Result<Self> {
+        match s {
+            "symlink" => Ok(Self::Symlink),
+            "copy" => Ok(Self::Copy),
+            _ => anyhow::bail!("unknown link kind '{}': expected 'symlink' or 'copy'", s),
+        }
+    }
 }
 
 impl WorkspaceSpec {
@@ -228,6 +269,7 @@ fn read_registered_units(workspace_root: &Path) -> Result<Vec<UnitSpec>> {
             name: fallback_name.clone(),
             path: format!("agents/{}", fallback_name),
             repos: Vec::new(),
+            links: Vec::new(),
         });
     }
 
diff --git a/src/cli/commands/branch.rs b/src/cli/commands/branch.rs
index 9c5ac4f3..91ddc099 100644
--- a/src/cli/commands/branch.rs
+++ b/src/cli/commands/branch.rs
@@ -4,7 +4,10 @@ use crate::cli::output::Output;
 use crate::core::manifest::Manifest;
 use crate::core::repo::{filter_repos, get_manifest_repo_info, RepoInfo};
 use crate::git::{
-    branch::{branch_exists, create_and_checkout_branch, delete_local_branch, list_local_branches},
+    branch::{
+        branch_exists, checkout_branch, create_and_checkout_branch, delete_local_branch,
+        list_local_branches,
+    },
     get_current_branch, open_repo,
 };
 use std::path::PathBuf;
@@ -473,15 +476,42 @@ pub fn run_branch(opts: BranchOptions<'_>) -> anyhow::Result<()> {
                 match open_repo(&repo.absolute_path) {
                     Ok(git_repo) => {
                         if branch_exists(&git_repo, branch_name) {
-                            if opts.json {
-                                json_results.push(JsonCreateResult {
-                                    repo: repo.name.clone(),
-                                    branch: branch_name.to_string(),
-                                    action: "already_exists".to_string(),
-                                    error: None,
-                                });
-                            } else {
-                                Output::info(&format!("{}: already exists", repo.name));
+                            // Branch exists — switch to it so subsequent commits
+                            // land on this branch, not the previous one (grip#401).
+                            match checkout_branch(&git_repo, branch_name) {
+                                Ok(()) => {
+                                    if opts.json {
+                                        json_results.push(JsonCreateResult {
+                                            repo: repo.name.clone(),
+                                            branch: branch_name.to_string(),
+                                            action: "switched".to_string(),
+                                            error: None,
+                                        });
+                                    } else {
+                                        Output::info(&format!(
+                                            "{}: already exists, switched",
+                                            repo.name
+                                        ));
+                                    }
+                                }
+                                Err(e) => {
+                                    if opts.json {
+                                        json_results.push(JsonCreateResult {
+                                            repo: repo.name.clone(),
+                                            branch: branch_name.to_string(),
+                                            action: "error".to_string(),
+                                            error: Some(format!(
+                                                "exists but failed to switch: {}",
+                                                e
+                                            )),
+                                        });
+                                    } else {
+                                        Output::error(&format!(
+                                            "{}: exists but failed to switch: {}",
+                                            repo.name, e
+                                        ));
+                                    }
+                                }
                             }
                             continue;
                         }
diff --git a/src/cli/commands/link.rs b/src/cli/commands/link.rs
index b43b3e1c..6e539e93 100644
--- a/src/cli/commands/link.rs
+++ b/src/cli/commands/link.rs
@@ -8,7 +8,104 @@ use crate::core::manifest_paths;
 use crate::core::repo::RepoInfo;
 use crate::files::{process_composefiles, resolve_file_source};
 use crate::git::path_exists;
-use std::path::Path;
+use std::path::{Path, PathBuf};
+
+/// Check if a source path contains glob characters (`*`, `?`, `[`).
+fn is_glob_pattern(src: &str) -> bool {
+    src.contains('*') || src.contains('?') || src.contains('[')
+}
+
+/// Expand a glob source pattern into individual (src, dest) pairs.
+///
+/// Given `src: "prompts/**"` and `dest: ".gitgrip/prompts/"`, this expands to:
+///   - `prompts/opus.md` -> `.gitgrip/prompts/opus.md`
+///   - `prompts/atlas.md` -> `.gitgrip/prompts/atlas.md`
+///
+/// The glob base (the non-glob prefix before the first glob character) is
+/// stripped from each matched path, and the remainder is appended to `dest`.
+fn expand_glob(src_pattern: &str, dest: &str, base_dir: &Path) -> Vec<(PathBuf, PathBuf)> {
+    let full_pattern = base_dir.join(src_pattern);
+    let pattern_str = match full_pattern.to_str() {
+        Some(s) => s.to_string(),
+        None => return Vec::new(),
+    };
+
+    let glob_base = glob_base_dir(src_pattern);
+
+    let entries = match glob::glob(&pattern_str) {
+        Ok(paths) => paths,
+        Err(e) => {
+            Output::warning(&format!("Invalid glob pattern '{}': {}", src_pattern, e));
+            return Vec::new();
+        }
+    };
+
+    let mut result = Vec::new();
+    for entry in entries.flatten() {
+        if entry.is_dir() {
+            continue; // only link/copy files, not directories
+        }
+        // Strip base_dir to get the repo-relative path
+        let rel_path = match entry.strip_prefix(base_dir) {
+            Ok(p) => p,
+            Err(_) => continue,
+        };
+        // Strip the glob base prefix to get the relative portion
+        let suffix = if glob_base.is_empty() {
+            rel_path.to_path_buf()
+        } else {
+            match rel_path.strip_prefix(&glob_base) {
+                Ok(s) => s.to_path_buf(),
+                Err(_) => rel_path.to_path_buf(),
+            }
+        };
+        let dest_path = PathBuf::from(dest).join(&suffix);
+        result.push((entry, dest_path));
+    }
+    result
+}
+
+/// Extract the non-glob directory prefix from a pattern.
+/// e.g. "prompts/**/*.md" -> "prompts", "**" -> "", "config/a*.toml" -> "config"
+fn glob_base_dir(pattern: &str) -> String {
+    let parts: Vec<&str> = pattern.split('/').collect();
+    let mut base_parts = Vec::new();
+    for part in parts {
+        if is_glob_pattern(part) {
+            break;
+        }
+        base_parts.push(part);
+    }
+    base_parts.join("/")
+}
+
+/// Expand a single src/dest pair, handling globs if present.
+/// For non-glob src, returns a single (absolute_source, dest) pair.
+/// For glob src, returns expanded pairs via `expand_glob`.
+fn expand_copy_pairs(src: &str, dest: &str, base_dir: &Path) -> Vec<(PathBuf, PathBuf)> {
+    if is_glob_pattern(src) {
+        expand_glob(src, dest, base_dir)
+    } else {
+        vec![(base_dir.join(src), PathBuf::from(dest))]
+    }
+}
+
+/// Create a symlink, returning (Result, label) for error reporting.
+/// Handles platform differences (unix symlink vs windows symlink_file/symlink_dir).
+fn apply_symlink(source: &Path, dest: &Path) -> (std::io::Result<()>, &'static str) {
+    #[cfg(unix)]
+    {
+        (std::os::unix::fs::symlink(source, dest), "symlink")
+    }
+    #[cfg(windows)]
+    {
+        if source.is_dir() {
+            (std::os::windows::fs::symlink_dir(source, dest), "symlink")
+        } else {
+            (std::os::windows::fs::symlink_file(source, dest), "symlink")
+        }
+    }
+}
 
 /// Run the link command
 pub fn run_link(
@@ -399,123 +496,83 @@ pub fn apply_links(workspace_root: &Path, manifest: &Manifest, quiet: bool) -> a
             continue;
         }
 
-        // Apply copyfiles
+        // Apply copyfiles (with glob expansion)
         if let Some(ref copyfiles) = config.copyfile {
-            for copyfile in copyfiles {
-                let source = repo
-                    .map(|r| r.absolute_path.join(&copyfile.src))
-                    .unwrap_or_else(|| workspace_root.join(&config.path).join(&copyfile.src));
-                let dest = workspace_root.join(&copyfile.dest);
-
-                if !source.exists() {
-                    Output::warning(&format!("Source not found: {:?}", source));
-                    errors += 1;
-                    continue;
-                }
+            let base_dir = repo
+                .map(|r| r.absolute_path.clone())
+                .unwrap_or_else(|| workspace_root.join(&config.path));
 
-                // Create parent directory if needed
-                if let Some(parent) = dest.parent() {
-                    std::fs::create_dir_all(parent)?;
-                }
-
-                match std::fs::copy(&source, &dest) {
-                    Ok(_) => {
-                        if !quiet {
-                            Output::success(&format!(
-                                "[copy] {} -> {}",
-                                copyfile.src, copyfile.dest
-                            ));
-                        }
-                        applied += 1;
-                    }
-                    Err(e) => {
-                        Output::error(&format!("Failed to copy: {}", e));
+            for copyfile in copyfiles {
+                let pairs = expand_copy_pairs(&copyfile.src, &copyfile.dest, &base_dir);
+                for (source, rel_dest) in &pairs {
+                    let dest = workspace_root.join(rel_dest);
+                    if !source.exists() {
+                        Output::warning(&format!("Source not found: {:?}", source));
                         errors += 1;
+                        continue;
+                    }
+                    if let Some(parent) = dest.parent() {
+                        std::fs::create_dir_all(parent)?;
+                    }
+                    match std::fs::copy(source, &dest) {
+                        Ok(_) => {
+                            if !quiet {
+                                Output::success(&format!(
+                                    "[copy] {} -> {}",
+                                    source.display(),
+                                    rel_dest.display()
+                                ));
+                            }
+                            applied += 1;
+                        }
+                        Err(e) => {
+                            Output::error(&format!("Failed to copy: {}", e));
+                            errors += 1;
+                        }
                     }
                 }
             }
         }
 
-        // Apply linkfiles
+        // Apply linkfiles (with glob expansion)
         if let Some(ref linkfiles) = config.linkfile {
-            for linkfile in linkfiles {
-                let source = repo
-                    .map(|r| r.absolute_path.join(&linkfile.src))
-                    .unwrap_or_else(|| workspace_root.join(&config.path).join(&linkfile.src));
-                let dest = workspace_root.join(&linkfile.dest);
+            let base_dir = repo
+                .map(|r| r.absolute_path.clone())
+                .unwrap_or_else(|| workspace_root.join(&config.path));
 
-                if !source.exists() {
-                    Output::warning(&format!("Source not found: {:?}", source));
-                    errors += 1;
-                    continue;
-                }
-
-                // Create parent directory if needed
-                if let Some(parent) = dest.parent() {
-                    std::fs::create_dir_all(parent)?;
-                }
-
-                // Remove existing link/file if present
-                if dest.exists() || dest.is_symlink() {
-                    let _ = std::fs::remove_file(&dest);
-                }
-
-                #[cfg(unix)]
-                {
-                    match std::os::unix::fs::symlink(&source, &dest) {
+            for linkfile in linkfiles {
+                let pairs = expand_copy_pairs(&linkfile.src, &linkfile.dest, &base_dir);
+                for (source, rel_dest) in &pairs {
+                    let dest = workspace_root.join(rel_dest);
+                    if !source.exists() {
+                        Output::warning(&format!("Source not found: {:?}", source));
+                        errors += 1;
+                        continue;
+                    }
+                    if let Some(parent) = dest.parent() {
+                        std::fs::create_dir_all(parent)?;
+                    }
+                    if dest.exists() || dest.is_symlink() {
+                        let _ = std::fs::remove_file(&dest);
+                    }
+                    let (result, label) = apply_symlink(source, &dest);
+                    match result {
                         Ok(_) => {
                             if !quiet {
                                 Output::success(&format!(
                                     "[link] {} -> {}",
-                                    linkfile.src, linkfile.dest
+                                    source.display(),
+                                    rel_dest.display()
                                 ));
                             }
                             applied += 1;
                         }
                         Err(e) => {
-                            Output::error(&format!("Failed to create symlink: {}", e));
+                            Output::error(&format!("Failed to create {}: {}", label, e));
                             errors += 1;
                         }
                     }
                 }
-
-                #[cfg(windows)]
-                {
-                    // On Windows, use junction for directories, symlink for files
-                    if source.is_dir() {
-                        match std::os::windows::fs::symlink_dir(&source, &dest) {
-                            Ok(_) => {
-                                if !quiet {
-                                    Output::success(&format!(
-                                        "[link] {} -> {}",
-                                        linkfile.src, linkfile.dest
-                                    ));
-                                }
-                                applied += 1;
-                            }
-                            Err(e) => {
-                                Output::error(&format!("Failed to create symlink: {}", e));
-                                errors += 1;
-                            }
-                        }
-                    } else {
-                        match std::os::windows::fs::symlink_file(&source, &dest) {
-                            Ok(_) => {
-                                if !quiet {
-                                    Output::success(&format!(
-                                        "[link] {} -> {}",
-                                        linkfile.src, linkfile.dest
-                                    ));
-                                }
-                                applied += 1;
-                            }
-                            Err(e) => {
-                                Output::error(&format!("Failed to create symlink: {}", e));
-                                errors += 1;
-                            }
-                        }
-                    }
-                }
             }
         }
     }
@@ -526,9 +583,37 @@ pub fn apply_links(workspace_root: &Path, manifest: &Manifest, quiet: bool) -> a
         let spaces_dir = manifest_paths::spaces_dir(workspace_root);
 
         if manifests_dir.exists() {
-            // Apply manifest copyfiles
+            // Apply manifest copyfiles (with glob expansion)
             if let Some(ref copyfiles) = manifest_config.copyfile {
                 for copyfile in copyfiles {
+                    // Glob expansion only for non-gripspace sources
+                    if !copyfile.src.starts_with("gripspace:") && is_glob_pattern(&copyfile.src) {
+                        let pairs = expand_glob(&copyfile.src, &copyfile.dest, &manifests_dir);
+                        for (source, rel_dest) in &pairs {
+                            let dest = workspace_root.join(rel_dest);
+                            if let Some(parent) = dest.parent() {
+                                std::fs::create_dir_all(parent)?;
+                            }
+                            match std::fs::copy(source, &dest) {
+                                Ok(_) => {
+                                    if !quiet {
+                                        Output::success(&format!(
+                                            "[copy] manifest:{} -> {}",
+                                            source.display(),
+                                            rel_dest.display()
+                                        ));
+                                    }
+                                    applied += 1;
+                                }
+                                Err(e) => {
+                                    Output::error(&format!("Failed to copy: {}", e));
+                                    errors += 1;
+                                }
+                            }
+                        }
+                        continue;
+                    }
+
                     let source =
                         match resolve_file_source(&copyfile.src, &manifests_dir, &spaces_dir) {
                             Ok(p) => p,
@@ -539,24 +624,19 @@ pub fn apply_links(workspace_root: &Path, manifest: &Manifest, quiet: bool) -> a
                             }
                         };
                     let dest = workspace_root.join(&copyfile.dest);
-
                     if !source.exists() {
                         Output::warning(&format!("Source not found: {:?}", source));
                         errors += 1;
                         continue;
                     }
-
-                    // Create parent directory if needed
                     if let Some(parent) = dest.parent() {
                         std::fs::create_dir_all(parent)?;
                     }
-
                     let label = if copyfile.src.starts_with("gripspace:") {
                         copyfile.src.clone()
                     } else {
                         format!("manifest:{}", copyfile.src)
                     };
-
                     match std::fs::copy(&source, &dest) {
                         Ok(_) => {
                             if !quiet {
@@ -572,9 +652,41 @@ pub fn apply_links(workspace_root: &Path, manifest: &Manifest, quiet: bool) -> a
                 }
             }
 
-            // Apply manifest linkfiles
+            // Apply manifest linkfiles (with glob expansion)
             if let Some(ref linkfiles) = manifest_config.linkfile {
                 for linkfile in linkfiles {
+                    // Glob expansion only for non-gripspace sources
+                    if !linkfile.src.starts_with("gripspace:") && is_glob_pattern(&linkfile.src) {
+                        let pairs = expand_glob(&linkfile.src, &linkfile.dest, &manifests_dir);
+                        for (source, rel_dest) in &pairs {
+                            let dest = workspace_root.join(rel_dest);
+                            if let Some(parent) = dest.parent() {
+                                std::fs::create_dir_all(parent)?;
+                            }
+                            if dest.exists() || dest.is_symlink() {
+                                let _ = std::fs::remove_file(&dest);
+                            }
+                            let (result, label) = apply_symlink(source, &dest);
+                            match result {
+                                Ok(_) => {
+                                    if !quiet {
+                                        Output::success(&format!(
+                                            "[link] manifest:{} -> {}",
+                                            source.display(),
+                                            rel_dest.display()
+                                        ));
+                                    }
+                                    applied += 1;
+                                }
+                                Err(e) => {
+                                    Output::error(&format!("Failed to create {}: {}", label, e));
+                                    errors += 1;
+                                }
+                            }
+                        }
+                        continue;
+                    }
+
                     let source =
                         match resolve_file_source(&linkfile.src, &manifests_dir, &spaces_dir) {
                             Ok(p) => p,
@@ -585,82 +697,33 @@ pub fn apply_links(workspace_root: &Path, manifest: &Manifest, quiet: bool) -> a
                             }
                         };
                     let dest = workspace_root.join(&linkfile.dest);
-
                     if !source.exists() {
                         Output::warning(&format!("Source not found: {:?}", source));
                         errors += 1;
                         continue;
                     }
-
-                    // Create parent directory if needed
                     if let Some(parent) = dest.parent() {
                         std::fs::create_dir_all(parent)?;
                     }
-
-                    // Remove existing link/file if present
                     if dest.exists() || dest.is_symlink() {
                         let _ = std::fs::remove_file(&dest);
                     }
-
                     let label = if linkfile.src.starts_with("gripspace:") {
                         linkfile.src.clone()
                     } else {
                         format!("manifest:{}", linkfile.src)
                     };
-
-                    #[cfg(unix)]
-                    {
-                        match std::os::unix::fs::symlink(&source, &dest) {
-                            Ok(_) => {
-                                if !quiet {
-                                    Output::success(&format!(
-                                        "[link] {} -> {}",
-                                        label, linkfile.dest
-                                    ));
-                                }
-                                applied += 1;
-                            }
-                            Err(e) => {
-                                Output::error(&format!("Failed to create symlink: {}", e));
-                                errors += 1;
+                    let (result, sym_label) = apply_symlink(&source, &dest);
+                    match result {
+                        Ok(_) => {
+                            if !quiet {
+                                Output::success(&format!("[link] {} -> {}", label, linkfile.dest));
                             }
+                            applied += 1;
                         }
-                    }
-
-                    #[cfg(windows)]
-                    {
-                        if source.is_dir() {
-                            match std::os::windows::fs::symlink_dir(&source, &dest) {
-                                Ok(_) => {
-                                    if !quiet {
-                                        Output::success(&format!(
-                                            "[link] {} -> {}",
-                                            label, linkfile.dest
-                                        ));
-                                    }
-                                    applied += 1;
-                                }
-                                Err(e) => {
-                                    Output::error(&format!("Failed to create symlink: {}", e));
-                                    errors += 1;
-                                }
-                            }
-                        } else {
-                            match std::os::windows::fs::symlink_file(&source, &dest) {
-                                Ok(_) => {
-                                    if !quiet {
-                                        Output::success(&format!(
-                                            "[link] {} -> {}",
-                                            label, linkfile.dest
-                                        ));
-                                    }
-                                    applied += 1;
-                                }
-                                Err(e) => {
-                                    Output::error(&format!("Failed to create symlink: {}", e));
-                                    errors += 1;
-                                }
-                            }
+                        Err(e) => {
+                            Output::error(&format!("Failed to create {}: {}", sym_label, e));
+                            errors += 1;
                         }
                     }
                 }
@@ -765,7 +828,7 @@ mod tests {
         let manifest = create_test_manifest(None, None);
 
         // Should not error even with no links
-        let result = show_link_status(&temp.path().to_path_buf(), &manifest, false);
+        let result = show_link_status(temp.path(), &manifest, false);
         assert!(result.is_ok());
     }
 
@@ -998,7 +1061,7 @@ mod tests {
         // Verify symlink points to the source file
         let dest_path = workspace.join("linked.config");
         let link_target = std::fs::read_link(&dest_path).unwrap();
-        let expected_source = repo_dir.join("shared.config");
+        let _expected_source = repo_dir.join("shared.config");
 
         // The target should resolve to the source file
         assert!(
@@ -1008,6 +1071,135 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_is_glob_pattern() {
+        assert!(is_glob_pattern("**"));
+        assert!(is_glob_pattern("*.md"));
+        assert!(is_glob_pattern("prompts/**"));
+        assert!(is_glob_pattern("config/?.toml"));
+        assert!(is_glob_pattern("[abc].txt"));
+        assert!(!is_glob_pattern("README.md"));
+        assert!(!is_glob_pattern("prompts/opus.md"));
+    }
+
+    #[test]
+    fn test_glob_base_dir() {
+        assert_eq!(glob_base_dir("**"), "");
+        assert_eq!(glob_base_dir("*.md"), "");
+        assert_eq!(glob_base_dir("prompts/**"), "prompts");
+        assert_eq!(glob_base_dir("config/nested/**/*.md"), "config/nested");
+        assert_eq!(glob_base_dir("a/b/c/*.txt"), "a/b/c");
+    }
+
+    #[test]
+    fn test_expand_glob_basic() {
+        let temp = TempDir::new().unwrap();
+        let base = temp.path();
+
+        // Create files
+        std::fs::create_dir_all(base.join("prompts")).unwrap();
+        std::fs::write(base.join("prompts/opus.md"), "opus").unwrap();
+        std::fs::write(base.join("prompts/atlas.md"), "atlas").unwrap();
+        std::fs::write(base.join("README.md"), "readme").unwrap();
+
+        let pairs = expand_glob("prompts/*", ".gitgrip/prompts/", base);
+        assert_eq!(pairs.len(), 2);
+
+        // Check that dest preserves the file name after stripping base
+        let dests: Vec<String> = pairs.iter().map(|(_, d)| d.display().to_string()).collect();
+        assert!(dests.contains(&".gitgrip/prompts/opus.md".to_string()));
+        assert!(dests.contains(&".gitgrip/prompts/atlas.md".to_string()));
+    }
+
+    #[test]
+    fn test_expand_glob_recursive() {
+        let temp = TempDir::new().unwrap();
+        let base = temp.path();
+
+        std::fs::create_dir_all(base.join("config/sub")).unwrap();
+        std::fs::write(base.join("config/a.toml"), "a").unwrap();
+        std::fs::write(base.join("config/sub/b.toml"), "b").unwrap();
+
+        let pairs = expand_glob("config/**/*.toml", "./", base);
+        assert_eq!(pairs.len(), 2);
+
+        let dests: Vec<String> = pairs.iter().map(|(_, d)| d.display().to_string()).collect();
+        assert!(dests.contains(&"a.toml".to_string()) || dests.contains(&"./a.toml".to_string()));
+    }
+
+    #[test]
+    fn test_expand_glob_skips_directories() {
+        let temp = TempDir::new().unwrap();
+        let base = temp.path();
+
+        std::fs::create_dir_all(base.join("config/subdir")).unwrap();
+        std::fs::write(base.join("config/file.txt"), "content").unwrap();
+
+        let pairs = expand_glob("config/*", "./", base);
+        // Should only include the file, not the directory
+        assert_eq!(pairs.len(), 1);
+    }
+
+    #[test]
+    fn test_apply_copyfile_glob() {
+        let temp = TempDir::new().unwrap();
+        let workspace = temp.path().to_path_buf();
+
+        // Create repo directory with multiple files
+        let repo_dir = workspace.join("test-repo");
+        let prompts_dir = repo_dir.join("prompts");
+        std::fs::create_dir_all(&prompts_dir).unwrap();
+        std::fs::write(prompts_dir.join("opus.md"), "# Opus").unwrap();
+        std::fs::write(prompts_dir.join("atlas.md"), "# Atlas").unwrap();
+
+        let copyfiles = vec![CopyFileConfig {
+            src: "prompts/*.md".to_string(),
+            dest: ".gitgrip/prompts/".to_string(),
+        }];
+
+        let manifest = create_test_manifest(Some(copyfiles), None);
+        let result = apply_links(&workspace, &manifest, true);
+        assert!(result.is_ok());
+
+        // Verify both files were copied
+        assert!(workspace.join(".gitgrip/prompts/opus.md").exists());
+        assert!(workspace.join(".gitgrip/prompts/atlas.md").exists());
+        assert_eq!(
+            std::fs::read_to_string(workspace.join(".gitgrip/prompts/opus.md")).unwrap(),
+            "# Opus"
+        );
+    }
+
+    #[test]
+    #[cfg(unix)]
+    fn test_apply_linkfile_glob() {
+        let temp = TempDir::new().unwrap();
+        let workspace = temp.path().to_path_buf();
+
+        let repo_dir = workspace.join("test-repo");
+        let prompts_dir = repo_dir.join("prompts");
+        std::fs::create_dir_all(&prompts_dir).unwrap();
+        std::fs::write(prompts_dir.join("opus.md"), "# Opus").unwrap();
+        std::fs::write(prompts_dir.join("atlas.md"), "# Atlas").unwrap();
+
+        let linkfiles = vec![LinkFileConfig {
+            src: "prompts/*.md".to_string(),
+            dest: ".gitgrip/prompts/".to_string(),
+        }];
+
+        let manifest = create_test_manifest(None, Some(linkfiles));
+        let result = apply_links(&workspace, &manifest, true);
+        assert!(result.is_ok());
+
+        // Verify symlinks were created
+        let opus_dest = workspace.join(".gitgrip/prompts/opus.md");
+        let atlas_dest = workspace.join(".gitgrip/prompts/atlas.md");
+        assert!(opus_dest.exists());
+        assert!(opus_dest.is_symlink());
+        assert!(atlas_dest.exists());
+        assert!(atlas_dest.is_symlink());
+    }
+
     #[test]
     #[cfg(unix)]
     fn test_linkfile_replaces_existing_file() {
diff --git a/src/cli/commands/migrate.rs b/src/cli/commands/migrate.rs
index 6b56e447..09448f46 100644
--- a/src/cli/commands/migrate.rs
+++ b/src/cli/commands/migrate.rs
@@ -266,11 +266,7 @@ fn generate_manifest_yaml(repos: &[(String, String)], org: &str, prefix: &str) -
 }
 
 /// Generate CLAUDE.md with repo table and agent context.
-fn generate_claude_md(
-    repos: &[(String, String)],
-    prefix: &str,
-    agents: &[AgentSpec],
-) -> String {
+fn generate_claude_md(repos: &[(String, String)], prefix: &str, agents: &[AgentSpec]) -> String {
     let mut md = String::new();
     md.push_str(&format!("# {}\n\n", prefix));
     md.push_str("Multi-repo workspace managed by **gitgrip** (`gr`). Always use `gr` — never raw `git` or `gh`.\n\n");
diff --git a/src/cli/commands/release.rs b/src/cli/commands/release.rs
index 9ac53267..76f147ee 100644
--- a/src/cli/commands/release.rs
+++ b/src/cli/commands/release.rs
@@ -1160,7 +1160,7 @@ version = "0.2.0"
             clone_strategy: crate::core::manifest::CloneStrategy::Clone,
         }];
 
-        let files = detect_version_files(&dir.path().to_path_buf(), &repos);
+        let files = detect_version_files(dir.path(), &repos);
         assert_eq!(files.len(), 1);
         assert_eq!(files[0].0, "my-repo");
         assert!(files[0].1.ends_with("Cargo.toml"));
@@ -1193,7 +1193,7 @@ version = "0.2.0"
             clone_strategy: crate::core::manifest::CloneStrategy::Clone,
         }];
 
-        let files = detect_version_files(&dir.path().to_path_buf(), &repos);
+        let files = detect_version_files(dir.path(), &repos);
         assert!(files.is_empty());
     }
 }
diff --git a/src/cli/commands/repo.rs b/src/cli/commands/repo.rs
index ecec6753..db59e0f6 100644
--- a/src/cli/commands/repo.rs
+++ b/src/cli/commands/repo.rs
@@ -288,7 +288,6 @@ mod tests {
 
 #[cfg(test)]
 mod yaml_insertion_tests {
-    use super::*;
 
     /// Helper function to extract the insertion logic for testing
     fn test_insert_yaml(content: &str, new_entry: &str) -> String {
diff --git a/src/cli/commands/tree.rs b/src/cli/commands/tree.rs
index e53f0f95..bac58717 100644
--- a/src/cli/commands/tree.rs
+++ b/src/cli/commands/tree.rs
@@ -1075,7 +1075,7 @@ fn stash_pop_repo(repo_path: &Path) -> anyhow::Result<()> {
 
 #[cfg(test)]
 mod tests {
-    use super::*;
+
     use tempfile::TempDir;
 
     #[test]
diff --git a/src/core/griptree.rs b/src/core/griptree.rs
index 7dbfc91b..28671f5a 100644
--- a/src/core/griptree.rs
+++ b/src/core/griptree.rs
@@ -355,7 +355,7 @@ mod tests {
     #[test]
     fn test_load_from_workspace_none_when_missing() {
         let temp = tempfile::TempDir::new().unwrap();
-        let result = GriptreeConfig::load_from_workspace(&temp.path().to_path_buf()).unwrap();
+        let result = GriptreeConfig::load_from_workspace(temp.path()).unwrap();
         assert!(result.is_none());
     }
 
@@ -369,7 +369,7 @@ mod tests {
         let config_path = gitgrip_dir.join("griptree.json");
         config.save(&config_path).unwrap();
 
-        let loaded = GriptreeConfig::load_from_workspace(&temp.path().to_path_buf())
+        let loaded = GriptreeConfig::load_from_workspace(temp.path())
             .unwrap()
             .expect("should find config");
         assert_eq!(loaded.branch, "feat/ws");
diff --git a/src/core/repo.rs b/src/core/repo.rs
index 950b3a58..f8bc8880 100644
--- a/src/core/repo.rs
+++ b/src/core/repo.rs
@@ -431,6 +431,22 @@ mod tests {
         assert_eq!(parsed.repo, "test-repo");
     }
 
+    #[test]
+    fn test_parse_github_org_ssh() {
+        // Regression test for grip#429: org URLs must extract owner correctly
+        let parsed = parse_git_url("git@github.com:synapt-dev/grip.git").unwrap();
+        assert_eq!(parsed.owner, "synapt-dev");
+        assert_eq!(parsed.repo, "grip");
+    }
+
+    #[test]
+    fn test_parse_github_org_https() {
+        // Regression test for grip#429: org URLs must extract owner correctly
+        let parsed = parse_git_url("https://github.com/synapt-dev/recall.git").unwrap();
+        assert_eq!(parsed.owner, "synapt-dev");
+        assert_eq!(parsed.repo, "recall");
+    }
+
     #[test]
     fn test_detect_github() {
         assert_eq!(
@@ -664,13 +680,7 @@ mod tests {
         };
 
         let filter = vec!["app".to_string()];
-        let result = filter_repos(
-            &manifest,
-            &temp.path().to_path_buf(),
-            Some(&filter),
-            None,
-            false,
-        );
+        let result = filter_repos(&manifest, temp.path(), Some(&filter), None, false);
         assert_eq!(result.len(), 1);
         assert_eq!(result[0].name, "app");
     }
@@ -732,12 +742,12 @@ mod tests {
             workspace: None,
         };
 
-        let result = filter_repos(&manifest, &temp.path().to_path_buf(), None, None, false);
+        let result = filter_repos(&manifest, temp.path(), None, None, false);
         assert_eq!(result.len(), 1);
         assert_eq!(result[0].name, "normal");
 
         // With include_reference = true
-        let result = filter_repos(&manifest, &temp.path().to_path_buf(), None, None, true);
+        let result = filter_repos(&manifest, temp.path(), None, None, true);
         assert_eq!(result.len(), 2);
     }
 
@@ -799,13 +809,7 @@ mod tests {
         };
 
         let groups = vec!["web".to_string()];
-        let result = filter_repos(
-            &manifest,
-            &temp.path().to_path_buf(),
-            None,
-            Some(&groups),
-            false,
-        );
+        let result = filter_repos(&manifest, temp.path(), None, Some(&groups), false);
         assert_eq!(result.len(), 1);
         assert_eq!(result[0].name, "frontend");
     }
@@ -835,9 +839,7 @@ mod tests {
             clone_strategy: None,
         };
         let settings = ManifestSettings::default();
-        let info =
-            RepoInfo::from_config("app", &config, &temp.path().to_path_buf(), &settings, None)
-                .unwrap();
+        let info = RepoInfo::from_config("app", &config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.revision, "develop");
 
         // repo omits revision, inherits from settings
@@ -861,16 +863,12 @@ mod tests {
             revision: Some("master".to_string()),
             ..Default::default()
         };
-        let info =
-            RepoInfo::from_config("app", &config, &temp.path().to_path_buf(), &settings, None)
-                .unwrap();
+        let info = RepoInfo::from_config("app", &config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.revision, "master");
 
         // both omit → falls back to "main"
         let settings = ManifestSettings::default();
-        let info =
-            RepoInfo::from_config("app", &config, &temp.path().to_path_buf(), &settings, None)
-                .unwrap();
+        let info = RepoInfo::from_config("app", &config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.revision, "main");
     }
 
@@ -899,14 +897,8 @@ mod tests {
 
         // No target → falls back to revision
         let settings = ManifestSettings::default();
-        let info = RepoInfo::from_config(
-            "app",
-            &base_config,
-            &temp.path().to_path_buf(),
-            &settings,
-            None,
-        )
-        .unwrap();
+        let info =
+            RepoInfo::from_config("app", &base_config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.target, "main");
         assert_eq!(info.target_branch(), "main");
         assert_eq!(info.sync_ref(), "origin/main");
@@ -916,14 +908,8 @@ mod tests {
             target: Some("develop".to_string()),
             ..Default::default()
         };
-        let info = RepoInfo::from_config(
-            "app",
-            &base_config,
-            &temp.path().to_path_buf(),
-            &settings,
-            None,
-        )
-        .unwrap();
+        let info =
+            RepoInfo::from_config("app", &base_config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.target, "develop");
         assert_eq!(info.target_branch(), "develop");
 
@@ -936,9 +922,7 @@ mod tests {
             target: Some("develop".to_string()),
             ..Default::default()
         };
-        let info =
-            RepoInfo::from_config("app", &config, &temp.path().to_path_buf(), &settings, None)
-                .unwrap();
+        let info = RepoInfo::from_config("app", &config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.target, "staging");
         assert_eq!(info.target_branch(), "staging");
     }
@@ -968,14 +952,8 @@ mod tests {
 
         // Defaults to "origin"
         let settings = ManifestSettings::default();
-        let info = RepoInfo::from_config(
-            "app",
-            &base_config,
-            &temp.path().to_path_buf(),
-            &settings,
-            None,
-        )
-        .unwrap();
+        let info =
+            RepoInfo::from_config("app", &base_config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.sync_remote, "origin");
         assert_eq!(info.push_remote, "origin");
 
@@ -985,14 +963,8 @@ mod tests {
             push_remote: Some("myfork".to_string()),
             ..Default::default()
         };
-        let info = RepoInfo::from_config(
-            "app",
-            &base_config,
-            &temp.path().to_path_buf(),
-            &settings,
-            None,
-        )
-        .unwrap();
+        let info =
+            RepoInfo::from_config("app", &base_config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.sync_remote, "upstream");
         assert_eq!(info.push_remote, "myfork");
 
@@ -1002,9 +974,7 @@ mod tests {
             push_remote: Some("origin".to_string()),
             ..base_config.clone()
         };
-        let info =
-            RepoInfo::from_config("app", &config, &temp.path().to_path_buf(), &settings, None)
-                .unwrap();
+        let info = RepoInfo::from_config("app", &config, temp.path(), &settings, None).unwrap();
         assert_eq!(info.sync_remote, "other");
         assert_eq!(info.push_remote, "origin");
     }
@@ -1041,14 +1011,8 @@ mod tests {
             clone_strategy: None,
         };
         let settings = ManifestSettings::default();
-        let info = RepoInfo::from_config(
-            "myrepo",
-            &config,
-            &temp.path().to_path_buf(),
-            &settings,
-            Some(&remotes),
-        )
-        .unwrap();
+        let info = RepoInfo::from_config("myrepo", &config, temp.path(), &settings, Some(&remotes))
+            .unwrap();
         assert_eq!(info.url, "git@github.com:org/myrepo.git");
     }
 
@@ -1144,7 +1108,7 @@ repos:
         let info = RepoInfo::from_config(
             "app",
             &manifest.repos["app"],
-            &temp.path().to_path_buf(),
+            temp.path(),
             &manifest.settings,
             manifest.remotes.as_ref(),
         )
diff --git a/src/git/branch.rs b/src/git/branch.rs
index 36f8763d..31e00760 100644
--- a/src/git/branch.rs
+++ b/src/git/branch.rs
@@ -374,7 +374,7 @@ mod tests {
 
     #[test]
     fn test_create_and_checkout_branch() {
-        let (temp, repo) = setup_test_repo();
+        let (_temp, repo) = setup_test_repo();
 
         create_and_checkout_branch(&repo, "feature").unwrap();
 
@@ -384,7 +384,7 @@ mod tests {
 
     #[test]
     fn test_branch_exists() {
-        let (temp, repo) = setup_test_repo();
+        let (_temp, repo) = setup_test_repo();
 
         assert!(!branch_exists(&repo, "feature"));
 
@@ -394,7 +394,7 @@ mod tests {
 
     #[test]
     fn test_checkout_branch() {
-        let (temp, repo) = setup_test_repo();
+        let (_temp, repo) = setup_test_repo();
 
         // Create a feature branch
         create_and_checkout_branch(&repo, "feature").unwrap();
@@ -413,7 +413,7 @@ mod tests {
 
     #[test]
     fn test_list_local_branches() {
-        let (temp, repo) = setup_test_repo();
+        let (_temp, repo) = setup_test_repo();
 
         create_and_checkout_branch(&repo, "feature1").unwrap();
         create_and_checkout_branch(&repo, "feature2").unwrap();
diff --git a/src/git/remote.rs b/src/git/remote.rs
index 7dde7482..a2cae999 100644
--- a/src/git/remote.rs
+++ b/src/git/remote.rs
@@ -725,7 +725,7 @@ mod tests {
 
     #[test]
     fn test_set_remote_url() {
-        let (temp, repo) = setup_test_repo();
+        let (_temp, repo) = setup_test_repo();
 
         // Create new remote
         set_remote_url(&repo, "origin", "https://github.com/test/repo1.git").unwrap();
diff --git a/src/platform/rate_limit.rs b/src/platform/rate_limit.rs
index c9853d76..fb20bd07 100644
--- a/src/platform/rate_limit.rs
+++ b/src/platform/rate_limit.rs
@@ -238,7 +238,7 @@ mod tests {
         };
         let wait = info.wait_seconds().unwrap();
         // Should be approximately 120 seconds (allow 2s tolerance for test execution)
-        assert!(wait >= 118 && wait <= 122, "wait_seconds was {}", wait);
+        assert!((118..=122).contains(&wait), "wait_seconds was {}", wait);
     }
 
     #[test]
diff --git a/src/telemetry/metrics.rs b/src/telemetry/metrics.rs
index f8a50f61..5d423d94 100644
--- a/src/telemetry/metrics.rs
+++ b/src/telemetry/metrics.rs
@@ -399,7 +399,7 @@ mod tests {
 
         // p50 should be around 50 (rounding may cause slight differences)
         let p50 = hist.p50().unwrap().as_millis();
-        assert!(p50 >= 49 && p50 <= 51, "p50 was {p50}, expected ~50");
+        assert!((49..=51).contains(&p50), "p50 was {p50}, expected ~50");
         assert!(hist.p99().unwrap() >= Duration::from_millis(99));
     }
 
diff --git a/tests/cli_tests.rs b/tests/cli_tests.rs
index ca1b04c5..a005d4fc 100644
--- a/tests/cli_tests.rs
+++ b/tests/cli_tests.rs
@@ -1379,7 +1379,7 @@ fn test_checkout_base_uses_griptree_config() {
     git_helpers::create_branch(&ws.repo_path("lib"), "feat/base");
     git_helpers::checkout(&ws.repo_path("lib"), "main");
 
-    let mut config = GriptreeConfig::new("feat/base", &ws.workspace_root.to_string_lossy());
+    let config = GriptreeConfig::new("feat/base", &ws.workspace_root.to_string_lossy());
     let config_path = ws.workspace_root.join(".gitgrip").join("griptree.json");
     config.save(&config_path).unwrap();
 
@@ -1701,3 +1701,519 @@ fn test_checkout_remove_rejects_extra_positional_args() {
             "unexpected extra arguments after checkout name",
         ));
 }
+
+// ─── gr2 apply link operations (grip#514) ──────────────────────────────
+
+#[test]
+fn test_gr2_plan_detects_missing_symlink() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    // Create a source file that the link will point to
+    std::fs::write(
+        workspace_root.join("config/shared.toml"),
+        "key = \"value\"\n",
+    )
+    .unwrap();
+
+    // Create the unit directory so Clone isn't planned
+    std::fs::create_dir_all(workspace_root.join("agents/atlas")).unwrap();
+    std::fs::write(
+        workspace_root.join("agents/atlas/unit.toml"),
+        "name = \"atlas\"\nkind = \"unit\"\n",
+    )
+    .unwrap();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = []
+
+[[units.links]]
+src = "config/shared.toml"
+dest = ".config/shared.toml"
+kind = "symlink"
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("link"))
+        .stdout(predicate::str::contains("config/shared.toml"));
+}
+
+#[test]
+fn test_gr2_apply_creates_symlink() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    // Create a source file
+    std::fs::write(
+        workspace_root.join("config/shared.toml"),
+        "key = \"value\"\n",
+    )
+    .unwrap();
+
+    // Create the unit directory
+    std::fs::create_dir_all(workspace_root.join("agents/atlas")).unwrap();
+    std::fs::write(
+        workspace_root.join("agents/atlas/unit.toml"),
+        "name = \"atlas\"\nkind = \"unit\"\n",
+    )
+    .unwrap();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = []
+
+[[units.links]]
+src = "config/shared.toml"
+dest = ".config/shared.toml"
+kind = "symlink"
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "symlink config/shared.toml -> agents/atlas/.config/shared.toml",
+        ));
+
+    let link_path = workspace_root.join("agents/atlas/.config/shared.toml");
+    assert!(link_path.exists(), "symlink destination should exist");
+    assert!(
+        link_path
+            .symlink_metadata()
+            .unwrap()
+            .file_type()
+            .is_symlink(),
+        "destination should be a symlink"
+    );
+
+    let content = std::fs::read_to_string(&link_path).unwrap();
+    assert_eq!(content, "key = \"value\"\n");
+}
+
+#[test]
+fn test_gr2_apply_creates_copy() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    std::fs::write(
+        workspace_root.join("config/env.toml"),
+        "env = \"production\"\n",
+    )
+    .unwrap();
+
+    std::fs::create_dir_all(workspace_root.join("agents/apollo")).unwrap();
+    std::fs::write(
+        workspace_root.join("agents/apollo/unit.toml"),
+        "name = \"apollo\"\nkind = \"unit\"\n",
+    )
+    .unwrap();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = []
+
+[[units.links]]
+src = "config/env.toml"
+dest = "env.toml"
+kind = "copy"
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "copy config/env.toml -> agents/apollo/env.toml",
+        ));
+
+    let dest_path = workspace_root.join("agents/apollo/env.toml");
+    assert!(dest_path.exists(), "copy destination should exist");
+    assert!(
+        !dest_path
+            .symlink_metadata()
+            .unwrap()
+            .file_type()
+            .is_symlink(),
+        "copy destination should NOT be a symlink"
+    );
+
+    let content = std::fs::read_to_string(&dest_path).unwrap();
+    assert_eq!(content, "env = \"production\"\n");
+}
+
+#[test]
+fn test_gr2_apply_link_fails_for_missing_source() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    std::fs::create_dir_all(workspace_root.join("agents/atlas")).unwrap();
+    std::fs::write(
+        workspace_root.join("agents/atlas/unit.toml"),
+        "name = \"atlas\"\nkind = \"unit\"\n",
+    )
+    .unwrap();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = []
+
+[[units.links]]
+src = "nonexistent/file.toml"
+dest = "file.toml"
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("link source does not exist"));
+}
+
+#[test]
+fn test_gr2_plan_noop_when_link_already_exists() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    std::fs::write(
+        workspace_root.join("config/shared.toml"),
+        "key = \"value\"\n",
+    )
+    .unwrap();
+
+    std::fs::create_dir_all(workspace_root.join("agents/atlas/.config")).unwrap();
+    std::fs::write(
+        workspace_root.join("agents/atlas/unit.toml"),
+        "name = \"atlas\"\nkind = \"unit\"\n",
+    )
+    .unwrap();
+    // Pre-create the destination so the link is already satisfied
+    std::fs::write(
+        workspace_root.join("agents/atlas/.config/shared.toml"),
+        "existing",
+    )
+    .unwrap();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = []
+
+[[units.links]]
+src = "config/shared.toml"
+dest = ".config/shared.toml"
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("no changes required"));
+}
+
+#[test]
+fn test_gr2_apply_records_state() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = []
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success();
+
+    let state_path = workspace_root.join(".grip/state/applied.toml");
+    assert!(state_path.exists(), "apply should record state");
+
+    let state = std::fs::read_to_string(&state_path).unwrap();
+    assert!(
+        state.contains("[[applied]]"),
+        "state should contain applied entries"
+    );
+    assert!(
+        state.contains("cloned unit"),
+        "state should record clone action"
+    );
+}
+
+#[test]
+fn test_gr2_apply_mixed_clone_and_link() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    std::fs::write(workspace_root.join("config/shared.toml"), "shared = true\n").unwrap();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = []
+
+[[units.links]]
+src = "config/shared.toml"
+dest = ".config/shared.toml"
+kind = "symlink"
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("cloned unit 'atlas'"))
+        .stdout(predicate::str::contains("symlink config/shared.toml"));
+
+    assert!(workspace_root.join("agents/atlas/unit.toml").exists());
+    assert!(workspace_root
+        .join("agents/atlas/.config/shared.toml")
+        .exists());
+}
+
+// ── gr2 apply TDD specs (grip#514, grip#526) ────────────────────────────────
+
+/// gr2 apply is a recognized subcommand (not "error: unrecognized subcommand").
+#[test]
+fn test_gr2_apply_command_recognized() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .stderr(predicate::str::contains("unrecognized subcommand").not());
+}
+
+/// gr2 apply outside a gr2 workspace returns a clear error.
+#[test]
+fn test_gr2_apply_requires_gr2_workspace() {
+    let temp = TempDir::new().unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(temp.path())
+        .arg("apply")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("not in a gr2 workspace"));
+}
+
+/// gr2 apply is idempotent: running twice on a fully-materialized workspace
+/// succeeds without error.
+#[test]
+fn test_gr2_apply_idempotent_on_materialized_workspace() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = []
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    let mut first = Command::cargo_bin("gr2").unwrap();
+    first
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success();
+
+    let mut second = Command::cargo_bin("gr2").unwrap();
+    second
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success();
+}
diff --git a/tests/common/mock_platform.rs b/tests/common/mock_platform.rs
index 8b4f5955..b46c6432 100644
--- a/tests/common/mock_platform.rs
+++ b/tests/common/mock_platform.rs
@@ -194,7 +194,7 @@ fn github_pr_json(
     body: &str,
 ) -> Value {
     let repo = github_repo_json("owner", "repo");
-    let api_base = format!("https://api.github.com/repos/owner/repo");
+    let api_base = "https://api.github.com/repos/owner/repo".to_string();
 
     let mut m = Map::new();
     m.insert("id".into(), json!(number));
diff --git a/tests/griptree_tests.rs b/tests/griptree_tests.rs
index 0101905c..4af25c82 100644
--- a/tests/griptree_tests.rs
+++ b/tests/griptree_tests.rs
@@ -82,7 +82,7 @@ fn test_griptree_pointer_new_fields() {
     assert_eq!(pointer.repos.len(), 1);
     assert_eq!(pointer.repos[0].name, "codi");
     assert_eq!(pointer.repos[0].original_branch, "main");
-    assert_eq!(pointer.repos[0].is_reference, false);
+    assert!(!pointer.repos[0].is_reference);
     assert_eq!(
         pointer.manifest_branch,
         Some("griptree-feat-test".to_string())
@@ -206,5 +206,5 @@ fn test_griptree_repo_info_camel_case() {
 
     let deserialized: GriptreeRepoInfo = serde_json::from_str(&json).unwrap();
     assert_eq!(deserialized.original_branch, "develop");
-    assert_eq!(deserialized.is_reference, false);
+    assert!(!deserialized.is_reference);
 }
diff --git a/tests/integration_agent_id.rs b/tests/integration_agent_id.rs
index 54f3cd1b..4e5ae987 100644
--- a/tests/integration_agent_id.rs
+++ b/tests/integration_agent_id.rs
@@ -6,7 +6,6 @@
 //! Conversa migration test in CI.
 
 use std::fs;
-use std::path::PathBuf;
 use tempfile::TempDir;
 
 // Re-export the registry functions we're testing
diff --git a/tests/multi_provider_e2e.rs b/tests/multi_provider_e2e.rs
index 26becef3..19c147fe 100644
--- a/tests/multi_provider_e2e.rs
+++ b/tests/multi_provider_e2e.rs
@@ -151,7 +151,7 @@ mod github_tests {
 
         // Verify manifest
         let manifest_path =
-            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(&workspace)
+            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(workspace)
                 .expect("manifest not found");
         let manifest = fs::read_to_string(&manifest_path).unwrap();
         assert!(manifest.contains("repo1"), "repo1 not in manifest");
@@ -339,7 +339,7 @@ mod gitlab_tests {
         );
 
         let manifest_path =
-            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(&workspace)
+            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(workspace)
                 .expect("manifest not found");
         let manifest = fs::read_to_string(&manifest_path).unwrap();
         assert!(manifest.contains("repo1"));
@@ -454,7 +454,7 @@ mod gitlab_tests {
 
         // Read and print the manifest
         let manifest_path =
-            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(&workspace)
+            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(workspace)
                 .expect("manifest not found");
         if manifest_path.exists() {
             let manifest_content = fs::read_to_string(&manifest_path).unwrap();
@@ -633,7 +633,7 @@ mod azure_tests {
         );
 
         let manifest_path =
-            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(&workspace)
+            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(workspace)
                 .expect("manifest not found");
         let manifest = fs::read_to_string(&manifest_path).unwrap();
         assert!(manifest.contains("repo1"));
@@ -853,7 +853,7 @@ mod mixed_platform_tests {
         );
 
         let manifest_path =
-            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(&workspace)
+            gitgrip::core::manifest_paths::resolve_gripspace_manifest_path(workspace)
                 .expect("manifest not found");
         let manifest = fs::read_to_string(&manifest_path).unwrap();
 
diff --git a/tests/test_add.rs b/tests/test_add.rs
index e05e0c42..de99bb61 100644
--- a/tests/test_add.rs
+++ b/tests/test_add.rs
@@ -2,7 +2,6 @@
 
 mod common;
 
-use common::assertions::assert_repo_clean;
 use common::fixtures::WorkspaceBuilder;
 
 #[test]
diff --git a/tests/test_branch.rs b/tests/test_branch.rs
index ee30a23e..07ff3aec 100644
--- a/tests/test_branch.rs
+++ b/tests/test_branch.rs
@@ -2,9 +2,7 @@
 
 mod common;
 
-use common::assertions::{
-    assert_all_on_branch, assert_branch_exists, assert_branch_not_exists, assert_on_branch,
-};
+use common::assertions::{assert_branch_exists, assert_branch_not_exists, assert_on_branch};
 use common::fixtures::WorkspaceBuilder;
 use common::git_helpers;
 
@@ -300,3 +298,51 @@ fn test_branch_create_then_verify_branches_exist() {
     assert_branch_exists(&ws.repo_path("alpha"), "main");
     assert_branch_exists(&ws.repo_path("beta"), "main");
 }
+
+/// Regression test for grip#401: `gr branch` on an existing branch must
+/// switch to it so subsequent commits land on the correct branch.
+#[test]
+fn test_branch_switches_to_existing_branch() {
+    let ws = WorkspaceBuilder::new().add_repo("app").build();
+    let manifest = ws.load_manifest();
+
+    // Create feat/target and then switch back to main
+    gitgrip::cli::commands::branch::run_branch(gitgrip::cli::commands::branch::BranchOptions {
+        workspace_root: &ws.workspace_root,
+        manifest: &manifest,
+        name: Some("feat/target"),
+        delete: false,
+        move_commits: false,
+        repos_filter: None,
+        group_filter: None,
+        json: false,
+    })
+    .unwrap();
+
+    gitgrip::cli::commands::checkout::run_checkout(
+        &ws.workspace_root,
+        &manifest,
+        "main",
+        false,
+        None,
+        None,
+    )
+    .unwrap();
+    assert_on_branch(&ws.repo_path("app"), "main");
+
+    // Run `gr branch feat/target` again — should switch to it
+    gitgrip::cli::commands::branch::run_branch(gitgrip::cli::commands::branch::BranchOptions {
+        workspace_root: &ws.workspace_root,
+        manifest: &manifest,
+        name: Some("feat/target"),
+        delete: false,
+        move_commits: false,
+        repos_filter: None,
+        group_filter: None,
+        json: false,
+    })
+    .unwrap();
+
+    // Must be on feat/target, not main
+    assert_on_branch(&ws.repo_path("app"), "feat/target");
+}
diff --git a/tests/test_commit.rs b/tests/test_commit.rs
index 6bf2bc48..c207a13b 100644
--- a/tests/test_commit.rs
+++ b/tests/test_commit.rs
@@ -4,7 +4,6 @@ mod common;
 
 use common::assertions::assert_repo_clean;
 use common::fixtures::WorkspaceBuilder;
-use common::git_helpers;
 
 #[test]
 fn test_commit_across_repos() {
diff --git a/tests/test_status.rs b/tests/test_status.rs
index 8d694697..f7b00ba1 100644
--- a/tests/test_status.rs
+++ b/tests/test_status.rs
@@ -2,9 +2,7 @@
 
 mod common;
 
-use common::assertions;
 use common::fixtures::WorkspaceBuilder;
-use common::git_helpers;
 
 #[test]
 fn test_status_clean_workspace() {

From 8da763febc1604f4cbd31aba4f597a995958b497 Mon Sep 17 00:00:00 2001
From: Layne Penney <dev@layne.pro>
Date: Sat, 11 Apr 2026 21:38:40 -0500
Subject: [PATCH 09/15] Sprint 18 ceremony: grip (#541)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
---
 gr2/src/args.rs     |   4 +
 gr2/src/dispatch.rs |  24 +-
 gr2/src/plan.rs     | 330 ++++++++++++++++--
 tests/cli_tests.rs  | 833 +++++++++++++++++++++++++++++++++++++++++++-
 4 files changed, 1150 insertions(+), 41 deletions(-)

diff --git a/gr2/src/args.rs b/gr2/src/args.rs
index 0945cb17..69c1bcd3 100644
--- a/gr2/src/args.rs
+++ b/gr2/src/args.rs
@@ -68,6 +68,10 @@ pub enum Commands {
         /// Pre-approve plans with more than 3 operations
         #[arg(long)]
         yes: bool,
+
+        /// Automatically stash and restore uncommitted changes in dirty repos
+        #[arg(long)]
+        autostash: bool,
     },
 }
 
diff --git a/gr2/src/dispatch.rs b/gr2/src/dispatch.rs
index cc0bbbba..40e60366 100644
--- a/gr2/src/dispatch.rs
+++ b/gr2/src/dispatch.rs
@@ -362,7 +362,10 @@ pub async fn dispatch_command(command: Commands, verbose: bool) -> Result<()> {
         Commands::Plan { yes } => {
             let workspace_root = require_workspace_root()?;
             let build = ExecutionPlan::from_workspace_spec(&workspace_root)?;
-            let guard_report = build.plan.guard_for_apply(&workspace_root, yes)?;
+            let guard_report =
+                build
+                    .plan
+                    .guard_for_apply(&workspace_root, &build.spec, yes, false)?;
 
             if build.generated_spec {
                 println!(
@@ -379,10 +382,13 @@ pub async fn dispatch_command(command: Commands, verbose: bool) -> Result<()> {
             }
             Ok(())
         }
-        Commands::Apply { yes } => {
+        Commands::Apply { yes, autostash } => {
             let workspace_root = require_workspace_root()?;
             let build = ExecutionPlan::from_workspace_spec(&workspace_root)?;
-            let guard_report = build.plan.guard_for_apply(&workspace_root, yes)?;
+            let guard_report =
+                build
+                    .plan
+                    .guard_for_apply(&workspace_root, &build.spec, yes, autostash)?;
 
             if build.generated_spec {
                 println!(
@@ -395,11 +401,21 @@ pub async fn dispatch_command(command: Commands, verbose: bool) -> Result<()> {
                 anyhow::bail!("plan contains more than 3 operations; rerun with --yes to apply it");
             }
 
+            if guard_report.has_dirty_repos && !autostash {
+                anyhow::bail!(
+                    "refusing to apply: units have repos with uncommitted changes; \
+                     rerun with --autostash to stash and restore them automatically"
+                );
+            }
+
             for warning in &guard_report.warnings {
                 println!("warning: {}", warning);
             }
 
-            let applied = build.plan.apply(&workspace_root, &build.spec)?;
+            let applied =
+                build
+                    .plan
+                    .apply(&workspace_root, &build.spec, &guard_report.dirty_repos)?;
             if applied.is_empty() {
                 println!("ExecutionPlan");
                 println!("- no changes required");
diff --git a/gr2/src/plan.rs b/gr2/src/plan.rs
index 1e12dab8..bced6892 100644
--- a/gr2/src/plan.rs
+++ b/gr2/src/plan.rs
@@ -2,7 +2,7 @@ use anyhow::{Context, Result};
 use serde::{Deserialize, Serialize};
 use std::collections::BTreeMap;
 use std::fs;
-use std::path::Path;
+use std::path::{Path, PathBuf};
 
 use crate::spec::{
     read_workspace_spec, workspace_spec_path, write_workspace_spec, LinkKind, LinkSpec, UnitSpec,
@@ -38,10 +38,20 @@ pub enum OperationType {
     Link,
 }
 
+/// A repo inside a unit that has uncommitted changes.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct DirtyRepo {
+    pub unit_name: String,
+    pub repo_name: String,
+    pub repo_path: PathBuf,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PlanGuardReport {
     pub warnings: Vec<String>,
     pub requires_confirmation: bool,
+    pub has_dirty_repos: bool,
+    pub dirty_repos: Vec<DirtyRepo>,
 }
 
 impl ExecutionPlan {
@@ -77,15 +87,34 @@ impl ExecutionPlan {
                 // doesn't exist yet, but they should be planned alongside the Clone)
             } else {
                 let expected_path = format!("agents/{}", unit.name);
-                if unit.path != expected_path {
+                let path_mismatch = unit.path != expected_path;
+
+                // Check for missing repo checkouts inside the unit
+                let missing_repos: Vec<&str> = unit
+                    .repos
+                    .iter()
+                    .filter(|repo_name| !unit_root.join(repo_name).exists())
+                    .map(|s| s.as_str())
+                    .collect();
+
+                if path_mismatch || !missing_repos.is_empty() {
                     let mut parameters = BTreeMap::new();
                     parameters.insert("path".to_string(), unit.path.clone());
                     parameters.insert("repos".to_string(), unit.repos.join(","));
+                    let preview = if !missing_repos.is_empty() {
+                        format!(
+                            "converge unit '{}': clone missing repos [{}]",
+                            unit.name,
+                            missing_repos.join(", ")
+                        )
+                    } else {
+                        format!("reconfigure unit '{}' to match {}", unit.name, unit.path)
+                    };
                     operations.push(PlanOperation {
                         unit_name: unit.name.clone(),
                         operation: OperationType::Configure,
                         parameters,
-                        preview: format!("reconfigure unit '{}' to match {}", unit.name, unit.path),
+                        preview,
                     });
                 }
             }
@@ -121,9 +150,48 @@ impl ExecutionPlan {
         })
     }
 
-    pub fn apply(&self, workspace_root: &Path, spec: &WorkspaceSpec) -> Result<Vec<String>> {
+    pub fn apply(
+        &self,
+        workspace_root: &Path,
+        spec: &WorkspaceSpec,
+        dirty_repos: &[DirtyRepo],
+    ) -> Result<Vec<String>> {
         let mut applied = Vec::new();
 
+        // Autostash: stash dirty repos before operations
+        let stashed = autostash_dirty_repos(dirty_repos)?;
+
+        let result = self.apply_operations(workspace_root, spec, &mut applied);
+
+        // Autostash: pop stashes regardless of operation success
+        let pop_errors = autostash_pop(&stashed);
+
+        // Record stash state if any stashes were created
+        if !stashed.is_empty() {
+            record_stash_state(workspace_root, &stashed, &pop_errors)?;
+        }
+
+        // Propagate operation errors after cleanup
+        result?;
+
+        if !applied.is_empty() {
+            record_apply_state(workspace_root, &applied)?;
+        }
+
+        // Report pop errors as warnings but don't fail
+        for err in &pop_errors {
+            applied.push(format!("warning: stash pop failed: {}", err));
+        }
+
+        Ok(applied)
+    }
+
+    fn apply_operations(
+        &self,
+        workspace_root: &Path,
+        spec: &WorkspaceSpec,
+        applied: &mut Vec<String>,
+    ) -> Result<()> {
         for operation in &self.operations {
             let unit_spec = spec
                 .units
@@ -138,14 +206,14 @@ impl ExecutionPlan {
 
             match operation.operation {
                 OperationType::Clone => {
-                    materialize_unit(workspace_root, unit_spec)?;
+                    materialize_unit(workspace_root, unit_spec, spec)?;
                     applied.push(format!(
                         "cloned unit '{}' into {}",
                         unit_spec.name, unit_spec.path
                     ));
                 }
                 OperationType::Configure => {
-                    materialize_unit(workspace_root, unit_spec)?;
+                    materialize_unit(workspace_root, unit_spec, spec)?;
                     applied.push(format!(
                         "configured unit '{}' at {}",
                         unit_spec.name, unit_spec.path
@@ -180,32 +248,44 @@ impl ExecutionPlan {
                 }
             }
         }
-
-        if !applied.is_empty() {
-            record_apply_state(workspace_root, &applied)?;
-        }
-
-        Ok(applied)
+        Ok(())
     }
 
     pub fn guard_for_apply(
         &self,
         workspace_root: &Path,
+        spec: &WorkspaceSpec,
         assume_yes: bool,
+        _autostash: bool,
     ) -> Result<PlanGuardReport> {
         let mut warnings = Vec::new();
+        let mut dirty_repos = Vec::new();
 
+        // Collect unit names that have planned operations
+        let mut units_with_ops: std::collections::HashSet<&str> = std::collections::HashSet::new();
         for operation in &self.operations {
-            match operation.operation {
-                OperationType::Link => {
-                    // For link operations, check the destination path inside the unit
-                    let unit_path = operation
+            units_with_ops.insert(&operation.unit_name);
+        }
+
+        for operation in &self.operations {
+            // Resolve the unit's actual path from the spec, not from parameters
+            let unit_path = spec
+                .units
+                .iter()
+                .find(|u| u.name == operation.unit_name)
+                .map(|u| u.path.as_str())
+                .unwrap_or_else(|| {
+                    operation
                         .parameters
                         .get("path")
-                        .cloned()
-                        .unwrap_or_else(|| format!("agents/{}", operation.unit_name));
+                        .map(|s| s.as_str())
+                        .unwrap_or("")
+                });
+
+            match operation.operation {
+                OperationType::Link => {
                     if let Some(dest) = operation.parameters.get("dest") {
-                        let dest_path = workspace_root.join(&unit_path).join(dest);
+                        let dest_path = workspace_root.join(unit_path).join(dest);
                         if dest_path.exists() {
                             anyhow::bail!(
                                 "refusing to apply plan: link destination already exists for unit '{}': {}",
@@ -216,13 +296,7 @@ impl ExecutionPlan {
                     }
                 }
                 _ => {
-                    let path = operation
-                        .parameters
-                        .get("path")
-                        .map(|value| workspace_root.join(value))
-                        .unwrap_or_else(|| {
-                            workspace_root.join(format!("agents/{}", operation.unit_name))
-                        });
+                    let path = workspace_root.join(unit_path);
 
                     if path.join(".git").exists() {
                         warnings.push(format!(
@@ -235,9 +309,42 @@ impl ExecutionPlan {
             }
         }
 
+        // Check for dirty repos in units that have planned operations
+        for unit in &spec.units {
+            if !units_with_ops.contains(unit.name.as_str()) {
+                continue;
+            }
+
+            let unit_root = workspace_root.join(&unit.path);
+            for repo_name in &unit.repos {
+                let repo_checkout = unit_root.join(repo_name);
+                if !repo_checkout.join(".git").exists() {
+                    continue;
+                }
+
+                if is_repo_dirty(&repo_checkout)? {
+                    warnings.push(format!(
+                        "unit '{}' repo '{}' has uncommitted changes at {}",
+                        unit.name,
+                        repo_name,
+                        repo_checkout.display()
+                    ));
+                    dirty_repos.push(DirtyRepo {
+                        unit_name: unit.name.clone(),
+                        repo_name: repo_name.clone(),
+                        repo_path: repo_checkout,
+                    });
+                }
+            }
+        }
+
+        let has_dirty_repos = !dirty_repos.is_empty();
+
         Ok(PlanGuardReport {
             warnings,
             requires_confirmation: self.operations.len() > 3 && !assume_yes,
+            has_dirty_repos,
+            dirty_repos,
         })
     }
 
@@ -364,12 +471,181 @@ fn copy_dir_recursive(src: &Path, dest: &Path) -> Result<()> {
     Ok(())
 }
 
-fn materialize_unit(workspace_root: &Path, unit: &UnitSpec) -> Result<()> {
+fn materialize_unit(workspace_root: &Path, unit: &UnitSpec, spec: &WorkspaceSpec) -> Result<()> {
     let unit_root = workspace_root.join(&unit.path);
     fs::create_dir_all(&unit_root)
         .with_context(|| format!("create unit directory {}", unit_root.display()))?;
     fs::write(unit_root.join("unit.toml"), render_unit_toml(unit))
         .with_context(|| format!("write unit metadata for '{}'", unit.name))?;
+
+    // Clone repos declared in the unit's repos list
+    for repo_name in &unit.repos {
+        let repo_spec = spec
+            .repos
+            .iter()
+            .find(|r| r.name == *repo_name)
+            .with_context(|| {
+                format!(
+                    "unit '{}' references repo '{}' which is not in the workspace spec",
+                    unit.name, repo_name
+                )
+            })?;
+
+        let clone_dest = unit_root.join(repo_name);
+        if clone_dest.exists() {
+            continue; // Already cloned, skip
+        }
+
+        let output = std::process::Command::new("git")
+            .args(["clone", &repo_spec.url])
+            .arg(&clone_dest)
+            .output()
+            .with_context(|| {
+                format!(
+                    "run git clone for repo '{}' into {}",
+                    repo_name,
+                    clone_dest.display()
+                )
+            })?;
+
+        if !output.status.success() {
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            anyhow::bail!(
+                "git clone failed for repo '{}' into {}: {}",
+                repo_name,
+                clone_dest.display(),
+                stderr.trim()
+            );
+        }
+    }
+
+    Ok(())
+}
+
+fn is_repo_dirty(repo_path: &Path) -> Result<bool> {
+    let output = std::process::Command::new("git")
+        .args(["status", "--porcelain"])
+        .current_dir(repo_path)
+        .output()
+        .with_context(|| format!("run git status in {}", repo_path.display()))?;
+
+    if !output.status.success() {
+        anyhow::bail!(
+            "git status failed in {}: {}",
+            repo_path.display(),
+            String::from_utf8_lossy(&output.stderr).trim()
+        );
+    }
+
+    Ok(!output.stdout.is_empty())
+}
+
+/// Stash dirty repos, returning the list of repos that were successfully stashed.
+fn autostash_dirty_repos(dirty_repos: &[DirtyRepo]) -> Result<Vec<DirtyRepo>> {
+    let mut stashed = Vec::new();
+
+    for dirty in dirty_repos {
+        let output = std::process::Command::new("git")
+            .args(["stash", "push", "-m", "gr2-autostash"])
+            .current_dir(&dirty.repo_path)
+            .output()
+            .with_context(|| {
+                format!(
+                    "git stash in {} for unit '{}' repo '{}'",
+                    dirty.repo_path.display(),
+                    dirty.unit_name,
+                    dirty.repo_name
+                )
+            })?;
+
+        if !output.status.success() {
+            anyhow::bail!(
+                "git stash failed in {} for unit '{}' repo '{}': {}",
+                dirty.repo_path.display(),
+                dirty.unit_name,
+                dirty.repo_name,
+                String::from_utf8_lossy(&output.stderr).trim()
+            );
+        }
+
+        stashed.push(dirty.clone());
+    }
+
+    Ok(stashed)
+}
+
+/// Pop stashes for repos that were stashed. Returns errors for repos that
+/// failed to pop (e.g. conflict), but does not abort.
+fn autostash_pop(stashed: &[DirtyRepo]) -> Vec<String> {
+    let mut errors = Vec::new();
+
+    for dirty in stashed {
+        let output = std::process::Command::new("git")
+            .args(["stash", "pop"])
+            .current_dir(&dirty.repo_path)
+            .output();
+
+        match output {
+            Ok(out) if !out.status.success() => {
+                errors.push(format!(
+                    "unit '{}' repo '{}' at {}: {}",
+                    dirty.unit_name,
+                    dirty.repo_name,
+                    dirty.repo_path.display(),
+                    String::from_utf8_lossy(&out.stderr).trim()
+                ));
+            }
+            Err(e) => {
+                errors.push(format!(
+                    "unit '{}' repo '{}' at {}: {}",
+                    dirty.unit_name,
+                    dirty.repo_name,
+                    dirty.repo_path.display(),
+                    e
+                ));
+            }
+            _ => {}
+        }
+    }
+
+    errors
+}
+
+fn record_stash_state(
+    workspace_root: &Path,
+    stashed: &[DirtyRepo],
+    pop_errors: &[String],
+) -> Result<()> {
+    let state_dir = workspace_root.join(".grip/state");
+    fs::create_dir_all(&state_dir)
+        .with_context(|| format!("create state directory {}", state_dir.display()))?;
+
+    let timestamp = chrono::Utc::now().to_rfc3339();
+    let mut content = format!("# Autostash record: {}\n\n", timestamp);
+
+    for dirty in stashed {
+        content.push_str("[[stash]]\n");
+        content.push_str(&format!("timestamp = \"{}\"\n", timestamp));
+        content.push_str(&format!("unit = \"{}\"\n", dirty.unit_name));
+        content.push_str(&format!("repo = \"{}\"\n", dirty.repo_name));
+        content.push_str(&format!("path = \"{}\"\n", dirty.repo_path.display()));
+        let restored = !pop_errors
+            .iter()
+            .any(|e| e.contains(&dirty.unit_name) && e.contains(&dirty.repo_name));
+        content.push_str(&format!("restored = {}\n\n", restored));
+    }
+
+    if !pop_errors.is_empty() {
+        content.push_str("# Pop errors (manual recovery needed):\n");
+        for err in pop_errors {
+            content.push_str(&format!("# {}\n", err));
+        }
+    }
+
+    let stash_path = state_dir.join("stash.toml");
+    fs::write(&stash_path, content)
+        .with_context(|| format!("write stash state to {}", stash_path.display()))?;
+
     Ok(())
 }
 
diff --git a/tests/cli_tests.rs b/tests/cli_tests.rs
index a005d4fc..a14d304f 100644
--- a/tests/cli_tests.rs
+++ b/tests/cli_tests.rs
@@ -983,13 +983,16 @@ fn test_gr2_plan_does_not_flag_repo_attachment_presence_as_drift() {
         .assert()
         .success();
 
+    // Use a local bare repo so the checkout can actually exist
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+
     let mut repo_add = Command::cargo_bin("gr2").unwrap();
     repo_add
         .current_dir(&workspace_root)
         .arg("repo")
         .arg("add")
         .arg("app")
-        .arg("https://github.com/synapt-dev/app.git")
+        .arg(bare.to_str().unwrap())
         .assert()
         .success();
 
@@ -1002,7 +1005,17 @@ fn test_gr2_plan_does_not_flag_repo_attachment_presence_as_drift() {
         .assert()
         .success();
 
-    let spec = r#"
+    // Simulate a fully-converged unit: clone the repo into the unit directory
+    let unit_repo_dir = workspace_root.join("agents/atlas/app");
+    std::process::Command::new("git")
+        .args(["clone"])
+        .arg(&bare)
+        .arg(&unit_repo_dir)
+        .output()
+        .unwrap();
+
+    let spec = format!(
+        r#"
 schema_version = 1
 workspace_name = "demo"
 
@@ -1012,13 +1025,15 @@ root = ".grip/cache"
 [[repos]]
 name = "app"
 path = "repos/app"
-url = "https://github.com/synapt-dev/app.git"
+url = "{}"
 
 [[units]]
 name = "atlas"
 path = "agents/atlas"
 repos = ["app"]
-"#;
+"#,
+        bare.display()
+    );
     std::fs::write(
         workspace_root.join(".grip/workspace_spec.toml"),
         spec.trim_start(),
@@ -1193,8 +1208,16 @@ fn test_gr2_apply_materializes_missing_units_from_plan() {
         .assert()
         .success();
 
-    let spec = r#"
-schema_version = 1
+    // Create a local bare repo to use as the "remote"
+    let bare_repo = temp.path().join("app-bare.git");
+    std::process::Command::new("git")
+        .args(["init", "--bare"])
+        .arg(&bare_repo)
+        .output()
+        .unwrap();
+
+    let spec = format!(
+        r#"schema_version = 1
 workspace_name = "demo"
 
 [cache]
@@ -1203,22 +1226,24 @@ root = ".grip/cache"
 [[repos]]
 name = "app"
 path = "repos/app"
-url = "https://github.com/synapt-dev/app.git"
+url = "{}"
 
 [[units]]
 name = "atlas"
 path = "agents/atlas"
 repos = ["app"]
-"#;
+"#,
+        bare_repo.display()
+    );
     std::fs::write(
         workspace_root.join(".grip/workspace_spec.toml"),
-        spec.trim_start(),
+        &spec,
     )
     .unwrap();
     std::fs::create_dir_all(workspace_root.join("repos/app")).unwrap();
     std::fs::write(
         workspace_root.join("repos/app/repo.toml"),
-        "name = \"app\"\nurl = \"https://github.com/synapt-dev/app.git\"\n",
+        format!("name = \"app\"\nurl = \"{}\"\n", bare_repo.display()),
     )
     .unwrap();
 
@@ -1235,6 +1260,9 @@ repos = ["app"]
     assert!(unit_toml.contains("name = \"atlas\""));
     assert!(unit_toml.contains("kind = \"unit\""));
     assert!(unit_toml.contains("repos = [\"app\"]"));
+
+    // Repo should be cloned into the unit workspace
+    assert!(workspace_root.join("agents/atlas/app/.git").exists());
 }
 
 #[test]
@@ -2217,3 +2245,788 @@ repos = []
         .assert()
         .success();
 }
+
+// ── gr2 apply: guard correctness + repo materialization (grip#514) ──────────
+
+/// guard_for_apply uses the unit's actual path from the spec, not the
+/// `agents/{name}` fallback, when checking for dirty checkouts.
+/// Regression test for Atlas's review note on grip#531.
+#[test]
+fn test_gr2_guard_uses_actual_unit_path_for_warnings() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    // Create a unit at a NON-default path (units/apollo, not agents/apollo)
+    // with a .git directory to trigger the dirty-checkout warning.
+    std::fs::create_dir_all(workspace_root.join("units/apollo/.git")).unwrap();
+    std::fs::write(
+        workspace_root.join("units/apollo/unit.toml"),
+        "name = \"apollo\"\nkind = \"unit\"\n",
+    )
+    .unwrap();
+
+    let spec = r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "apollo"
+path = "units/apollo"
+repos = []
+"#;
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        spec.trim_start(),
+    )
+    .unwrap();
+
+    // Plan should warn about dirty checkout at units/apollo, NOT agents/apollo.
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("units/apollo"))
+        .stdout(predicate::str::contains("uncommitted changes"));
+}
+
+/// Clone operation materializes repos declared in the unit's `repos` list
+/// by cloning them from their registered URLs.
+#[test]
+fn test_gr2_apply_clone_materializes_unit_repos() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    // Create a local bare repo to use as the "remote"
+    let bare_repo = temp.path().join("bare-repo.git");
+    std::process::Command::new("git")
+        .args(["init", "--bare"])
+        .arg(&bare_repo)
+        .output()
+        .unwrap();
+
+    // Register the repo in the workspace
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "test-repo"])
+        .arg(bare_repo.to_str().unwrap())
+        .assert()
+        .success();
+
+    // Write a spec that declares a unit referencing the repo
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "test-repo"
+path = "repos/test-repo"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["test-repo"]
+"#,
+        bare_repo.display()
+    );
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        &spec,
+    )
+    .unwrap();
+
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success();
+
+    // The unit directory and unit.toml should exist
+    assert!(workspace_root.join("agents/apollo/unit.toml").exists());
+
+    // The repo should be cloned into the unit's workspace
+    let repo_checkout = workspace_root.join("agents/apollo/test-repo");
+    assert!(
+        repo_checkout.exists(),
+        "repo should be cloned into unit workspace at agents/apollo/test-repo"
+    );
+    assert!(
+        repo_checkout.join(".git").exists(),
+        "cloned repo should have a .git directory"
+    );
+}
+
+/// Plan output shows repo clone operations for units with declared repos.
+#[test]
+fn test_gr2_plan_shows_repo_clone_for_unit() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let bare_repo = temp.path().join("bare-repo.git");
+    std::process::Command::new("git")
+        .args(["init", "--bare"])
+        .arg(&bare_repo)
+        .output()
+        .unwrap();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "test-repo"])
+        .arg(bare_repo.to_str().unwrap())
+        .assert()
+        .success();
+
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "test-repo"
+path = "repos/test-repo"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["test-repo"]
+"#,
+        bare_repo.display()
+    );
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        &spec,
+    )
+    .unwrap();
+
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("clone"))
+        .stdout(predicate::str::contains("apollo"));
+}
+
+// ── gr2 apply: autostash policy (grip#534) ────────────────────────────────────
+
+/// Helper: create a local bare repo with one committed file, suitable for
+/// cloning into unit workspaces. Returns the path to the bare repo.
+fn create_bare_repo_with_content(parent: &std::path::Path, name: &str) -> std::path::PathBuf {
+    let bare = parent.join(format!("{}.git", name));
+    std::process::Command::new("git")
+        .args(["init", "--bare"])
+        .arg(&bare)
+        .output()
+        .unwrap();
+
+    // Clone into a temp working copy, add a file, push back
+    let work = parent.join(format!("{}-work", name));
+    std::process::Command::new("git")
+        .args(["clone"])
+        .arg(&bare)
+        .arg(&work)
+        .output()
+        .unwrap();
+    std::fs::write(work.join("README.md"), "# test\n").unwrap();
+    std::process::Command::new("git")
+        .args(["add", "."])
+        .current_dir(&work)
+        .output()
+        .unwrap();
+    std::process::Command::new("git")
+        .args(["commit", "-m", "init"])
+        .current_dir(&work)
+        .output()
+        .unwrap();
+    std::process::Command::new("git")
+        .args(["push"])
+        .current_dir(&work)
+        .output()
+        .unwrap();
+
+    bare
+}
+
+/// Helper: set up a workspace with a unit that has an already-cloned repo.
+/// Returns the workspace root path.
+fn setup_workspace_with_cloned_unit(
+    temp: &TempDir,
+    bare_repo: &std::path::Path,
+) -> std::path::PathBuf {
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    // Register the repo
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "app"])
+        .arg(bare_repo.to_str().unwrap())
+        .assert()
+        .success();
+
+    // Write spec with the unit referencing the repo
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["app"]
+"#,
+        bare_repo.display()
+    );
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        &spec,
+    )
+    .unwrap();
+
+    // Run apply once to materialize the unit + clone the repo
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success();
+
+    // Verify the repo is cloned
+    assert!(workspace_root.join("agents/apollo/app/.git").exists());
+
+    workspace_root
+}
+
+/// gr2 apply should block when a unit's cloned repo has uncommitted changes
+/// and --autostash is not provided. Default must be safe: no silent discard.
+#[test]
+fn test_gr2_apply_blocks_dirty_repo_without_autostash() {
+    let temp = TempDir::new().unwrap();
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+    let workspace_root = setup_workspace_with_cloned_unit(&temp, &bare);
+
+    // Dirty the cloned repo: modify the tracked file
+    let repo_checkout = workspace_root.join("agents/apollo/app");
+    std::fs::write(repo_checkout.join("README.md"), "# modified\n").unwrap();
+
+    // Create a shared config file so we can add a link operation to the plan
+    std::fs::write(workspace_root.join("config/shared.toml"), "shared = true\n").unwrap();
+
+    // Rewrite spec to add a link (triggers a Link operation since dest doesn't exist)
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["app"]
+
+[[units.links]]
+src = "config/shared.toml"
+dest = ".config/shared.toml"
+kind = "symlink"
+"#,
+        bare.display()
+    );
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        &spec,
+    )
+    .unwrap();
+
+    // Apply without --autostash should fail because the unit's repo is dirty
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("dirty")
+            .or(predicate::str::contains("uncommitted")));
+}
+
+/// gr2 apply --autostash should preserve dirty changes by stashing before
+/// the operation and popping after.
+#[test]
+fn test_gr2_apply_autostash_preserves_dirty_changes() {
+    let temp = TempDir::new().unwrap();
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+    let workspace_root = setup_workspace_with_cloned_unit(&temp, &bare);
+
+    // Dirty the cloned repo
+    let repo_checkout = workspace_root.join("agents/apollo/app");
+    std::fs::write(repo_checkout.join("README.md"), "# modified by agent\n").unwrap();
+
+    // Add a link to trigger an operation
+    std::fs::write(workspace_root.join("config/shared.toml"), "shared = true\n").unwrap();
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["app"]
+
+[[units.links]]
+src = "config/shared.toml"
+dest = ".config/shared.toml"
+kind = "symlink"
+"#,
+        bare.display()
+    );
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        &spec,
+    )
+    .unwrap();
+
+    // Apply with --autostash should succeed
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .args(["apply", "--autostash"])
+        .assert()
+        .success();
+
+    // The dirty change should still be present after apply
+    let content = std::fs::read_to_string(repo_checkout.join("README.md")).unwrap();
+    assert!(
+        content.contains("modified by agent"),
+        "autostash should preserve the dirty change; got: {}",
+        content
+    );
+}
+
+/// gr2 plan should report actual dirty state (uncommitted changes detected)
+/// rather than just "possible uncommitted changes" based on .git existence.
+#[test]
+fn test_gr2_plan_shows_actual_dirty_state() {
+    let temp = TempDir::new().unwrap();
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+    let workspace_root = setup_workspace_with_cloned_unit(&temp, &bare);
+
+    // Dirty the cloned repo
+    let repo_checkout = workspace_root.join("agents/apollo/app");
+    std::fs::write(repo_checkout.join("README.md"), "# dirty\n").unwrap();
+
+    // Add a link to trigger an operation in the plan
+    std::fs::write(workspace_root.join("config/shared.toml"), "shared = true\n").unwrap();
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["app"]
+
+[[units.links]]
+src = "config/shared.toml"
+dest = ".config/shared.toml"
+kind = "symlink"
+"#,
+        bare.display()
+    );
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        &spec,
+    )
+    .unwrap();
+
+    // Plan should report the dirty state with specifics
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("uncommitted changes"));
+}
+
+/// When --autostash is used, gr2 apply should record the stash action
+/// in .grip/state for recovery and auditability.
+#[test]
+fn test_gr2_autostash_records_state() {
+    let temp = TempDir::new().unwrap();
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+    let workspace_root = setup_workspace_with_cloned_unit(&temp, &bare);
+
+    // Dirty the cloned repo
+    let repo_checkout = workspace_root.join("agents/apollo/app");
+    std::fs::write(repo_checkout.join("README.md"), "# dirty for stash\n").unwrap();
+
+    // Add a link to trigger an operation
+    std::fs::write(workspace_root.join("config/shared.toml"), "shared = true\n").unwrap();
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["app"]
+
+[[units.links]]
+src = "config/shared.toml"
+dest = ".config/shared.toml"
+kind = "symlink"
+"#,
+        bare.display()
+    );
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        &spec,
+    )
+    .unwrap();
+
+    // Apply with --autostash
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .args(["apply", "--autostash"])
+        .assert()
+        .success();
+
+    // Stash state should be recorded
+    let stash_state = workspace_root.join(".grip/state/stash.toml");
+    assert!(
+        stash_state.exists(),
+        "autostash should record state in .grip/state/stash.toml"
+    );
+    let content = std::fs::read_to_string(&stash_state).unwrap();
+    assert!(
+        content.contains("apollo") && content.contains("app"),
+        "stash state should reference the unit and repo; got: {}",
+        content
+    );
+}
+
+/// gr2 apply should succeed without --autostash when repos are clean
+/// (no uncommitted changes). Clean workspaces need no special handling.
+#[test]
+fn test_gr2_apply_clean_repo_no_autostash_needed() {
+    let temp = TempDir::new().unwrap();
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+    let workspace_root = setup_workspace_with_cloned_unit(&temp, &bare);
+
+    // Don't dirty anything — the repo is clean
+
+    // Apply without --autostash should succeed on clean workspace
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success();
+}
+
+// ── gr2 apply: partial unit convergence (grip#539) ────────────────────────────
+
+/// When a unit exists (unit.toml present, path correct) but a declared repo
+/// has not been cloned, plan should emit an operation to converge it.
+#[test]
+fn test_gr2_plan_detects_missing_repo_in_existing_unit() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let bare = create_bare_repo_with_content(temp.path(), "myrepo");
+
+    // Register the repo
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "myrepo"])
+        .arg(bare.to_str().unwrap())
+        .assert()
+        .success();
+
+    // Manually create the unit directory with unit.toml (simulating a
+    // partially-materialized unit where the unit exists but repos aren't cloned)
+    let unit_root = workspace_root.join("agents/apollo");
+    std::fs::create_dir_all(&unit_root).unwrap();
+    std::fs::write(
+        unit_root.join("unit.toml"),
+        "name = \"apollo\"\nkind = \"unit\"\nrepos = [\"myrepo\"]\n",
+    )
+    .unwrap();
+
+    // Write a spec declaring the unit with the repo
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "myrepo"
+path = "repos/myrepo"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["myrepo"]
+"#,
+        bare.display()
+    );
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        &spec,
+    )
+    .unwrap();
+
+    // Plan should detect the missing repo and emit a non-empty plan
+    let mut plan = Command::cargo_bin("gr2").unwrap();
+    plan.current_dir(&workspace_root)
+        .arg("plan")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("apollo"))
+        .stdout(predicate::str::contains("no changes required").not());
+}
+
+/// Apply should clone missing repos into an existing unit, converging it
+/// to match the declared spec.
+#[test]
+fn test_gr2_apply_converges_missing_repo_in_existing_unit() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let bare = create_bare_repo_with_content(temp.path(), "myrepo");
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "myrepo"])
+        .arg(bare.to_str().unwrap())
+        .assert()
+        .success();
+
+    // Create partially-materialized unit (unit.toml exists, repo not cloned)
+    let unit_root = workspace_root.join("agents/apollo");
+    std::fs::create_dir_all(&unit_root).unwrap();
+    std::fs::write(
+        unit_root.join("unit.toml"),
+        "name = \"apollo\"\nkind = \"unit\"\nrepos = [\"myrepo\"]\n",
+    )
+    .unwrap();
+
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "myrepo"
+path = "repos/myrepo"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["myrepo"]
+"#,
+        bare.display()
+    );
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        &spec,
+    )
+    .unwrap();
+
+    // Apply should converge: clone the missing repo
+    let mut apply = Command::cargo_bin("gr2").unwrap();
+    apply
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success();
+
+    // Verify the repo was cloned into the unit
+    let repo_checkout = unit_root.join("myrepo");
+    assert!(
+        repo_checkout.join(".git").exists(),
+        "missing repo should be cloned into existing unit at agents/apollo/myrepo"
+    );
+}
+
+/// Apply is idempotent: running on a fully-converged unit (repos already
+/// cloned) should produce "no changes required".
+#[test]
+fn test_gr2_apply_idempotent_after_repo_convergence() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let bare = create_bare_repo_with_content(temp.path(), "myrepo");
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "myrepo"])
+        .arg(bare.to_str().unwrap())
+        .assert()
+        .success();
+
+    // Create partially-materialized unit
+    let unit_root = workspace_root.join("agents/apollo");
+    std::fs::create_dir_all(&unit_root).unwrap();
+    std::fs::write(
+        unit_root.join("unit.toml"),
+        "name = \"apollo\"\nkind = \"unit\"\nrepos = [\"myrepo\"]\n",
+    )
+    .unwrap();
+
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "myrepo"
+path = "repos/myrepo"
+url = "{}"
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+repos = ["myrepo"]
+"#,
+        bare.display()
+    );
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        &spec,
+    )
+    .unwrap();
+
+    // First apply converges
+    let mut first = Command::cargo_bin("gr2").unwrap();
+    first
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success();
+
+    // Second apply should be a no-op
+    let mut second = Command::cargo_bin("gr2").unwrap();
+    second
+        .current_dir(&workspace_root)
+        .arg("apply")
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("no changes required"));
+}

From 35278a9447c7d0f284c22d8ceb3bf0993175fafa Mon Sep 17 00:00:00 2001
From: Layne Penney <dev@layne.pro>
Date: Sat, 11 Apr 2026 23:37:55 -0500
Subject: [PATCH 10/15] docs: design gr2 repo maintenance and lanes (#543)

---
 docs/AUDIT-gr2-current-surface-vs-rulebook.md | 341 +++++++++
 docs/PLAN-gr2-needs-and-criteria.md           | 438 ++++++++++++
 docs/PLAN-gr2-repo-maintenance-and-lanes.md   | 654 ++++++++++++++++++
 gr2/prototypes/README.md                      | 100 +++
 gr2/prototypes/lane_workspace_prototype.py    | 235 +++++++
 gr2/prototypes/repo_maintenance_prototype.py  | 443 ++++++++++++
 6 files changed, 2211 insertions(+)
 create mode 100644 docs/AUDIT-gr2-current-surface-vs-rulebook.md
 create mode 100644 docs/PLAN-gr2-needs-and-criteria.md
 create mode 100644 docs/PLAN-gr2-repo-maintenance-and-lanes.md
 create mode 100644 gr2/prototypes/README.md
 create mode 100644 gr2/prototypes/lane_workspace_prototype.py
 create mode 100644 gr2/prototypes/repo_maintenance_prototype.py

diff --git a/docs/AUDIT-gr2-current-surface-vs-rulebook.md b/docs/AUDIT-gr2-current-surface-vs-rulebook.md
new file mode 100644
index 00000000..076b72c7
--- /dev/null
+++ b/docs/AUDIT-gr2-current-surface-vs-rulebook.md
@@ -0,0 +1,341 @@
+# Audit: Current gr2 Surface vs Rulebook
+
+## Scope
+
+This audit compares the current `gr2` implementation surface against:
+
+- `docs/PLAN-gr2-needs-and-criteria.md`
+- `docs/PLAN-gr2-repo-maintenance-and-lanes.md`
+
+Implementation reviewed:
+
+- `gr2/src/args.rs`
+- `gr2/src/dispatch.rs`
+- `gr2/src/plan.rs`
+- `gr2/src/spec.rs`
+
+## Executive Summary
+
+Current `gr2` is a useful structural bootstrap, not yet a first-class workspace.
+
+What it does reasonably well:
+
+- initialize a team-workspace skeleton
+- register repos and units
+- emit a basic workspace spec
+- plan and apply structural convergence
+- keep some repo mutation out of plain `apply`
+
+What it does not yet do:
+
+- named lanes
+- shared/private context
+- lane-aware execution
+- explicit repo-maintenance surfaces
+- review-lane isolation
+- durable recovery/state strong enough for multi-agent use
+
+Bottom line:
+
+- as a structural foundation: promising
+- as a human + multi-agent operating surface: incomplete
+
+## Criteria Assessment
+
+### 1. Structural and Repo-State Separation
+
+Status: `Partial`
+
+Strength:
+
+- the current model does separate `plan/apply` from most explicit branch/sync behavior
+
+Weakness:
+
+- `materialize_unit()` clones repos directly during `apply`, which is acceptable as structural convergence
+- but there is still no explicit repo-maintenance read/write surface above it
+- `Apply --autostash` exists, but the user still lacks a separate repo-status model to understand when it would matter
+
+Assessment:
+
+The safety boundary is directionally right, but incomplete because repo-state
+inspection is still missing.
+
+### 2. Named Multi-Repo Lanes
+
+Status: `Fail`
+
+Current surface:
+
+- no lane commands
+- no lane metadata
+- no lane types
+- no lane-local branch/PR/context model
+
+Assessment:
+
+This is the largest missing capability relative to the rulebook.
+
+### 3. Cheap Parallelism
+
+Status: `Partial`
+
+Strength:
+
+- workspace topology is moving toward clone-backed isolation rather than shared worktrees
+
+Weakness:
+
+- cache exists only as a path in spec; there is no active lane/cache model
+- no lane creation surface
+- no disposable review lane concept
+
+Assessment:
+
+The intended direction is there, but the system cannot yet prove cheap
+parallelism in practice.
+
+### 4. Shared and Private Context
+
+Status: `Fail`
+
+Current surface:
+
+- `config/` exists at init time
+- no context model in spec or metadata
+- no unit-private context roots
+- no lane-local context inheritance
+
+Assessment:
+
+This is entirely absent from current `gr2`.
+
+### 5. Lane-Aware Execution
+
+Status: `Fail`
+
+Current surface:
+
+- no `exec` surface
+- no lane scoping
+- no repo-subset execution model
+
+Assessment:
+
+The current implementation offers no first-class answer for build/test/run.
+
+### 6. Dirty Work Preservation
+
+Status: `Partial`
+
+Strength:
+
+- current branch includes explicit dirty repo detection inside unit repo checkouts
+- autostash/preservation hooks exist in `plan.rs`
+
+Weakness:
+
+- preservation is apply-time only
+- no separate repo-maintenance command family
+- no user-facing recovery/status surface yet
+
+Assessment:
+
+This is meaningful progress, but still not a complete preservation story.
+
+### 7. PR and Review Isolation
+
+Status: `Fail`
+
+Current surface:
+
+- no `checkout-pr`
+- no review lanes
+- no durable PR associations
+
+Assessment:
+
+Review remains external to the workspace model.
+
+### 8. Cross-Repo Feature Coherence
+
+Status: `Fail`
+
+Current surface:
+
+- units can list repos
+- no branch map
+- no PR grouping
+- no expected verification set
+
+Assessment:
+
+The workspace knows repo membership, but not feature coherence.
+
+### 9. Deterministic Status Surfaces
+
+Status: `Partial`
+
+Strength:
+
+- `plan` is deterministic for structural operations
+- `spec show/validate` exist
+
+Weakness:
+
+- no JSON/status model for repo state
+- no lane status
+- no execution status
+- no PR-linkage status
+
+Assessment:
+
+Structural visibility exists. Operational visibility does not.
+
+### 10. Multi-Repo Scratchpads
+
+Status: `Fail`
+
+Current surface:
+
+- only one implicit working context per unit path
+- no multiple scratchpads
+- no review or repro lanes
+
+Assessment:
+
+Current `gr2` cannot yet support the core workflow-switching use case.
+
+## Surface-Specific Findings
+
+### `args.rs`
+
+What exists:
+
+- `init`
+- `doctor`
+- `team`
+- `repo`
+- `unit`
+- `spec`
+- `plan`
+- `apply`
+
+Finding:
+
+The command surface is still structural/registry-heavy. There is no runtime
+surface for:
+
+- repo maintenance
+- lane management
+- execution
+- context
+
+### `dispatch.rs`
+
+Finding 1:
+
+`TeamCommands` and `UnitCommands` both materialize directories under `agents/`,
+but they represent different concepts (`agent.toml` vs `unit.toml`) without a
+clear higher-level model.
+
+Why this matters:
+
+- the rulebook needs unit home, lanes, context, and execution roots
+- the current split is likely to confuse future implementation if not unified
+
+Finding 2:
+
+`RepoCommands::Add` creates metadata directories immediately under `repos/`.
+That is acceptable for registration, but it mixes registry behavior with
+materialized path creation before a stronger lane/cache model exists.
+
+### `spec.rs`
+
+Finding 1:
+
+`WorkspaceSpec v1` is intentionally narrow, which is good.
+
+Finding 2:
+
+`WorkspaceSpec::from_workspace()` does not recover the richer intent needed for
+future lanes:
+
+- no branch map
+- no lane state
+- no context roots
+- no execution defaults
+
+Finding 3:
+
+`read_registered_units()` reconstructs units from directory presence and
+currently initializes `repos` as empty.
+
+Why this matters:
+
+- round-tripping from the filesystem loses intent
+- that is acceptable for bootstrap, but not for a durable lane workspace
+
+### `plan.rs`
+
+Finding 1:
+
+The current branch improved real gaps:
+
+- partially materialized unit repos are now detected
+- link planning exists
+- dirty nested repos are detected
+
+Finding 2:
+
+`materialize_unit()` clones repos directly into the unit path.
+
+This is acceptable for now, but it bypasses the future cache/lane model and
+will need refactoring once lanes become first-class.
+
+Finding 3:
+
+Dirty repo detection only considers repos inside units with planned operations.
+
+That is a reasonable apply guard, but it is not the same as a general
+repo-maintenance status surface.
+
+## Practical Gaps to Fix First
+
+### P0
+
+- `gr2 repo status`
+- lane metadata format
+
+These are the minimum requirements to make repo-state and lane-state legible.
+
+### P1
+
+- lane create/status/enter/remove
+- lane-aware execution
+
+These make the workspace usable for actual task switching.
+
+### P2
+
+- `lane checkout-pr`
+- explicit repo sync/pull/fetch surfaces
+
+These complete the review and maintenance story.
+
+## Conclusion
+
+Current `gr2` passes as a structural foundation and fails as a complete
+human/agent workspace.
+
+That is not a criticism of the implementation direction. It is the correct
+reading of where the surface is today.
+
+The good news is that the missing pieces are now sharply defined:
+
+- visibility
+- lane metadata
+- lane-aware execution
+- isolated review/scratch workflows
+
+Those are exactly the right next layers to build.
diff --git a/docs/PLAN-gr2-needs-and-criteria.md b/docs/PLAN-gr2-needs-and-criteria.md
new file mode 100644
index 00000000..270b2a60
--- /dev/null
+++ b/docs/PLAN-gr2-needs-and-criteria.md
@@ -0,0 +1,438 @@
+# gr2 Needs and Criteria Rulebook
+
+## Purpose
+
+This document is the comprehensive criteria set for a first-class `gr2`
+workspace that must work for:
+
+- a solo human working across many repos
+- multiple agents working in parallel
+- mixed human + agent teams
+
+It is not a feature wishlist. It is the rulebook for what the workspace must
+be able to do without unsafe workarounds.
+
+## Primary Design Principle
+
+The workspace unit is not a single repo checkout.
+
+The workspace unit is:
+
+- a named lane
+- a selected repo set
+- a branch/PR context
+- a context bundle
+- an execution surface
+
+If `gr2` gets that right, humans and agents can work safely in parallel.
+If it gets that wrong, users will fall back to ad hoc worktrees, raw git, and
+hidden state.
+
+## User Modes
+
+`gr2` must support all of these without changing its core model.
+
+### Solo Human
+
+The user needs to:
+
+- work across multiple repos as one feature
+- review another PR without disturbing that feature
+- start a second feature while the first waits on review
+- run build/test/verify for the active multi-repo lane
+
+### Single Agent
+
+The agent needs to:
+
+- discover the correct workspace context quickly
+- understand which repos matter for the task
+- branch and execute commands without guessing
+- report deterministic status
+- avoid clobbering unrelated work
+
+### Multi-Agent Team
+
+The team needs to:
+
+- isolate active work per unit
+- share durable context where appropriate
+- preserve private context where appropriate
+- coordinate across linked PRs and sprint lanes
+- switch between tasks without contaminating each other's state
+
+## Hard Requirements
+
+### 1. Structural and Repo-State Separation
+
+`gr2 apply` must remain structural only.
+
+It may:
+
+- create directories
+- materialize missing repos
+- attach repos into units
+- converge partially-materialized lanes
+- write metadata
+
+It must not silently:
+
+- pull
+- merge
+- rebase
+- switch active branches
+- discard or obscure dirty work
+
+This is the most important safety boundary in the system.
+
+### 2. Named Multi-Repo Lanes
+
+The system must support named lanes as first-class objects.
+
+Each lane must support:
+
+- a repo set
+- a branch map
+- PR associations
+- context roots
+- execution defaults
+- a lane type
+
+Required lane types:
+
+- `home`
+- `feature`
+- `review`
+- `scratch`
+
+### 3. Cheap Parallelism
+
+Lane creation must be cheap enough that users do not avoid it.
+
+That implies:
+
+- shared cache for repo sources
+- selective lane repo membership
+- fast materialization from cache
+- disposable review lanes
+
+If lane creation is slow or expensive, users will bypass the model.
+
+### 4. Shared and Private Context
+
+The workspace must support two context scopes:
+
+- shared workspace context
+- unit-private context
+
+Shared context must be durable and visible to all relevant workers.
+Private context must not be treated as common workspace state.
+
+Lane context should inherit both:
+
+- shared workspace context
+- unit-private context
+- optional lane-local additions
+
+### 5. Lane-Aware Execution
+
+The workspace must provide lane-aware execution for:
+
+- build
+- test
+- lint
+- run
+- verify
+
+Execution must be scoped by:
+
+- lane
+- repo selection
+- order/parallelism policy
+- fail-fast or collect-all policy
+
+If execution remains global, the lane model is incomplete.
+
+### 6. Dirty Work Preservation
+
+The system must never silently discard local modifications.
+
+Required behaviors:
+
+- detect dirty work explicitly
+- block by default
+- allow explicit preservation mode
+- log preservation/recovery actions
+- surface failed restore clearly
+
+Autostash is acceptable only as an explicit preservation mechanism.
+
+### 7. PR and Review Isolation
+
+Users must be able to check out a PR without disturbing active feature work.
+
+That means:
+
+- PR checkout creates or updates a review lane
+- review lanes are disposable
+- review lanes can run their own commands
+- review lanes do not mutate the current feature lane
+
+### 8. Cross-Repo Feature Coherence
+
+A cross-repo feature must be representable as one lane record, not merely
+several repos that happen to share a branch name.
+
+The lane must know:
+
+- included repos
+- per-repo branch intent
+- associated PRs
+- expected verification commands
+
+### 9. Deterministic Status Surfaces
+
+Agents and humans need trustworthy read surfaces.
+
+`gr2` must provide explicit status views for:
+
+- workspace structural drift
+- repo sync drift
+- lane metadata
+- dirty state
+- execution status
+- PR linkage
+
+These should be machine-readable as well as human-readable.
+
+### 10. Multi-Repo Scratchpads
+
+The system must support two or more temporary scratchpads simultaneously.
+
+Examples:
+
+- a feature lane
+- a review lane
+- a reproduction lane
+- a release lane
+
+This is not optional convenience. It is necessary for real workflow switching.
+
+## Command-Surface Criteria
+
+### Spec Surface
+
+The user must be able to inspect and validate workspace intent without mutating
+repo state.
+
+Required surfaces:
+
+- `gr2 spec show`
+- `gr2 spec validate`
+- later: `gr2 spec diff`, `gr2 spec explain`
+
+### Structural Surface
+
+The user must be able to preview and apply structural workspace changes.
+
+Required surfaces:
+
+- `gr2 plan`
+- `gr2 apply`
+
+### Repo-Maintenance Surface
+
+The user must be able to inspect and update repo state explicitly.
+
+Required surfaces:
+
+- `gr2 repo status`
+- `gr2 repo fetch`
+- `gr2 repo sync`
+- `gr2 repo checkout`
+
+### Lane Surface
+
+The user must be able to manage lanes directly.
+
+Required surfaces:
+
+- `gr2 lane list`
+- `gr2 lane create`
+- `gr2 lane status`
+- `gr2 lane enter`
+- `gr2 lane remove`
+- `gr2 lane branch`
+- `gr2 lane checkout-pr`
+
+### Execution Surface
+
+The user must be able to run multi-repo commands against a lane.
+
+Required surfaces:
+
+- `gr2 exec status`
+- `gr2 exec run`
+- `gr2 exec test`
+- `gr2 exec build`
+
+### Context Surface
+
+The user must be able to inspect and manage effective context.
+
+Required surfaces:
+
+- `gr2 context show`
+- `gr2 context shared edit`
+- `gr2 context unit edit`
+
+## Metadata Criteria
+
+### Workspace Metadata
+
+The workspace must persist:
+
+- workspace identity
+- spec version
+- cache location
+- repo registry
+- unit registry
+
+### Lane Metadata
+
+Every lane must persist:
+
+- lane id
+- lane name
+- owner unit
+- lane type
+- included repos
+- branch map
+- PR associations
+- creation source
+- context roots
+- execution defaults
+- recovery state
+
+### Recovery Metadata
+
+The workspace must persist enough state to explain and recover from:
+
+- autostash actions
+- failed restore
+- interrupted sync/apply
+- partially materialized lanes
+
+## Agent-Specific Criteria
+
+### Discoverability
+
+An agent entering the workspace must be able to determine:
+
+- what lane it is in
+- what repos belong to that lane
+- what commands are relevant
+- what shared context applies
+- what private context applies
+
+without scraping ambiguous terminal output.
+
+### Isolation
+
+An agent must not need to infer which directories are safe to touch.
+
+The workspace structure should make it obvious:
+
+- shared context
+- private unit roots
+- lane-local checkouts
+
+### Deterministic Automation
+
+An agent must not have to guess whether:
+
+- a merge succeeded
+- a lane switched correctly
+- a repo is safe to update
+- a command should run in all repos or only some repos
+
+This implies strong status and JSON-capable output surfaces.
+
+## Human-Specific Criteria
+
+### Low Ceremony
+
+Humans should not need to think in terms of internal metadata to do common work.
+
+The happy path should feel like:
+
+- create lane
+- switch into lane
+- branch it
+- run tests
+- open PR
+- switch to another lane
+
+### Recoverability
+
+When something goes wrong, the user must be able to answer:
+
+- what lane am I in
+- what repos are dirty
+- what did the tool change
+- where is my preserved work
+- how do I get back to the prior state
+
+## Criteria for Success
+
+The design is successful if a user can do all of the following without raw git
+or manual directory gymnastics:
+
+1. Start a cross-repo feature in three repos.
+2. Open linked PRs for that feature.
+3. Leave the feature intact while it waits on review.
+4. Check out another PR in a disposable review lane.
+5. Start a second feature in a different lane.
+6. Run build/test only for the correct lane and repo set.
+7. Preserve dirty work safely while switching or syncing.
+8. Return to the original feature lane and continue editing.
+9. Do the same with two or more agents working simultaneously.
+
+## Failure Criteria
+
+The design has failed if users still need to rely on:
+
+- ad hoc raw git worktrees across multiple repos
+- hidden global sync behavior
+- ambiguous context files
+- manual stash/recovery folklore
+- guessing which repo set a command should operate on
+- chat memory instead of workspace state
+
+## Implementation Priority
+
+Build against this criteria set in this order:
+
+1. narrow `apply`
+2. `gr2 repo status`
+3. lane metadata
+4. `gr2 lane create/status/enter/remove`
+5. `gr2 exec` lane-aware command surface
+6. `gr2 lane checkout-pr`
+7. `gr2 repo sync` with explicit preservation policy
+8. richer context tooling
+
+## Bottom Line
+
+The bar for `gr2` is not "better multi-repo git commands."
+
+The bar is:
+
+- a trustworthy multi-repo operating system for humans and agents
+- explicit context
+- explicit execution
+- explicit parallel work surfaces
+- explicit recovery
+
+That is the criteria rulebook. Any `gr2` design or implementation should be
+judged against it.
diff --git a/docs/PLAN-gr2-repo-maintenance-and-lanes.md b/docs/PLAN-gr2-repo-maintenance-and-lanes.md
new file mode 100644
index 00000000..87b3aba9
--- /dev/null
+++ b/docs/PLAN-gr2-repo-maintenance-and-lanes.md
@@ -0,0 +1,654 @@
+# gr2 Repo Maintenance and Lanes
+
+## Problem
+
+`gr` taught us two useful things:
+
+1. multi-repo work is real, not edge-case behavior
+2. hiding repo coordination behind one broad `sync` surface creates avoidable confusion
+
+The current pain points are consistent:
+
+- manifest intent, file projection, and repo mutation are too entangled
+- switching from one feature to another is too global
+- reviewing a PR while keeping local feature work alive is awkward
+- agents need more isolation than shared worktrees provide
+- humans need less ceremony than a full fresh workspace for every task
+
+We need `gr2` to be a first-class multi-repo workspace for both:
+
+- a solo human working across several repos
+- multiple agents working in parallel without stepping on each other
+
+The workspace model needs to support:
+
+- one feature spanning three repos
+- a second feature starting while the first is in review
+- checking out a PR without disturbing ongoing work
+- keeping repo state explicit and recoverable
+- preserving dirty local work by default
+- shared team context plus unit-specific private context
+- multi-repo build, test, and command execution scoped to a lane
+
+## Design Goals
+
+- make workspace intent explicit
+- make repo state transitions explicit
+- make parallel work cheap
+- make review and temporary work cheap
+- preserve local modifications safely
+- keep agent and human behavior on the same primitives
+- avoid hidden pull/merge/rebase side effects
+- make shared context and unit-private context explicit
+- make multi-repo execution lane-aware
+
+## Non-Goals
+
+- `gr2 apply` is not a global "make it all right somehow" button
+- `WorkspaceSpec v1` is not the place for full org/policy/runtime state
+- shared repos and active feature sandboxes should not be conflated
+
+## Core Split
+
+`gr2` should separate three concerns.
+
+### 1. Workspace Intent
+
+`WorkspaceSpec` declares:
+
+- which repos exist
+- where they live
+- which units use which repos
+- basic workspace topology
+
+This is the durable declarative layer.
+
+### 2. Structural Convergence
+
+`gr2 apply` should do only structural work:
+
+- create missing directories
+- materialize missing repo checkouts
+- attach repos into units
+- converge partially materialized units
+- write unit metadata
+
+It should not silently:
+
+- pull from remotes
+- merge branches
+- rebase local work
+- switch active branches unexpectedly
+
+### 3. Repo Maintenance
+
+Repo maintenance should be an explicit surface above structural apply:
+
+- fetch
+- fast-forward
+- branch correction
+- PR checkout
+- autostash-based preservation
+- divergence handling
+
+That should become a separate command family, not hidden inside `apply`.
+
+## Proposed Workspace Model
+
+The workspace should have three layers:
+
+```text
+<workspace>/
+├── .grip/
+│   ├── workspace_spec.toml
+│   ├── state/
+│   └── cache/
+│       └── repos/
+├── config/
+├── repos/
+│   └── <shared checkouts>
+├── agents/
+│   └── <unit>/
+│       ├── unit.toml
+│       ├── home/
+│       └── lanes/
+│           ├── <lane-a>/
+│           │   └── repos/
+│           └── <lane-b>/
+│               └── repos/
+└── scratch/
+    └── <review-or-throwaway-lanes>
+```
+
+### Shared Cache
+
+`.grip/cache/repos/` stores reusable repo sources.
+
+This is the acceleration layer:
+
+- clone once
+- materialize many
+- cheap temporary sandboxes
+
+### Shared Repos
+
+`repos/` is for shared baseline or stable workspace-level repos.
+
+These are not where active feature work should live by default.
+
+### Unit Home
+
+`agents/<unit>/home/` is the stable home lane for a person or agent.
+
+This is where "my normal work" lives when not split into a feature lane.
+
+### Lanes
+
+A lane is a multi-repo scratchpad.
+
+A lane contains:
+
+- a selected set of repos
+- a branch map
+- local dirtiness state
+- lane-local checkout paths
+- review metadata if it came from a PR
+- shared and private context references
+- execution defaults for build/test/run commands
+
+This is the multi-repo equivalent of a worktree, but not tied to git's
+single-repo worktree mechanism.
+
+## Context Model
+
+The workspace needs two context scopes.
+
+### Shared Context
+
+Shared context is visible to everyone in the workspace:
+
+- workspace instructions
+- shared prompts
+- release plan
+- shared notes and decisions
+- cross-repo task state
+
+This should live in stable workspace-managed locations such as:
+
+- `config/`
+- `.grip/context/shared/`
+
+This is the context a human or agent should inherit by default when entering
+the workspace or a lane.
+
+### Unit-Private Context
+
+Each unit needs private context that is not treated as shared scratch space:
+
+- local notes
+- pending ideas
+- temporary debugging context
+- agent-specific reminders
+- local execution state
+
+This should live under the unit root, not in shared workspace state:
+
+- `agents/<unit>/home/context/`
+- `agents/<unit>/lanes/<lane>/context/`
+
+The rule should be:
+
+- shared context is workspace-owned
+- private context is unit-owned
+- lane context inherits both, but may add lane-local notes
+
+That gives us the right behavior for both humans and agents:
+
+- the team can share durable operational context
+- each worker can keep private working memory without trampling others
+
+## Execution Model
+
+The workspace also needs a first-class multi-repo execution surface.
+
+Users need to run:
+
+- builds
+- tests
+- linters
+- migrations
+- verification commands
+
+across a selected repo set, inside a selected lane.
+
+### Why This Matters
+
+If lane management exists but execution stays global, users will still be
+forced back into the old failure mode:
+
+- wrong branch
+- wrong checkout
+- wrong repo subset
+- wrong temporary context
+
+So command execution must be lane-aware.
+
+### Proposed Execution Commands
+
+```bash
+gr2 exec status
+gr2 exec run <command>
+gr2 exec test
+gr2 exec build
+```
+
+Each execution should be scoped by:
+
+- lane
+- repo selection
+- execution order or parallelism policy
+- fail-fast vs collect-all behavior
+
+Examples:
+
+```bash
+gr2 exec test --lane feat-auth
+gr2 exec run --lane review-541 --repo grip 'cargo test'
+gr2 exec build --lane feat-billing --repos app,api
+```
+
+### Execution Metadata
+
+Each lane should be able to record:
+
+- default repo set
+- default working directory per repo
+- common scripts or commands
+- last known successful verification set
+
+This should not be a hidden shell convention. It should be lane metadata.
+
+## Lane Metadata
+
+The lane record should be explicit and durable.
+
+At minimum it should contain:
+
+- lane name
+- owner unit
+- lane type: `home`, `feature`, `review`, `scratch`
+- included repos
+- branch map per repo
+- PR associations
+- context roots
+- execution defaults
+- creation source
+- dirty/autostash recovery state
+
+That metadata is what makes lane switching trustworthy.
+
+Without it, `gr2` would just be managing directories and hoping the user
+remembers what each one is for.
+
+## Why Lanes Instead of Plain Worktrees
+
+Git worktrees are repo-local. Our problem is workspace-wide.
+
+One feature often means:
+
+- repo A on `feat/x`
+- repo B on `feat/x`
+- repo C on `feat/x`
+
+and the user wants that set to behave as one working context.
+
+So the first-class unit is not "a checkout of one repo".
+It is:
+
+- one named lane
+- one set of repos
+- one branch intent
+- one local review/edit surface
+
+## User Flows
+
+### 1. Solo Human, One Cross-Repo Feature
+
+User wants to work on a feature spanning `app`, `api`, and `shared`.
+
+```bash
+gr2 lane create feat-auth --repos app,api,shared
+gr2 lane branch feat-auth --name feat/auth
+gr2 lane enter feat-auth
+```
+
+Now the user has one isolated multi-repo context.
+
+### 2. Start Another Feature While the First Is in Review
+
+The first feature is open in PR and waiting on review.
+User wants to start a second feature without disturbing it.
+
+```bash
+gr2 lane create feat-billing --repos app,api
+gr2 lane branch feat-billing --name feat/billing
+gr2 lane enter feat-billing
+```
+
+The first lane stays intact. The second lane starts from cache-backed clones.
+
+### 3. Check Out a PR While Keeping Your Own Work
+
+User needs to review or patch someone else's PR while keeping their own lane.
+
+```bash
+gr2 lane checkout-pr review-541 --repo grip --pr 541
+gr2 lane enter review-541
+```
+
+This should create a separate review lane. It must not disturb the user's
+feature lane or home lane.
+
+### 4. Agent Parallelism
+
+Atlas is working on `feat-a`. Apollo is working on `feat-b`.
+Both need isolated multi-repo state.
+
+They should each have:
+
+- private unit roots
+- private lanes
+- shared cache
+
+That gives:
+
+- low duplication where safe
+- no checkout collisions
+- no "another agent changed my branch" failures
+
+### 5. Temporary Scratchpads
+
+Yes, we should explicitly support two or more temporary scratchpads.
+
+Examples:
+
+- a feature lane
+- a review lane
+- a reproduction lane for a bug
+
+Those should all be first-class, cheap, and disposable.
+
+## Repo Maintenance Model
+
+The prototype suggests this action taxonomy:
+
+- `clone_missing`
+- `block_path_conflict`
+- `block_dirty`
+- `autostash_then_sync`
+- `checkout_branch`
+- `fast_forward`
+- `manual_sync`
+- `no_change`
+
+This is the right design direction because it makes repo state legible.
+
+### Shared Repo Defaults
+
+Shared repos can default to stricter automation:
+
+- fetch allowed
+- fast-forward allowed when clean
+- branch correction allowed when no local work exists
+
+### Lane Repo Defaults
+
+Lane repos should be more conservative:
+
+- no automatic branch movement
+- no automatic merge/rebase
+- stop when dirty unless explicit preservation is requested
+
+This is the right default because lanes are where active work lives.
+
+## Proposed Commands
+
+### Structural
+
+```bash
+gr2 spec show
+gr2 spec validate
+gr2 plan
+gr2 apply
+```
+
+### Repo Maintenance
+
+```bash
+gr2 repo status
+gr2 repo sync
+gr2 repo fetch
+gr2 repo pull
+gr2 repo checkout
+```
+
+### Lane Management
+
+```bash
+gr2 lane list
+gr2 lane create <name>
+gr2 lane enter <name>
+gr2 lane leave
+gr2 lane remove <name>
+gr2 lane branch <lane> --name <branch>
+gr2 lane checkout-pr <lane> --repo <repo> --pr <num>
+gr2 lane status [<lane>]
+```
+
+### Context
+
+```bash
+gr2 context show [--lane <lane>]
+gr2 context shared edit
+gr2 context unit edit [--lane <lane>]
+```
+
+### Execution
+
+```bash
+gr2 exec status [--lane <lane>]
+gr2 exec run --lane <lane> [--repo <repo>] <command>
+gr2 exec test --lane <lane>
+gr2 exec build --lane <lane>
+```
+
+## Branch and PR Behavior
+
+### Branch Switching
+
+Branch switching should be lane-local, not workspace-global.
+
+If the user is in lane `feat-auth`, then:
+
+```bash
+gr2 lane branch feat-auth --name feat/auth
+```
+
+means:
+
+- create or check out `feat/auth` across the repos in that lane
+- do not disturb repos outside that lane
+
+### PR Checkout
+
+Checking out a PR should create or update a review lane.
+
+That review lane should record:
+
+- source repo
+- PR number
+- branch/ref used
+- whether it is disposable
+
+### Linked Cross-Repo Features
+
+A feature spanning three repos should have one lane record that knows:
+
+- which repos are included
+- what branch each repo should be on
+- which PRs belong to that lane
+- what shared and private context applies there
+- what the expected verification commands are
+
+That is the real unit of work. Not "three separate branches that happen to
+share a name."
+
+## Relationship to `gr`
+
+`gr` already has the right lessons:
+
+- linked PRs matter
+- synchronized branch flows matter
+- atomic merge intent matters
+- manifest-driven workspaces matter
+
+But `gr` still carries too much global behavior.
+
+`gr2` should keep the good parts and change the operating unit:
+
+- from global repo sync
+- to explicit workspace intent + lane-local repo maintenance
+
+## Why This Should Hold Up Under Scrutiny
+
+This design holds up if we enforce these rules:
+
+### 1. `apply` stays narrow
+
+If `apply` starts pulling, merging, rebasing, and switching branches, the model
+collapses back into hidden side effects.
+
+This rule is non-negotiable.
+
+### 2. Lanes are cheap
+
+If creating a lane feels expensive, people will go back to mutating one shared
+workspace and the safety model will fail.
+
+That means:
+
+- shared cache
+- fast materialization
+- minimal ceremony
+
+### 3. Lane state is explicit
+
+Every lane needs durable metadata:
+
+- included repos
+- branch map
+- PR associations
+- creation source
+- dirty/preserved state
+- context roots
+- execution defaults
+
+If lane state is inferred ad hoc from the filesystem, users will not trust it.
+
+### 4. Dirty-worktree handling is visible
+
+Autostash is useful, but it is dangerous if hidden.
+
+The system must record:
+
+- stash creation
+- target repo
+- restore attempt
+- restore failure
+
+### 5. Shared repos and active work stay separate
+
+If shared baseline repos and live feature repos share too much behavior, users
+will be surprised by sync results.
+
+### 6. PR workflows are first-class
+
+If checking out a PR is treated as a second-class hack, users will keep opening
+ad hoc worktrees and the multi-repo abstraction will fracture.
+
+### 7. Shared and private context stay separate
+
+If unit-private context leaks into shared context, agents will step on each
+other and humans will stop trusting the workspace.
+
+### 8. Execution is lane-aware
+
+If build/test/run commands are not scoped to lanes, users will still make the
+wrong changes in the wrong place and the workspace model will feel fake.
+
+## Risks
+
+### Disk Usage
+
+Multiple lanes mean more checkouts.
+
+Mitigation:
+
+- shared cache
+- sparse lane repo selection
+- disposable review lanes
+
+### Metadata Complexity
+
+Lane metadata, branch maps, and PR associations can get messy.
+
+Mitigation:
+
+- durable lane manifest/state
+- explicit commands
+- strong status surfaces
+
+### Too Many Abstractions
+
+If we introduce `spec`, `apply`, `repo`, `lane`, `cache`, and `pr` without clear
+boundaries, the UX will feel over-engineered.
+
+Mitigation:
+
+- keep the command split simple
+- optimize the happy path
+- document when to use each surface
+
+## Practical Recommendation
+
+Build `gr2` in this order:
+
+1. finish narrow `apply`
+2. add `gr2 repo status` using the prototype action taxonomy
+3. define lane metadata format, including context and execution defaults
+4. add `gr2 lane create/status/enter/remove`
+5. add `gr2 lane branch`
+6. add lane-aware `gr2 exec` surfaces for build/test/run
+7. add `gr2 lane checkout-pr`
+8. add `gr2 repo sync` with explicit policy and autostash logging
+
+## Bottom Line
+
+Yes, `gr2` should support two temporary scratchpads and more.
+
+That is not optional polish. It is the core answer to:
+
+- human multi-repo feature work
+- agent parallelism
+- review without disruption
+- switching features while another waits in PR
+
+The right foundation is:
+
+- declarative workspace spec
+- narrow structural apply
+- explicit repo maintenance
+- cheap named lanes as multi-repo scratchpads
+
+That is meaningfully better than `gr`, and it uses the actual lessons we
+already paid to learn.
diff --git a/gr2/prototypes/README.md b/gr2/prototypes/README.md
new file mode 100644
index 00000000..55c58632
--- /dev/null
+++ b/gr2/prototypes/README.md
@@ -0,0 +1,100 @@
+# gr2 Repo Maintenance Prototype
+
+This prototype explores a split between:
+
+- `gr2 apply`
+  - structural workspace convergence
+  - create/mount missing repo paths
+  - write unit metadata
+- repo maintenance
+  - fetch, fast-forward, branch correction, dirty-worktree handling
+
+## Why it exists
+
+`WorkspaceSpec v1` is intentionally narrow. It tells us which repos should
+exist and where they should live, but it does not yet define full collaboration
+policy for:
+
+- when to pull
+- when to fast-forward
+- when to refuse because a repo is dirty
+- when autostash is allowed
+- when a branch mismatch is safe to correct automatically
+
+The prototype keeps those decisions explicit instead of burying them inside
+`gr2 apply`.
+
+## Command
+
+```bash
+python3 gr2/prototypes/repo_maintenance_prototype.py /path/to/workspace
+```
+
+Optional policy file:
+
+```bash
+python3 gr2/prototypes/repo_maintenance_prototype.py \
+  /path/to/workspace \
+  --policy /path/to/repo_policy.toml
+```
+
+## Example policy
+
+```toml
+[defaults]
+tracked_branch = "main"
+shared_sync = "ff-only"
+unit_sync = "explicit"
+dirty = "block"
+
+[repos.grip]
+dirty = "autostash"
+```
+
+## Current behavior
+
+The planner classifies each shared repo and each unit-mounted repo into actions
+such as:
+
+- `clone_missing`
+- `fast_forward`
+- `checkout_branch`
+- `block_dirty`
+- `autostash_then_sync`
+- `manual_sync`
+- `no_change`
+
+That gives us a concrete design target for future commands like:
+
+- `gr2 repo status`
+- `gr2 repo sync`
+- `gr2 repo pull`
+
+without turning plain `gr2 apply` into an unsafe catch-all mutation command.
+
+## Lane Workspace Prototype
+
+`lane_workspace_prototype.py` explores the next layer above repo maintenance:
+
+- explicit lane metadata on disk
+- lane-local repo membership and branch map
+- shared + private context roots
+- lane-aware execution planning
+
+Example:
+
+```bash
+python3 gr2/prototypes/lane_workspace_prototype.py create-lane \
+  /path/to/workspace atlas feat-auth --repos app,api --branch feat/auth
+
+python3 gr2/prototypes/lane_workspace_prototype.py plan-exec \
+  /path/to/workspace atlas feat-auth 'cargo test'
+```
+
+This prototype does not execute commands. It proves that lane metadata can
+become the durable source of truth for:
+
+- which repos belong to a lane
+- which branch each repo should use
+- which context roots apply
+- where multi-repo commands should run
diff --git a/gr2/prototypes/lane_workspace_prototype.py b/gr2/prototypes/lane_workspace_prototype.py
new file mode 100644
index 00000000..9e1b4549
--- /dev/null
+++ b/gr2/prototypes/lane_workspace_prototype.py
@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""Prototype lane metadata and lane-aware execution planning for gr2.
+
+This prototype does not mutate git state. It proves the lane model is useful by
+persisting explicit lane metadata and generating execution plans scoped by lane.
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import shlex
+import sys
+import tomllib
+from pathlib import Path
+
+
+LANE_SCHEMA_VERSION = 1
+
+
+@dataclasses.dataclass
+class LaneMetadata:
+    schema_version: int
+    lane_name: str
+    owner_unit: str
+    lane_type: str
+    repos: list[str]
+    branch_map: dict[str, str]
+    pr_associations: list[str]
+    shared_context_roots: list[str]
+    private_context_roots: list[str]
+    exec_defaults: dict[str, object]
+    creation_source: str
+
+    def as_toml(self) -> str:
+        lines = [
+            f"schema_version = {self.schema_version}",
+            f'lane_name = "{self.lane_name}"',
+            f'owner_unit = "{self.owner_unit}"',
+            f'lane_type = "{self.lane_type}"',
+            f'creation_source = "{self.creation_source}"',
+            "",
+            f"repos = [{', '.join(f'\"{r}\"' for r in self.repos)}]",
+            "",
+            "[branch_map]",
+        ]
+        for repo, branch in sorted(self.branch_map.items()):
+            lines.append(f'{repo} = "{branch}"')
+
+        lines.extend(
+            [
+                "",
+                "[context]",
+                "shared_roots = ["
+            ]
+        )
+        for root in self.shared_context_roots:
+            lines.append(f'  "{root}",')
+
+        lines.extend(
+            [
+                "]",
+                "private_roots = [",
+            ]
+        )
+        for root in self.private_context_roots:
+            lines.append(f'  "{root}",')
+
+        lines.extend(
+            [
+                "]",
+                "",
+                "[exec_defaults]",
+            ]
+        )
+        for key, value in self.exec_defaults.items():
+            if isinstance(value, bool):
+                encoded = str(value).lower()
+            elif isinstance(value, int):
+                encoded = str(value)
+            elif isinstance(value, list):
+                encoded = "[" + ", ".join(f'"{item}"' for item in value) + "]"
+            else:
+                encoded = f'"{value}"'
+            lines.append(f"{key} = {encoded}")
+
+        if self.pr_associations:
+            lines.extend(["", "[[pr_associations]]"])
+            for assoc in self.pr_associations:
+                lines.append(f'ref = "{assoc}"')
+
+        return "\n".join(lines) + "\n"
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Prototype gr2 lane metadata + exec planner")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    create = sub.add_parser("create-lane")
+    create.add_argument("workspace_root", type=Path)
+    create.add_argument("owner_unit")
+    create.add_argument("lane_name")
+    create.add_argument("--type", default="feature")
+    create.add_argument("--repos", required=True, help="comma-separated repo names")
+    create.add_argument("--branch", required=True, help="default branch for included repos")
+    create.add_argument("--source", default="manual")
+
+    show = sub.add_parser("show-lane")
+    show.add_argument("workspace_root", type=Path)
+    show.add_argument("owner_unit")
+    show.add_argument("lane_name")
+
+    plan = sub.add_parser("plan-exec")
+    plan.add_argument("workspace_root", type=Path)
+    plan.add_argument("owner_unit")
+    plan.add_argument("lane_name")
+    plan.add_argument("command_text")
+    plan.add_argument("--repos", help="optional comma-separated repo subset")
+    plan.add_argument("--json", action="store_true")
+
+    return parser.parse_args()
+
+
+def lane_dir(workspace_root: Path, owner_unit: str, lane_name: str) -> Path:
+    return workspace_root / "agents" / owner_unit / "lanes" / lane_name
+
+
+def lane_file(workspace_root: Path, owner_unit: str, lane_name: str) -> Path:
+    return lane_dir(workspace_root, owner_unit, lane_name) / "lane.toml"
+
+
+def load_workspace_spec(workspace_root: Path) -> dict:
+    with (workspace_root / ".grip" / "workspace_spec.toml").open("rb") as fh:
+        return tomllib.load(fh)
+
+
+def create_lane(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    spec = load_workspace_spec(workspace_root)
+    repo_names = [item["name"] for item in spec.get("repos", [])]
+    repos = [repo.strip() for repo in args.repos.split(",") if repo.strip()]
+
+    missing = [repo for repo in repos if repo not in repo_names]
+    if missing:
+        raise SystemExit(f"unknown repos for lane: {', '.join(missing)}")
+
+    lane_root = lane_dir(workspace_root, args.owner_unit, args.lane_name)
+    lane_root.mkdir(parents=True, exist_ok=True)
+    (lane_root / "repos").mkdir(exist_ok=True)
+    (lane_root / "context").mkdir(exist_ok=True)
+
+    metadata = LaneMetadata(
+        schema_version=LANE_SCHEMA_VERSION,
+        lane_name=args.lane_name,
+        owner_unit=args.owner_unit,
+        lane_type=args.type,
+        repos=repos,
+        branch_map={repo: args.branch for repo in repos},
+        pr_associations=[],
+        shared_context_roots=["config", ".grip/context/shared"],
+        private_context_roots=[
+            f"agents/{args.owner_unit}/home/context",
+            f"agents/{args.owner_unit}/lanes/{args.lane_name}/context",
+        ],
+        exec_defaults={
+            "parallelism": "workspace-default",
+            "fail_fast": True,
+            "default_command_family": ["build", "test"],
+        },
+        creation_source=args.source,
+    )
+    lane_file(workspace_root, args.owner_unit, args.lane_name).write_text(metadata.as_toml())
+    print(lane_file(workspace_root, args.owner_unit, args.lane_name))
+    return 0
+
+
+def show_lane(args: argparse.Namespace) -> int:
+    print(lane_file(args.workspace_root.resolve(), args.owner_unit, args.lane_name).read_text())
+    return 0
+
+
+def plan_exec(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    lane_doc = tomllib.loads(
+        lane_file(workspace_root, args.owner_unit, args.lane_name).read_text()
+    )
+
+    selected_repos = lane_doc["repos"]
+    if args.repos:
+        requested = [repo.strip() for repo in args.repos.split(",") if repo.strip()]
+        selected_repos = [repo for repo in selected_repos if repo in requested]
+
+    command_argv = shlex.split(args.command_text)
+    rows = []
+    for repo in selected_repos:
+        rows.append(
+            {
+                "lane": lane_doc["lane_name"],
+                "owner_unit": lane_doc["owner_unit"],
+                "repo": repo,
+                "branch": lane_doc["branch_map"].get(repo),
+                "cwd": str(workspace_root / "agents" / args.owner_unit / "lanes" / args.lane_name / "repos" / repo),
+                "command": command_argv,
+                "shared_context_roots": lane_doc.get("context", {}).get("shared_roots", []),
+                "private_context_roots": lane_doc.get("context", {}).get("private_roots", []),
+                "fail_fast": lane_doc["exec_defaults"]["fail_fast"],
+            }
+        )
+
+    if args.json:
+        print(json.dumps(rows, indent=2))
+    else:
+        print("gr2 lane-exec prototype")
+        print("LANE\tREPO\tBRANCH\tCWD\tCOMMAND")
+        for row in rows:
+            print(
+                f"{row['lane']}\t{row['repo']}\t{row['branch']}\t{row['cwd']}\t{' '.join(row['command'])}"
+            )
+    return 0
+
+
+def main() -> int:
+    args = parse_args()
+    if args.command == "create-lane":
+        return create_lane(args)
+    if args.command == "show-lane":
+        return show_lane(args)
+    if args.command == "plan-exec":
+        return plan_exec(args)
+    raise SystemExit(f"unknown command: {args.command}")
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/gr2/prototypes/repo_maintenance_prototype.py b/gr2/prototypes/repo_maintenance_prototype.py
new file mode 100644
index 00000000..740ec259
--- /dev/null
+++ b/gr2/prototypes/repo_maintenance_prototype.py
@@ -0,0 +1,443 @@
+#!/usr/bin/env python3
+"""Prototype planner for gr2 repo maintenance policy.
+
+This is intentionally separate from gr2 apply. It answers:
+- which repos are missing and need clone/materialization
+- which repos are safe to fast-forward
+- which repos require explicit human intervention
+- where autostash would be required to proceed
+
+The goal is to keep workspace structure convergence (`gr2 apply`) separate
+from repo state convergence (`gr2 repo sync` / `gr2 repo pull`).
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import subprocess
+import sys
+import tomllib
+from pathlib import Path
+
+
+@dataclasses.dataclass(frozen=True)
+class RepoSpec:
+    name: str
+    path: str
+    url: str
+
+
+@dataclasses.dataclass(frozen=True)
+class UnitSpec:
+    name: str
+    path: str
+    repos: list[str]
+
+
+@dataclasses.dataclass(frozen=True)
+class WorkspaceSpec:
+    schema_version: int
+    workspace_name: str
+    repos: list[RepoSpec]
+    units: list[UnitSpec]
+
+
+@dataclasses.dataclass(frozen=True)
+class RepoTarget:
+    scope: str
+    target_name: str
+    repo_name: str
+    path: Path
+    url: str
+
+
+@dataclasses.dataclass(frozen=True)
+class RepoPolicy:
+    sync_mode: str
+    dirty_policy: str
+    tracked_branch: str | None
+
+
+@dataclasses.dataclass(frozen=True)
+class RepoStatus:
+    exists: bool
+    is_git_repo: bool
+    branch: str | None
+    upstream: str | None
+    dirty: bool
+    ahead: int
+    behind: int
+    detached: bool
+
+
+@dataclasses.dataclass(frozen=True)
+class PlannedAction:
+    target: RepoTarget
+    action: str
+    reason: str
+    status: RepoStatus
+    policy: RepoPolicy
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "scope": self.target.scope,
+            "target": self.target.target_name,
+            "repo": self.target.repo_name,
+            "path": str(self.target.path),
+            "action": self.action,
+            "reason": self.reason,
+            "status": dataclasses.asdict(self.status),
+            "policy": dataclasses.asdict(self.policy),
+        }
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Prototype gr2 repo maintenance planner")
+    parser.add_argument("workspace_root", type=Path, help="gr2 workspace root")
+    parser.add_argument(
+        "--spec",
+        type=Path,
+        help="path to workspace_spec.toml (defaults to <workspace>/.grip/workspace_spec.toml)",
+    )
+    parser.add_argument(
+        "--policy",
+        type=Path,
+        help="optional TOML policy file for branch/sync defaults",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="emit machine-readable JSON instead of a table",
+    )
+    return parser.parse_args()
+
+
+def read_workspace_spec(spec_path: Path) -> WorkspaceSpec:
+    with spec_path.open("rb") as fh:
+        raw = tomllib.load(fh)
+
+    repos = [
+        RepoSpec(name=item["name"], path=item["path"], url=item["url"])
+        for item in raw.get("repos", [])
+    ]
+    units = [
+        UnitSpec(
+            name=item["name"],
+            path=item["path"],
+            repos=list(item.get("repos", [])),
+        )
+        for item in raw.get("units", [])
+    ]
+    return WorkspaceSpec(
+        schema_version=raw["schema_version"],
+        workspace_name=raw["workspace_name"],
+        repos=repos,
+        units=units,
+    )
+
+
+def read_policy(policy_path: Path | None) -> dict[str, object]:
+    if policy_path is None:
+        return {}
+    with policy_path.open("rb") as fh:
+        return tomllib.load(fh)
+
+
+def derive_targets(workspace_root: Path, spec: WorkspaceSpec) -> list[RepoTarget]:
+    shared_targets = [
+        RepoTarget(
+            scope="shared",
+            target_name=repo.name,
+            repo_name=repo.name,
+            path=workspace_root / repo.path,
+            url=repo.url,
+        )
+        for repo in spec.repos
+    ]
+
+    repo_map = {repo.name: repo for repo in spec.repos}
+    unit_targets: list[RepoTarget] = []
+    for unit in spec.units:
+        for repo_name in unit.repos:
+            repo = repo_map[repo_name]
+            unit_targets.append(
+                RepoTarget(
+                    scope="unit",
+                    target_name=unit.name,
+                    repo_name=repo_name,
+                    path=workspace_root / unit.path / repo_name,
+                    url=repo.url,
+                )
+            )
+
+    return shared_targets + unit_targets
+
+
+def policy_for(target: RepoTarget, policy_doc: dict[str, object]) -> RepoPolicy:
+    defaults = policy_doc.get("defaults", {})
+    repos = policy_doc.get("repos", {})
+
+    if not isinstance(defaults, dict):
+        defaults = {}
+    if not isinstance(repos, dict):
+        repos = {}
+
+    repo_overrides = repos.get(target.repo_name, {})
+    if not isinstance(repo_overrides, dict):
+        repo_overrides = {}
+
+    if target.scope == "shared":
+        sync_mode = str(repo_overrides.get("sync", defaults.get("shared_sync", "ff-only")))
+    else:
+        sync_mode = str(repo_overrides.get("sync", defaults.get("unit_sync", "explicit")))
+
+    dirty_policy = str(repo_overrides.get("dirty", defaults.get("dirty", "block")))
+    tracked_branch = repo_overrides.get("tracked_branch", defaults.get("tracked_branch"))
+    tracked_branch = str(tracked_branch) if tracked_branch is not None else None
+
+    return RepoPolicy(
+        sync_mode=sync_mode,
+        dirty_policy=dirty_policy,
+        tracked_branch=tracked_branch,
+    )
+
+
+def run_git(repo_path: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", *args],
+        cwd=repo_path,
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+
+
+def inspect_repo(path: Path) -> RepoStatus:
+    if not path.exists():
+        return RepoStatus(
+            exists=False,
+            is_git_repo=False,
+            branch=None,
+            upstream=None,
+            dirty=False,
+            ahead=0,
+            behind=0,
+            detached=False,
+        )
+
+    git_check = run_git(path, "rev-parse", "--is-inside-work-tree")
+    if git_check.returncode != 0 or git_check.stdout.strip() != "true":
+        return RepoStatus(
+            exists=True,
+            is_git_repo=False,
+            branch=None,
+            upstream=None,
+            dirty=False,
+            ahead=0,
+            behind=0,
+            detached=False,
+        )
+
+    branch_proc = run_git(path, "symbolic-ref", "--quiet", "--short", "HEAD")
+    detached = branch_proc.returncode != 0
+    branch = None if detached else branch_proc.stdout.strip()
+
+    upstream_proc = run_git(path, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}")
+    upstream = upstream_proc.stdout.strip() if upstream_proc.returncode == 0 else None
+
+    dirty_proc = run_git(path, "status", "--porcelain")
+    dirty = bool(dirty_proc.stdout.strip())
+
+    ahead = 0
+    behind = 0
+    if upstream:
+        counts_proc = run_git(path, "rev-list", "--left-right", "--count", f"HEAD...{upstream}")
+        if counts_proc.returncode == 0:
+            left, right = counts_proc.stdout.strip().split()
+            ahead = int(left)
+            behind = int(right)
+
+    return RepoStatus(
+        exists=True,
+        is_git_repo=True,
+        branch=branch,
+        upstream=upstream,
+        dirty=dirty,
+        ahead=ahead,
+        behind=behind,
+        detached=detached,
+    )
+
+
+def classify(target: RepoTarget, status: RepoStatus, policy: RepoPolicy) -> PlannedAction:
+    if not status.exists:
+        return PlannedAction(target, "clone_missing", "repo path is absent", status, policy)
+
+    if not status.is_git_repo:
+        return PlannedAction(
+            target,
+            "block_path_conflict",
+            "target path exists but is not a git repo",
+            status,
+            policy,
+        )
+
+    if status.detached:
+        return PlannedAction(
+            target,
+            "manual_sync",
+            "repo is on a detached HEAD; do not move automatically",
+            status,
+            policy,
+        )
+
+    if policy.tracked_branch and status.branch != policy.tracked_branch:
+        if target.scope == "shared" and not status.dirty and status.ahead == 0:
+            return PlannedAction(
+                target,
+                "checkout_branch",
+                f"shared repo should be on {policy.tracked_branch}, found {status.branch}",
+                status,
+                policy,
+            )
+        return PlannedAction(
+            target,
+            "manual_sync",
+            f"branch mismatch: expected {policy.tracked_branch}, found {status.branch}",
+            status,
+            policy,
+        )
+
+    if status.dirty:
+        if policy.dirty_policy == "autostash":
+            return PlannedAction(
+                target,
+                "autostash_then_sync",
+                "working tree is dirty and policy allows preservation",
+                status,
+                policy,
+            )
+        return PlannedAction(
+            target,
+            "block_dirty",
+            "working tree is dirty; stop by default",
+            status,
+            policy,
+        )
+
+    if not status.upstream:
+        return PlannedAction(
+            target,
+            "manual_sync",
+            "repo has no upstream tracking branch",
+            status,
+            policy,
+        )
+
+    if status.behind == 0 and status.ahead == 0:
+        return PlannedAction(
+            target,
+            "no_change",
+            "repo is already aligned with upstream",
+            status,
+            policy,
+        )
+
+    if status.behind > 0 and status.ahead == 0:
+        if policy.sync_mode == "ff-only":
+            return PlannedAction(
+                target,
+                "fast_forward",
+                f"repo is behind upstream by {status.behind} commit(s) and can fast-forward",
+                status,
+                policy,
+            )
+        return PlannedAction(
+            target,
+            "manual_sync",
+            f"repo is behind upstream by {status.behind} commit(s), but policy requires explicit sync",
+            status,
+            policy,
+        )
+
+    if status.behind > 0 and status.ahead > 0:
+        return PlannedAction(
+            target,
+            "manual_sync",
+            f"repo diverged from upstream (ahead {status.ahead}, behind {status.behind})",
+            status,
+            policy,
+        )
+
+    if status.ahead > 0:
+        return PlannedAction(
+            target,
+            "manual_sync",
+            f"repo has {status.ahead} local commit(s) ahead of upstream",
+            status,
+            policy,
+        )
+
+    return PlannedAction(target, "manual_sync", "unclassified repo state", status, policy)
+
+
+def render_table(actions: list[PlannedAction]) -> str:
+    lines = [
+        "gr2 repo-maintenance prototype",
+        "SCOPE\tTARGET\tREPO\tACTION\tBRANCH\tUPSTREAM\tSTATE\tREASON",
+    ]
+    for item in actions:
+        state_bits = []
+        if item.status.dirty:
+            state_bits.append("dirty")
+        if item.status.ahead:
+            state_bits.append(f"ahead={item.status.ahead}")
+        if item.status.behind:
+            state_bits.append(f"behind={item.status.behind}")
+        if item.status.detached:
+            state_bits.append("detached")
+        if not state_bits:
+            state_bits.append("clean")
+
+        lines.append(
+            "\t".join(
+                [
+                    item.target.scope,
+                    item.target.target_name,
+                    item.target.repo_name,
+                    item.action,
+                    item.status.branch or "-",
+                    item.status.upstream or "-",
+                    ",".join(state_bits),
+                    item.reason,
+                ]
+            )
+        )
+    return "\n".join(lines)
+
+
+def main() -> int:
+    args = parse_args()
+    workspace_root = args.workspace_root.resolve()
+    spec_path = (args.spec or workspace_root / ".grip" / "workspace_spec.toml").resolve()
+    spec = read_workspace_spec(spec_path)
+    policy_doc = read_policy(args.policy)
+
+    actions = []
+    for target in derive_targets(workspace_root, spec):
+        status = inspect_repo(target.path)
+        policy = policy_for(target, policy_doc)
+        actions.append(classify(target, status, policy))
+
+    if args.json:
+        print(json.dumps([item.as_dict() for item in actions], indent=2))
+    else:
+        print(render_table(actions))
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

From 8ccb34363ef7cb699e409c7dadb3815f5f3dcef5 Mon Sep 17 00:00:00 2001
From: Layne Penney <dev@layne.pro>
Date: Sun, 12 Apr 2026 00:02:00 -0500
Subject: [PATCH 11/15] feat: add gr2 repo status surface (#548)

---
 gr2/src/args.rs        |  11 ++
 gr2/src/dispatch.rs    |   8 +
 gr2/src/lib.rs         |   1 +
 gr2/src/repo_status.rs | 329 +++++++++++++++++++++++++++++++++++++++++
 tests/cli_tests.rs     | 268 ++++++++++++++++++++++++---------
 5 files changed, 546 insertions(+), 71 deletions(-)
 create mode 100644 gr2/src/repo_status.rs

diff --git a/gr2/src/args.rs b/gr2/src/args.rs
index 69c1bcd3..f381a476 100644
--- a/gr2/src/args.rs
+++ b/gr2/src/args.rs
@@ -107,6 +107,17 @@ pub enum RepoCommands {
     /// List registered repos
     List,
 
+    /// Inspect repo-maintenance state across shared repos and unit repos
+    Status {
+        /// Only show repo state for a specific unit
+        #[arg(long)]
+        unit: Option<String>,
+
+        /// Only show a specific repo name
+        #[arg(long)]
+        repo: Option<String>,
+    },
+
     /// Remove a registered repo
     Remove {
         /// Logical repo name
diff --git a/gr2/src/dispatch.rs b/gr2/src/dispatch.rs
index 40e60366..9d92f128 100644
--- a/gr2/src/dispatch.rs
+++ b/gr2/src/dispatch.rs
@@ -4,6 +4,7 @@ use std::path::PathBuf;
 
 use crate::args::{Commands, RepoCommands, SpecCommands, TeamCommands, UnitCommands};
 use crate::plan::ExecutionPlan;
+use crate::repo_status::{RepoStatusFilter, RepoStatusReport};
 use crate::spec::{read_workspace_spec, workspace_spec_path, write_workspace_spec, WorkspaceSpec};
 
 pub async fn dispatch_command(command: Commands, verbose: bool) -> Result<()> {
@@ -176,6 +177,13 @@ pub async fn dispatch_command(command: Commands, verbose: bool) -> Result<()> {
 
                 Ok(())
             }
+            RepoCommands::Status { unit, repo } => {
+                let workspace_root = require_workspace_root()?;
+                let report =
+                    RepoStatusReport::load(&workspace_root, &RepoStatusFilter { unit, repo })?;
+                println!("{}", report.render_table());
+                Ok(())
+            }
             RepoCommands::Remove { name } => {
                 let workspace_root = require_workspace_root()?;
                 let repos_root = workspace_root.join("repos");
diff --git a/gr2/src/lib.rs b/gr2/src/lib.rs
index ba904930..2c0c1d61 100644
--- a/gr2/src/lib.rs
+++ b/gr2/src/lib.rs
@@ -5,4 +5,5 @@
 pub mod args;
 pub mod dispatch;
 pub mod plan;
+pub mod repo_status;
 pub mod spec;
diff --git a/gr2/src/repo_status.rs b/gr2/src/repo_status.rs
new file mode 100644
index 00000000..4b89bc5d
--- /dev/null
+++ b/gr2/src/repo_status.rs
@@ -0,0 +1,329 @@
+use anyhow::{Context, Result};
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use crate::spec::{read_workspace_spec, RepoSpec, UnitSpec};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RepoAction {
+    CloneMissing,
+    BlockPathConflict,
+    BlockDirty,
+    FastForward,
+    ManualSync,
+    NoChange,
+}
+
+impl RepoAction {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::CloneMissing => "clone_missing",
+            Self::BlockPathConflict => "block_path_conflict",
+            Self::BlockDirty => "block_dirty",
+            Self::FastForward => "fast_forward",
+            Self::ManualSync => "manual_sync",
+            Self::NoChange => "no_change",
+        }
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RepoScope {
+    Shared,
+    Unit,
+}
+
+impl RepoScope {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Shared => "shared",
+            Self::Unit => "unit",
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RepoStatusRow {
+    pub scope: RepoScope,
+    pub target: String,
+    pub repo: String,
+    pub path: PathBuf,
+    pub action: RepoAction,
+    pub branch: Option<String>,
+    pub upstream: Option<String>,
+    pub dirty: bool,
+    pub ahead: u32,
+    pub behind: u32,
+    pub reason: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RepoStatusReport {
+    pub rows: Vec<RepoStatusRow>,
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct RepoStatusFilter {
+    pub unit: Option<String>,
+    pub repo: Option<String>,
+}
+
+impl RepoStatusReport {
+    pub fn load(workspace_root: &Path, filter: &RepoStatusFilter) -> Result<Self> {
+        let spec = read_workspace_spec(workspace_root)?;
+        let mut rows = Vec::new();
+
+        for repo in &spec.repos {
+            if filter.repo.as_deref().is_some_and(|name| name != repo.name) {
+                continue;
+            }
+            rows.push(classify_shared_repo(workspace_root, repo)?);
+        }
+
+        for unit in &spec.units {
+            if filter.unit.as_deref().is_some_and(|name| name != unit.name) {
+                continue;
+            }
+            for repo_name in &unit.repos {
+                if filter.repo.as_deref().is_some_and(|name| name != repo_name) {
+                    continue;
+                }
+                let repo = spec
+                    .repos
+                    .iter()
+                    .find(|repo| repo.name == *repo_name)
+                    .with_context(|| {
+                        format!(
+                            "unit '{}' references repo '{}' which is missing from workspace spec",
+                            unit.name, repo_name
+                        )
+                    })?;
+                rows.push(classify_unit_repo(workspace_root, unit, repo)?);
+            }
+        }
+
+        rows.sort_by(|a, b| {
+            a.scope
+                .as_str()
+                .cmp(b.scope.as_str())
+                .then_with(|| a.target.cmp(&b.target))
+                .then_with(|| a.repo.cmp(&b.repo))
+        });
+
+        Ok(Self { rows })
+    }
+
+    pub fn render_table(&self) -> String {
+        if self.rows.is_empty() {
+            return "RepoStatus\n- no repo targets matched\n".to_string();
+        }
+
+        let mut lines = vec![
+            "RepoStatus".to_string(),
+            "SCOPE\tTARGET\tREPO\tACTION\tBRANCH\tUPSTREAM\tSTATE\tREASON".to_string(),
+        ];
+
+        for row in &self.rows {
+            let mut state = Vec::new();
+            if row.dirty {
+                state.push("dirty".to_string());
+            }
+            if row.ahead > 0 {
+                state.push(format!("ahead={}", row.ahead));
+            }
+            if row.behind > 0 {
+                state.push(format!("behind={}", row.behind));
+            }
+            if state.is_empty() {
+                state.push("clean".to_string());
+            }
+
+            lines.push(format!(
+                "{}\t{}\t{}\t{}\t{}\t{}\t{}\t{}",
+                row.scope.as_str(),
+                row.target,
+                row.repo,
+                row.action.as_str(),
+                row.branch.as_deref().unwrap_or("-"),
+                row.upstream.as_deref().unwrap_or("-"),
+                state.join(","),
+                row.reason
+            ));
+        }
+
+        lines.join("\n")
+    }
+}
+
+fn classify_shared_repo(workspace_root: &Path, repo: &RepoSpec) -> Result<RepoStatusRow> {
+    let path = workspace_root.join(&repo.path);
+    let mut row = base_row(
+        RepoScope::Shared,
+        repo.name.clone(),
+        repo.name.clone(),
+        path.clone(),
+    );
+
+    if !path.exists() {
+        row.action = RepoAction::CloneMissing;
+        row.reason = "shared repo path is absent".to_string();
+        return Ok(row);
+    }
+
+    if !is_git_repo(&path)? {
+        row.action = RepoAction::BlockPathConflict;
+        row.reason = "shared repo path exists but is not a git repo".to_string();
+        return Ok(row);
+    }
+
+    fill_git_status(&path, &mut row)?;
+    classify_repo_state(&mut row, true);
+    Ok(row)
+}
+
+fn classify_unit_repo(
+    workspace_root: &Path,
+    unit: &UnitSpec,
+    repo: &RepoSpec,
+) -> Result<RepoStatusRow> {
+    let path = workspace_root.join(&unit.path).join(&repo.name);
+    let mut row = base_row(
+        RepoScope::Unit,
+        unit.name.clone(),
+        repo.name.clone(),
+        path.clone(),
+    );
+
+    if !path.exists() {
+        row.action = RepoAction::CloneMissing;
+        row.reason = "unit repo checkout is absent".to_string();
+        return Ok(row);
+    }
+
+    if !is_git_repo(&path)? {
+        row.action = RepoAction::BlockPathConflict;
+        row.reason = "unit repo path exists but is not a git repo".to_string();
+        return Ok(row);
+    }
+
+    fill_git_status(&path, &mut row)?;
+    classify_repo_state(&mut row, false);
+    Ok(row)
+}
+
+fn base_row(scope: RepoScope, target: String, repo: String, path: PathBuf) -> RepoStatusRow {
+    RepoStatusRow {
+        scope,
+        target,
+        repo,
+        path,
+        action: RepoAction::NoChange,
+        branch: None,
+        upstream: None,
+        dirty: false,
+        ahead: 0,
+        behind: 0,
+        reason: String::new(),
+    }
+}
+
+fn classify_repo_state(row: &mut RepoStatusRow, allow_ff: bool) {
+    if row.dirty {
+        row.action = RepoAction::BlockDirty;
+        row.reason = "working tree is dirty; stop by default".to_string();
+        return;
+    }
+
+    match (row.ahead, row.behind, row.upstream.is_some()) {
+        (_, _, false) => {
+            row.action = RepoAction::ManualSync;
+            row.reason = "repo has no upstream tracking branch".to_string();
+        }
+        (0, 0, true) => {
+            row.action = RepoAction::NoChange;
+            row.reason = "repo is already aligned with upstream".to_string();
+        }
+        (0, behind, true) if behind > 0 && allow_ff => {
+            row.action = RepoAction::FastForward;
+            row.reason = format!("repo is behind upstream by {} commit(s)", behind);
+        }
+        (0, behind, true) if behind > 0 => {
+            row.action = RepoAction::ManualSync;
+            row.reason = format!(
+                "repo is behind upstream by {} commit(s), but unit repos require explicit sync",
+                behind
+            );
+        }
+        (ahead, behind, true) if ahead > 0 && behind > 0 => {
+            row.action = RepoAction::ManualSync;
+            row.reason = format!(
+                "repo diverged from upstream (ahead {}, behind {})",
+                ahead, behind
+            );
+        }
+        (ahead, 0, true) if ahead > 0 => {
+            row.action = RepoAction::ManualSync;
+            row.reason = format!("repo has {} local commit(s) ahead of upstream", ahead);
+        }
+        _ => {
+            row.action = RepoAction::ManualSync;
+            row.reason = "repo requires explicit inspection".to_string();
+        }
+    }
+}
+
+fn fill_git_status(repo_path: &Path, row: &mut RepoStatusRow) -> Result<()> {
+    row.branch = git_stdout(repo_path, &["symbolic-ref", "--quiet", "--short", "HEAD"]).ok();
+    row.upstream = git_stdout(
+        repo_path,
+        &[
+            "rev-parse",
+            "--abbrev-ref",
+            "--symbolic-full-name",
+            "@{upstream}",
+        ],
+    )
+    .ok();
+    row.dirty = !git_stdout(repo_path, &["status", "--porcelain"])?.is_empty();
+
+    if row.upstream.is_some() {
+        let counts = git_stdout(
+            repo_path,
+            &["rev-list", "--left-right", "--count", "HEAD...@{upstream}"],
+        )?;
+        let mut parts = counts.split_whitespace();
+        row.ahead = parts.next().unwrap_or("0").parse().unwrap_or(0);
+        row.behind = parts.next().unwrap_or("0").parse().unwrap_or(0);
+    }
+
+    Ok(())
+}
+
+fn is_git_repo(path: &Path) -> Result<bool> {
+    let output = Command::new("git")
+        .args(["rev-parse", "--is-inside-work-tree"])
+        .current_dir(path)
+        .output()
+        .with_context(|| format!("run git rev-parse in {}", path.display()))?;
+
+    Ok(output.status.success() && String::from_utf8_lossy(&output.stdout).trim() == "true")
+}
+
+fn git_stdout(repo_path: &Path, args: &[&str]) -> Result<String> {
+    let output = Command::new("git")
+        .args(args)
+        .current_dir(repo_path)
+        .output()
+        .with_context(|| format!("run git {:?} in {}", args, repo_path.display()))?;
+
+    if !output.status.success() {
+        anyhow::bail!(
+            "git {:?} failed in {}: {}",
+            args,
+            repo_path.display(),
+            String::from_utf8_lossy(&output.stderr).trim()
+        );
+    }
+
+    Ok(String::from_utf8_lossy(&output.stdout).trim().to_string())
+}
diff --git a/tests/cli_tests.rs b/tests/cli_tests.rs
index a14d304f..4c2705db 100644
--- a/tests/cli_tests.rs
+++ b/tests/cli_tests.rs
@@ -475,6 +475,172 @@ fn test_gr2_repo_list_requires_gr2_workspace() {
         ));
 }
 
+#[test]
+fn test_gr2_repo_status_reports_missing_unit_checkout_as_clone_missing() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app"]
+"#,
+        toml_path(&bare)
+    );
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), spec).unwrap();
+    std::fs::create_dir_all(workspace_root.join("agents/atlas")).unwrap();
+    std::fs::write(
+        workspace_root.join("agents/atlas/unit.toml"),
+        "name = \"atlas\"\nkind = \"unit\"\nrepos = [\"app\"]\n",
+    )
+    .unwrap();
+
+    let mut status = Command::cargo_bin("gr2").unwrap();
+    status
+        .current_dir(&workspace_root)
+        .args(["repo", "status"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("RepoStatus"))
+        .stdout(predicate::str::contains("clone_missing"))
+        .stdout(predicate::str::contains("atlas"))
+        .stdout(predicate::str::contains("app"));
+}
+
+#[test]
+fn test_gr2_repo_status_reports_dirty_unit_repo_as_block_dirty() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app"]
+"#,
+        toml_path(&bare)
+    );
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), spec).unwrap();
+    std::fs::create_dir_all(workspace_root.join("agents/atlas")).unwrap();
+    std::fs::write(
+        workspace_root.join("agents/atlas/unit.toml"),
+        "name = \"atlas\"\nkind = \"unit\"\nrepos = [\"app\"]\n",
+    )
+    .unwrap();
+
+    let clone_dest = workspace_root.join("agents/atlas/app");
+    let status = std::process::Command::new("git")
+        .arg("clone")
+        .arg(&bare)
+        .arg(&clone_dest)
+        .status()
+        .unwrap();
+    assert!(status.success());
+    std::fs::write(clone_dest.join("dirty.txt"), "local change").unwrap();
+
+    let mut repo_status = Command::cargo_bin("gr2").unwrap();
+    repo_status
+        .current_dir(&workspace_root)
+        .args(["repo", "status", "--unit", "atlas"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("block_dirty"))
+        .stdout(predicate::str::contains("working tree is dirty"));
+}
+
+#[test]
+fn test_gr2_repo_status_reports_shared_repo_behind_upstream_as_fast_forward() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init").arg(&workspace_root).assert().success();
+
+    let bare = create_bare_repo_with_content(temp.path(), "app");
+
+    let spec = format!(
+        r#"schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{}"
+"#,
+        toml_path(&bare)
+    );
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), spec).unwrap();
+
+    let shared_repo = workspace_root.join("repos/app");
+    let status = std::process::Command::new("git")
+        .arg("clone")
+        .arg(&bare)
+        .arg(&shared_repo)
+        .status()
+        .unwrap();
+    assert!(status.success());
+
+    let staging = temp.path().join("staging");
+    let status = std::process::Command::new("git")
+        .arg("clone")
+        .arg(&bare)
+        .arg(&staging)
+        .status()
+        .unwrap();
+    assert!(status.success());
+    git_helpers::configure_identity(&staging);
+    git_helpers::commit_file(&staging, "later.txt", "upstream", "Add upstream");
+    let branch = git_helpers::current_branch(&staging);
+    git_helpers::push_branch(&staging, "origin", &branch);
+    git_helpers::fetch(&shared_repo, "origin", Some(&branch));
+
+    let mut repo_status = Command::cargo_bin("gr2").unwrap();
+    repo_status
+        .current_dir(&workspace_root)
+        .args(["repo", "status", "--repo", "app"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("fast_forward"))
+        .stdout(predicate::str::contains("shared"))
+        .stdout(predicate::str::contains("behind=1"));
+}
+
 #[test]
 fn test_gr2_repo_remove_deletes_registered_repo() {
     let temp = TempDir::new().unwrap();
@@ -1032,7 +1198,7 @@ name = "atlas"
 path = "agents/atlas"
 repos = ["app"]
 "#,
-        bare.display()
+        toml_path(&bare)
     );
     std::fs::write(
         workspace_root.join(".grip/workspace_spec.toml"),
@@ -1233,17 +1399,13 @@ name = "atlas"
 path = "agents/atlas"
 repos = ["app"]
 "#,
-        bare_repo.display()
+        toml_path(&bare_repo)
     );
-    std::fs::write(
-        workspace_root.join(".grip/workspace_spec.toml"),
-        &spec,
-    )
-    .unwrap();
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
     std::fs::create_dir_all(workspace_root.join("repos/app")).unwrap();
     std::fs::write(
         workspace_root.join("repos/app/repo.toml"),
-        format!("name = \"app\"\nurl = \"{}\"\n", bare_repo.display()),
+        format!("name = \"app\"\nurl = \"{}\"\n", toml_path(&bare_repo)),
     )
     .unwrap();
 
@@ -2351,13 +2513,9 @@ name = "apollo"
 path = "agents/apollo"
 repos = ["test-repo"]
 "#,
-        bare_repo.display()
+        toml_path(&bare_repo)
     );
-    std::fs::write(
-        workspace_root.join(".grip/workspace_spec.toml"),
-        &spec,
-    )
-    .unwrap();
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
 
     let mut apply = Command::cargo_bin("gr2").unwrap();
     apply
@@ -2427,13 +2585,9 @@ name = "apollo"
 path = "agents/apollo"
 repos = ["test-repo"]
 "#,
-        bare_repo.display()
+        toml_path(&bare_repo)
     );
-    std::fs::write(
-        workspace_root.join(".grip/workspace_spec.toml"),
-        &spec,
-    )
-    .unwrap();
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
 
     let mut plan = Command::cargo_bin("gr2").unwrap();
     plan.current_dir(&workspace_root)
@@ -2451,7 +2605,7 @@ repos = ["test-repo"]
 fn create_bare_repo_with_content(parent: &std::path::Path, name: &str) -> std::path::PathBuf {
     let bare = parent.join(format!("{}.git", name));
     std::process::Command::new("git")
-        .args(["init", "--bare"])
+        .args(["init", "--bare", "-b", "main"])
         .arg(&bare)
         .output()
         .unwrap();
@@ -2464,6 +2618,7 @@ fn create_bare_repo_with_content(parent: &std::path::Path, name: &str) -> std::p
         .arg(&work)
         .output()
         .unwrap();
+    git_helpers::configure_identity(&work);
     std::fs::write(work.join("README.md"), "# test\n").unwrap();
     std::process::Command::new("git")
         .args(["add", "."])
@@ -2484,6 +2639,10 @@ fn create_bare_repo_with_content(parent: &std::path::Path, name: &str) -> std::p
     bare
 }
 
+fn toml_path(path: &std::path::Path) -> String {
+    path.display().to_string().replace('\\', "\\\\")
+}
+
 /// Helper: set up a workspace with a unit that has an already-cloned repo.
 /// Returns the workspace root path.
 fn setup_workspace_with_cloned_unit(
@@ -2527,13 +2686,9 @@ name = "apollo"
 path = "agents/apollo"
 repos = ["app"]
 "#,
-        bare_repo.display()
+        toml_path(&bare_repo)
     );
-    std::fs::write(
-        workspace_root.join(".grip/workspace_spec.toml"),
-        &spec,
-    )
-    .unwrap();
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
 
     // Run apply once to materialize the unit + clone the repo
     let mut apply = Command::cargo_bin("gr2").unwrap();
@@ -2587,13 +2742,9 @@ src = "config/shared.toml"
 dest = ".config/shared.toml"
 kind = "symlink"
 "#,
-        bare.display()
+        toml_path(&bare)
     );
-    std::fs::write(
-        workspace_root.join(".grip/workspace_spec.toml"),
-        &spec,
-    )
-    .unwrap();
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
 
     // Apply without --autostash should fail because the unit's repo is dirty
     let mut apply = Command::cargo_bin("gr2").unwrap();
@@ -2602,8 +2753,7 @@ kind = "symlink"
         .arg("apply")
         .assert()
         .failure()
-        .stderr(predicate::str::contains("dirty")
-            .or(predicate::str::contains("uncommitted")));
+        .stderr(predicate::str::contains("dirty").or(predicate::str::contains("uncommitted")));
 }
 
 /// gr2 apply --autostash should preserve dirty changes by stashing before
@@ -2642,13 +2792,9 @@ src = "config/shared.toml"
 dest = ".config/shared.toml"
 kind = "symlink"
 "#,
-        bare.display()
+        toml_path(&bare)
     );
-    std::fs::write(
-        workspace_root.join(".grip/workspace_spec.toml"),
-        &spec,
-    )
-    .unwrap();
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
 
     // Apply with --autostash should succeed
     let mut apply = Command::cargo_bin("gr2").unwrap();
@@ -2703,13 +2849,9 @@ src = "config/shared.toml"
 dest = ".config/shared.toml"
 kind = "symlink"
 "#,
-        bare.display()
+        toml_path(&bare)
     );
-    std::fs::write(
-        workspace_root.join(".grip/workspace_spec.toml"),
-        &spec,
-    )
-    .unwrap();
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
 
     // Plan should report the dirty state with specifics
     let mut plan = Command::cargo_bin("gr2").unwrap();
@@ -2756,13 +2898,9 @@ src = "config/shared.toml"
 dest = ".config/shared.toml"
 kind = "symlink"
 "#,
-        bare.display()
+        toml_path(&bare)
     );
-    std::fs::write(
-        workspace_root.join(".grip/workspace_spec.toml"),
-        &spec,
-    )
-    .unwrap();
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
 
     // Apply with --autostash
     let mut apply = Command::cargo_bin("gr2").unwrap();
@@ -2861,13 +2999,9 @@ name = "apollo"
 path = "agents/apollo"
 repos = ["myrepo"]
 "#,
-        bare.display()
+        toml_path(&bare)
     );
-    std::fs::write(
-        workspace_root.join(".grip/workspace_spec.toml"),
-        &spec,
-    )
-    .unwrap();
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
 
     // Plan should detect the missing repo and emit a non-empty plan
     let mut plan = Command::cargo_bin("gr2").unwrap();
@@ -2930,13 +3064,9 @@ name = "apollo"
 path = "agents/apollo"
 repos = ["myrepo"]
 "#,
-        bare.display()
+        toml_path(&bare)
     );
-    std::fs::write(
-        workspace_root.join(".grip/workspace_spec.toml"),
-        &spec,
-    )
-    .unwrap();
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
 
     // Apply should converge: clone the missing repo
     let mut apply = Command::cargo_bin("gr2").unwrap();
@@ -3005,13 +3135,9 @@ name = "apollo"
 path = "agents/apollo"
 repos = ["myrepo"]
 "#,
-        bare.display()
+        toml_path(&bare)
     );
-    std::fs::write(
-        workspace_root.join(".grip/workspace_spec.toml"),
-        &spec,
-    )
-    .unwrap();
+    std::fs::write(workspace_root.join(".grip/workspace_spec.toml"), &spec).unwrap();
 
     // First apply converges
     let mut first = Command::cargo_bin("gr2").unwrap();

From 93a2ca23df4509070e3e5109720ce562ba3f25f3 Mon Sep 17 00:00:00 2001
From: Layne Penney <dev@layne.pro>
Date: Sun, 12 Apr 2026 00:03:20 -0500
Subject: [PATCH 12/15] feat: add gr2 lane metadata surface (#549)

---
 gr2/src/args.rs     |  86 ++++++++++
 gr2/src/dispatch.rs | 117 ++++++++++++-
 gr2/src/lane.rs     | 400 ++++++++++++++++++++++++++++++++++++++++++++
 gr2/src/lib.rs      |   1 +
 tests/cli_tests.rs  | 310 ++++++++++++++++++++++++++++++++++
 5 files changed, 912 insertions(+), 2 deletions(-)
 create mode 100644 gr2/src/lane.rs

diff --git a/gr2/src/args.rs b/gr2/src/args.rs
index f381a476..045806cf 100644
--- a/gr2/src/args.rs
+++ b/gr2/src/args.rs
@@ -50,6 +50,12 @@ pub enum Commands {
         command: UnitCommands,
     },
 
+    /// Lane metadata operations
+    Lane {
+        #[command(subcommand)]
+        command: LaneCommands,
+    },
+
     /// Declarative workspace spec operations
     Spec {
         #[command(subcommand)]
@@ -143,6 +149,86 @@ pub enum UnitCommands {
     },
 }
 
+#[derive(Subcommand, Debug)]
+pub enum LaneCommands {
+    /// Create a lane record and scaffold its workspace directories
+    Create {
+        /// Lane name
+        name: String,
+
+        /// Owning unit
+        #[arg(long = "owner-unit")]
+        owner_unit: String,
+
+        /// Lane type
+        #[arg(long = "type", default_value = "feature")]
+        lane_type: String,
+
+        /// Repo membership for the lane (defaults to unit repos from workspace spec)
+        #[arg(long = "repo")]
+        repos: Vec<String>,
+
+        /// Branch intent entries in repo=branch form
+        #[arg(long = "branch")]
+        branches: Vec<String>,
+
+        /// Extra shared context roots relative to workspace root
+        #[arg(long = "shared-context")]
+        shared_context: Vec<String>,
+
+        /// Extra private context roots relative to workspace root
+        #[arg(long = "private-context")]
+        private_context: Vec<String>,
+
+        /// Default execution command for the lane (repeatable)
+        #[arg(long = "exec")]
+        exec: Vec<String>,
+
+        /// PR associations in repo:number form
+        #[arg(long = "pr")]
+        prs: Vec<String>,
+
+        /// Creation source label
+        #[arg(long)]
+        source: Option<String>,
+
+        /// Allow execution fan-out across repos by default
+        #[arg(long)]
+        parallel: bool,
+
+        /// Do not fail fast when running multi-repo commands
+        #[arg(long)]
+        no_fail_fast: bool,
+    },
+
+    /// List persisted lanes
+    List {
+        /// Filter to one owner unit
+        #[arg(long = "owner-unit")]
+        owner_unit: Option<String>,
+    },
+
+    /// Print one lane record
+    Show {
+        /// Lane name
+        name: String,
+
+        /// Owning unit
+        #[arg(long = "owner-unit")]
+        owner_unit: String,
+    },
+
+    /// Remove one lane record and its scaffolded directories
+    Remove {
+        /// Lane name
+        name: String,
+
+        /// Owning unit
+        #[arg(long = "owner-unit")]
+        owner_unit: String,
+    },
+}
+
 #[derive(Subcommand, Debug)]
 pub enum SpecCommands {
     /// Print the current workspace spec
diff --git a/gr2/src/dispatch.rs b/gr2/src/dispatch.rs
index 9d92f128..482a7a6e 100644
--- a/gr2/src/dispatch.rs
+++ b/gr2/src/dispatch.rs
@@ -1,8 +1,13 @@
-use anyhow::Result;
+use anyhow::{Context, Result};
+use std::collections::BTreeMap;
 use std::fs;
 use std::path::PathBuf;
 
-use crate::args::{Commands, RepoCommands, SpecCommands, TeamCommands, UnitCommands};
+use crate::args::{Commands, LaneCommands, RepoCommands, SpecCommands, TeamCommands, UnitCommands};
+use crate::lane::{
+    create_lane, list_lanes, remove_lane, render_lane_table, show_lane, validate_lane_name,
+    LaneCreateRequest, LanePrAssociation, LaneType,
+};
 use crate::plan::ExecutionPlan;
 use crate::repo_status::{RepoStatusFilter, RepoStatusReport};
 use crate::spec::{read_workspace_spec, workspace_spec_path, write_workspace_spec, WorkspaceSpec};
@@ -341,6 +346,77 @@ pub async fn dispatch_command(command: Commands, verbose: bool) -> Result<()> {
                 Ok(())
             }
         },
+        Commands::Lane { command } => match command {
+            LaneCommands::Create {
+                name,
+                owner_unit,
+                lane_type,
+                repos,
+                branches,
+                shared_context,
+                private_context,
+                exec,
+                prs,
+                source,
+                parallel,
+                no_fail_fast,
+            } => {
+                let workspace_root = require_workspace_root()?;
+                validate_unit_name(&owner_unit)?;
+                validate_lane_name(&name)?;
+
+                let branch_map = parse_branch_map(branches)?;
+                let pr_associations = parse_pr_associations(prs)?;
+                let request = LaneCreateRequest {
+                    name: name.clone(),
+                    owner_unit: owner_unit.clone(),
+                    lane_type: lane_type.parse::<LaneType>()?,
+                    repos,
+                    branch_map,
+                    shared_context,
+                    private_context,
+                    exec_commands: exec,
+                    creation_source: source.unwrap_or_else(|| "manual".to_string()),
+                    pr_associations,
+                    parallel,
+                    fail_fast: !no_fail_fast,
+                };
+
+                let record = create_lane(&workspace_root, request)?;
+                println!(
+                    "Created lane '{}'\n- owner: {}\n- type: {}\n- repos: {}",
+                    record.lane_name,
+                    record.owner_unit,
+                    record.lane_type.as_str(),
+                    record.repos.join(", ")
+                );
+                Ok(())
+            }
+            LaneCommands::List { owner_unit } => {
+                let workspace_root = require_workspace_root()?;
+                if let Some(owner_unit) = &owner_unit {
+                    validate_unit_name(owner_unit)?;
+                }
+                let lanes = list_lanes(&workspace_root, owner_unit.as_deref())?;
+                println!("{}", render_lane_table(&lanes));
+                Ok(())
+            }
+            LaneCommands::Show { name, owner_unit } => {
+                let workspace_root = require_workspace_root()?;
+                validate_unit_name(&owner_unit)?;
+                validate_lane_name(&name)?;
+                println!("{}", show_lane(&workspace_root, &owner_unit, &name)?);
+                Ok(())
+            }
+            LaneCommands::Remove { name, owner_unit } => {
+                let workspace_root = require_workspace_root()?;
+                validate_unit_name(&owner_unit)?;
+                validate_lane_name(&name)?;
+                remove_lane(&workspace_root, &owner_unit, &name)?;
+                println!("Removed lane '{}' for unit '{}'", name, owner_unit);
+                Ok(())
+            }
+        },
         Commands::Spec { command } => match command {
             SpecCommands::Show => {
                 let workspace_root = require_workspace_root()?;
@@ -464,3 +540,40 @@ fn validate_unit_name(name: &str) -> Result<()> {
 
     Ok(())
 }
+
+fn parse_branch_map(entries: Vec<String>) -> Result<BTreeMap<String, String>> {
+    let mut branch_map = BTreeMap::new();
+    for entry in entries {
+        let (repo, branch) = entry
+            .split_once('=')
+            .with_context(|| format!("invalid branch mapping '{}': expected repo=branch", entry))?;
+        if repo.trim().is_empty() || branch.trim().is_empty() {
+            anyhow::bail!(
+                "invalid branch mapping '{}': repo and branch must both be non-empty",
+                entry
+            );
+        }
+        branch_map.insert(repo.trim().to_string(), branch.trim().to_string());
+    }
+    Ok(branch_map)
+}
+
+fn parse_pr_associations(entries: Vec<String>) -> Result<Vec<LanePrAssociation>> {
+    let mut prs = Vec::new();
+    for entry in entries {
+        let (repo, number) = entry
+            .split_once(':')
+            .with_context(|| format!("invalid PR association '{}': expected repo:number", entry))?;
+        if repo.trim().is_empty() {
+            anyhow::bail!("invalid PR association '{}': repo must not be empty", entry);
+        }
+        prs.push(LanePrAssociation {
+            repo: repo.trim().to_string(),
+            number: number
+                .trim()
+                .parse::<u64>()
+                .with_context(|| format!("invalid PR number in '{}'", entry))?,
+        });
+    }
+    Ok(prs)
+}
diff --git a/gr2/src/lane.rs b/gr2/src/lane.rs
new file mode 100644
index 00000000..b457012c
--- /dev/null
+++ b/gr2/src/lane.rs
@@ -0,0 +1,400 @@
+use anyhow::{Context, Result};
+use serde::{Deserialize, Serialize};
+use std::collections::{BTreeMap, BTreeSet};
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use crate::spec::{read_workspace_spec, workspace_spec_path, WorkspaceSpec};
+
+pub const LANE_SCHEMA_VERSION: u32 = 1;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct LaneRecord {
+    pub schema_version: u32,
+    pub lane_id: String,
+    pub lane_name: String,
+    pub owner_unit: String,
+    pub lane_type: LaneType,
+    pub repos: Vec<String>,
+    #[serde(default)]
+    pub branch_map: BTreeMap<String, String>,
+    pub creation_source: String,
+    pub context: LaneContextRoots,
+    pub exec_defaults: LaneExecDefaults,
+    #[serde(default)]
+    pub pr_associations: Vec<LanePrAssociation>,
+    pub recovery: LaneRecoveryState,
+}
+
+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
+#[serde(rename_all = "snake_case")]
+pub enum LaneType {
+    Home,
+    Feature,
+    Review,
+    Scratch,
+}
+
+impl LaneType {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Home => "home",
+            Self::Feature => "feature",
+            Self::Review => "review",
+            Self::Scratch => "scratch",
+        }
+    }
+}
+
+impl std::str::FromStr for LaneType {
+    type Err = anyhow::Error;
+
+    fn from_str(value: &str) -> Result<Self> {
+        match value {
+            "home" => Ok(Self::Home),
+            "feature" => Ok(Self::Feature),
+            "review" => Ok(Self::Review),
+            "scratch" => Ok(Self::Scratch),
+            other => anyhow::bail!(
+                "unknown lane type '{}': expected home, feature, review, or scratch",
+                other
+            ),
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct LaneContextRoots {
+    #[serde(default)]
+    pub shared_roots: Vec<String>,
+    #[serde(default)]
+    pub private_roots: Vec<String>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct LaneExecDefaults {
+    #[serde(default)]
+    pub commands: Vec<String>,
+    pub fail_fast: bool,
+    pub parallel: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct LanePrAssociation {
+    pub repo: String,
+    pub number: u64,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
+pub struct LaneRecoveryState {
+    #[serde(default)]
+    pub autostash_refs: BTreeMap<String, String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LaneCreateRequest {
+    pub name: String,
+    pub owner_unit: String,
+    pub lane_type: LaneType,
+    pub repos: Vec<String>,
+    pub branch_map: BTreeMap<String, String>,
+    pub shared_context: Vec<String>,
+    pub private_context: Vec<String>,
+    pub exec_commands: Vec<String>,
+    pub creation_source: String,
+    pub pr_associations: Vec<LanePrAssociation>,
+    pub parallel: bool,
+    pub fail_fast: bool,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LaneSummary {
+    pub owner_unit: String,
+    pub lane_name: String,
+    pub lane_type: LaneType,
+    pub repo_count: usize,
+}
+
+pub fn create_lane(workspace_root: &Path, request: LaneCreateRequest) -> Result<LaneRecord> {
+    validate_lane_name(&request.name)?;
+    validate_lane_name(&request.owner_unit)?;
+
+    let spec = load_workspace_spec_for_lanes(workspace_root)?;
+    let unit = spec
+        .units
+        .iter()
+        .find(|unit| unit.name == request.owner_unit)
+        .with_context(|| format!("unit '{}' not found in workspace spec", request.owner_unit))?;
+
+    let known_repos = spec
+        .repos
+        .iter()
+        .map(|repo| repo.name.clone())
+        .collect::<BTreeSet<_>>();
+
+    let mut repos = if request.repos.is_empty() {
+        unit.repos.clone()
+    } else {
+        request.repos.clone()
+    };
+    repos.sort();
+    repos.dedup();
+
+    if repos.is_empty() {
+        anyhow::bail!(
+            "lane '{}' has no repo membership; pass --repo or add repos to unit '{}' in workspace spec",
+            request.name,
+            request.owner_unit
+        );
+    }
+
+    for repo in &repos {
+        if !known_repos.contains(repo) {
+            anyhow::bail!("lane '{}' references unknown repo '{}'", request.name, repo);
+        }
+    }
+
+    for repo in request.branch_map.keys() {
+        if !repos.iter().any(|member| member == repo) {
+            anyhow::bail!(
+                "lane '{}' branch map references repo '{}' outside lane membership",
+                request.name,
+                repo
+            );
+        }
+    }
+
+    for pr in &request.pr_associations {
+        if !repos.iter().any(|repo| repo == &pr.repo) {
+            anyhow::bail!(
+                "lane '{}' PR association references repo '{}' outside lane membership",
+                request.name,
+                pr.repo
+            );
+        }
+    }
+
+    let metadata_path = lane_metadata_path(workspace_root, &request.owner_unit, &request.name);
+    if metadata_path.exists() {
+        anyhow::bail!(
+            "lane '{}' for unit '{}' already exists",
+            request.name,
+            request.owner_unit
+        );
+    }
+
+    let lane_root = lane_root_path(workspace_root, &request.owner_unit, &request.name);
+    fs::create_dir_all(lane_root.join("repos"))
+        .with_context(|| format!("create lane repos directory {}", lane_root.display()))?;
+    fs::create_dir_all(lane_root.join("context"))
+        .with_context(|| format!("create lane context directory {}", lane_root.display()))?;
+    fs::create_dir_all(
+        metadata_path
+            .parent()
+            .context("lane metadata parent missing")?,
+    )
+    .with_context(|| format!("create lane state directory {}", metadata_path.display()))?;
+
+    let shared_roots = merge_roots(
+        vec!["config".to_string(), ".grip/context/shared".to_string()],
+        request.shared_context,
+    );
+    let private_roots = merge_roots(
+        vec![
+            format!("agents/{}/home/context", request.owner_unit),
+            format!(
+                "agents/{}/lanes/{}/context",
+                request.owner_unit, request.name
+            ),
+        ],
+        request.private_context,
+    );
+
+    let record = LaneRecord {
+        schema_version: LANE_SCHEMA_VERSION,
+        lane_id: format!("{}:{}", request.owner_unit, request.name),
+        lane_name: request.name,
+        owner_unit: request.owner_unit,
+        lane_type: request.lane_type,
+        repos,
+        branch_map: request.branch_map,
+        creation_source: request.creation_source,
+        context: LaneContextRoots {
+            shared_roots,
+            private_roots,
+        },
+        exec_defaults: LaneExecDefaults {
+            commands: request.exec_commands,
+            fail_fast: request.fail_fast,
+            parallel: request.parallel,
+        },
+        pr_associations: request.pr_associations,
+        recovery: LaneRecoveryState::default(),
+    };
+
+    let content = toml::to_string_pretty(&record).context("serialize lane record")?;
+    fs::write(&metadata_path, content)
+        .with_context(|| format!("write lane metadata to {}", metadata_path.display()))?;
+
+    Ok(record)
+}
+
+pub fn list_lanes(workspace_root: &Path, owner_filter: Option<&str>) -> Result<Vec<LaneSummary>> {
+    let state_root = lane_state_root(workspace_root);
+    if !state_root.exists() {
+        return Ok(Vec::new());
+    }
+
+    let mut lanes = Vec::new();
+    for owner_entry in fs::read_dir(&state_root)? {
+        let owner_entry = owner_entry?;
+        if !owner_entry.file_type()?.is_dir() {
+            continue;
+        }
+
+        let owner_unit = owner_entry.file_name().to_string_lossy().into_owned();
+        if let Some(filter) = owner_filter {
+            if filter != owner_unit {
+                continue;
+            }
+        }
+
+        for lane_entry in fs::read_dir(owner_entry.path())? {
+            let lane_entry = lane_entry?;
+            if !lane_entry.file_type()?.is_file() {
+                continue;
+            }
+
+            if lane_entry.path().extension().and_then(|ext| ext.to_str()) != Some("toml") {
+                continue;
+            }
+
+            let record = load_lane_record_path(&lane_entry.path())?;
+            lanes.push(LaneSummary {
+                owner_unit: record.owner_unit,
+                lane_name: record.lane_name,
+                lane_type: record.lane_type,
+                repo_count: record.repos.len(),
+            });
+        }
+    }
+
+    lanes.sort_by(|left, right| {
+        left.owner_unit
+            .cmp(&right.owner_unit)
+            .then_with(|| left.lane_name.cmp(&right.lane_name))
+    });
+    Ok(lanes)
+}
+
+pub fn show_lane(workspace_root: &Path, owner_unit: &str, lane_name: &str) -> Result<String> {
+    let path = lane_metadata_path(workspace_root, owner_unit, lane_name);
+    fs::read_to_string(&path).with_context(|| format!("read lane metadata from {}", path.display()))
+}
+
+pub fn remove_lane(workspace_root: &Path, owner_unit: &str, lane_name: &str) -> Result<()> {
+    let metadata_path = lane_metadata_path(workspace_root, owner_unit, lane_name);
+    if !metadata_path.exists() {
+        anyhow::bail!("lane '{}' for unit '{}' not found", lane_name, owner_unit);
+    }
+
+    fs::remove_file(&metadata_path)
+        .with_context(|| format!("remove lane metadata {}", metadata_path.display()))?;
+
+    let owner_state_root = lane_state_root(workspace_root).join(owner_unit);
+    if owner_state_root.exists() && owner_state_root.read_dir()?.next().is_none() {
+        fs::remove_dir(&owner_state_root).with_context(|| {
+            format!(
+                "remove empty lane owner state {}",
+                owner_state_root.display()
+            )
+        })?;
+    }
+
+    let lane_root = lane_root_path(workspace_root, owner_unit, lane_name);
+    if lane_root.exists() {
+        fs::remove_dir_all(&lane_root)
+            .with_context(|| format!("remove lane root {}", lane_root.display()))?;
+    }
+
+    Ok(())
+}
+
+pub fn render_lane_table(lanes: &[LaneSummary]) -> String {
+    if lanes.is_empty() {
+        return "No gr2 lanes registered.".to_string();
+    }
+
+    let mut out = String::from("Lanes\nOWNER NAME TYPE REPOS\n");
+    for lane in lanes {
+        out.push_str(&format!(
+            "{} {} {} {}\n",
+            lane.owner_unit,
+            lane.lane_name,
+            lane.lane_type.as_str(),
+            lane.repo_count
+        ));
+    }
+    out.trim_end().to_string()
+}
+
+fn load_workspace_spec_for_lanes(workspace_root: &Path) -> Result<WorkspaceSpec> {
+    let spec_path = workspace_spec_path(workspace_root);
+    if spec_path.exists() {
+        read_workspace_spec(workspace_root)
+    } else {
+        WorkspaceSpec::from_workspace(workspace_root)
+    }
+}
+
+fn load_lane_record_path(path: &Path) -> Result<LaneRecord> {
+    let content = fs::read_to_string(path)
+        .with_context(|| format!("read lane metadata from {}", path.display()))?;
+    toml::from_str(&content).context("parse lane metadata")
+}
+
+fn merge_roots(defaults: Vec<String>, extras: Vec<String>) -> Vec<String> {
+    let mut merged = defaults;
+    for extra in extras {
+        if !merged.iter().any(|existing| existing == &extra) {
+            merged.push(extra);
+        }
+    }
+    merged
+}
+
+pub fn lane_state_root(workspace_root: &Path) -> PathBuf {
+    workspace_root.join(".grip/state/lanes")
+}
+
+pub fn lane_metadata_path(workspace_root: &Path, owner_unit: &str, lane_name: &str) -> PathBuf {
+    lane_state_root(workspace_root)
+        .join(owner_unit)
+        .join(format!("{}.toml", lane_name))
+}
+
+pub fn lane_root_path(workspace_root: &Path, owner_unit: &str, lane_name: &str) -> PathBuf {
+    workspace_root
+        .join("agents")
+        .join(owner_unit)
+        .join("lanes")
+        .join(lane_name)
+}
+
+pub fn validate_lane_name(name: &str) -> Result<()> {
+    if name.is_empty() {
+        anyhow::bail!("lane name must not be empty");
+    }
+
+    if !name
+        .chars()
+        .all(|ch| ch.is_ascii_alphanumeric() || ch == '_' || ch == '-' || ch == '.')
+    {
+        anyhow::bail!(
+            "invalid lane name '{}': use only ASCII letters, numbers, '.', '_' or '-'",
+            name
+        );
+    }
+
+    Ok(())
+}
diff --git a/gr2/src/lib.rs b/gr2/src/lib.rs
index 2c0c1d61..a7473004 100644
--- a/gr2/src/lib.rs
+++ b/gr2/src/lib.rs
@@ -4,6 +4,7 @@
 
 pub mod args;
 pub mod dispatch;
+pub mod lane;
 pub mod plan;
 pub mod repo_status;
 pub mod spec;
diff --git a/tests/cli_tests.rs b/tests/cli_tests.rs
index 4c2705db..7f5b5ac4 100644
--- a/tests/cli_tests.rs
+++ b/tests/cli_tests.rs
@@ -3156,3 +3156,313 @@ repos = ["myrepo"]
         .success()
         .stdout(predicate::str::contains("no changes required"));
 }
+
+#[test]
+fn test_gr2_lane_create_persists_metadata_and_scaffolds_lane_root() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "app", "https://example.com/app.git"])
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .args(["unit", "add", "atlas"])
+        .assert()
+        .success();
+
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://example.com/app.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app"]
+"#,
+    )
+    .unwrap();
+
+    let mut create = Command::cargo_bin("gr2").unwrap();
+    create
+        .current_dir(&workspace_root)
+        .args([
+            "lane",
+            "create",
+            "feat-123",
+            "--owner-unit",
+            "atlas",
+            "--type",
+            "feature",
+            "--branch",
+            "app=feat-123",
+            "--exec",
+            "cargo test -p app",
+        ])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Created lane 'feat-123'"))
+        .stdout(predicate::str::contains("repos: app"));
+
+    let metadata_path = workspace_root.join(".grip/state/lanes/atlas/feat-123.toml");
+    assert!(metadata_path.exists());
+    let metadata = std::fs::read_to_string(&metadata_path).unwrap();
+    assert!(metadata.contains("lane_id = \"atlas:feat-123\""));
+    assert!(metadata.contains("lane_name = \"feat-123\""));
+    assert!(metadata.contains("owner_unit = \"atlas\""));
+    assert!(metadata.contains("lane_type = \"feature\""));
+    assert!(metadata.contains("repos = [\"app\"]"));
+    assert!(metadata.contains("app = \"feat-123\""));
+    assert!(metadata.contains("commands = [\"cargo test -p app\"]"));
+
+    assert!(workspace_root
+        .join("agents/atlas/lanes/feat-123/repos")
+        .is_dir());
+    assert!(workspace_root
+        .join("agents/atlas/lanes/feat-123/context")
+        .is_dir());
+}
+
+#[test]
+fn test_gr2_lane_list_and_show_report_persisted_lane() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "app", "https://example.com/app.git"])
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .args(["unit", "add", "atlas"])
+        .assert()
+        .success();
+
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://example.com/app.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app"]
+"#,
+    )
+    .unwrap();
+
+    let mut create = Command::cargo_bin("gr2").unwrap();
+    create
+        .current_dir(&workspace_root)
+        .args([
+            "lane",
+            "create",
+            "review-548",
+            "--owner-unit",
+            "atlas",
+            "--type",
+            "review",
+            "--repo",
+            "app",
+            "--pr",
+            "app:548",
+        ])
+        .assert()
+        .success();
+
+    let mut list = Command::cargo_bin("gr2").unwrap();
+    list.current_dir(&workspace_root)
+        .args(["lane", "list"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("Lanes"))
+        .stdout(predicate::str::contains("atlas review-548 review 1"));
+
+    let mut show = Command::cargo_bin("gr2").unwrap();
+    show.current_dir(&workspace_root)
+        .args(["lane", "show", "review-548", "--owner-unit", "atlas"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("lane_name = \"review-548\""))
+        .stdout(predicate::str::contains("number = 548"));
+}
+
+#[test]
+fn test_gr2_lane_remove_deletes_metadata_and_lane_root() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut repo_add = Command::cargo_bin("gr2").unwrap();
+    repo_add
+        .current_dir(&workspace_root)
+        .args(["repo", "add", "app", "https://example.com/app.git"])
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .args(["unit", "add", "atlas"])
+        .assert()
+        .success();
+
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://example.com/app.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app"]
+"#,
+    )
+    .unwrap();
+
+    let mut create = Command::cargo_bin("gr2").unwrap();
+    create
+        .current_dir(&workspace_root)
+        .args([
+            "lane",
+            "create",
+            "scratch-a",
+            "--owner-unit",
+            "atlas",
+            "--type",
+            "scratch",
+        ])
+        .assert()
+        .success();
+
+    let metadata_path = workspace_root.join(".grip/state/lanes/atlas/scratch-a.toml");
+    let lane_root = workspace_root.join("agents/atlas/lanes/scratch-a");
+    assert!(metadata_path.exists());
+    assert!(lane_root.exists());
+
+    let mut remove = Command::cargo_bin("gr2").unwrap();
+    remove
+        .current_dir(&workspace_root)
+        .args(["lane", "remove", "scratch-a", "--owner-unit", "atlas"])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains(
+            "Removed lane 'scratch-a' for unit 'atlas'",
+        ));
+
+    assert!(!metadata_path.exists());
+    assert!(!lane_root.exists());
+}
+
+#[test]
+fn test_gr2_lane_create_rejects_unknown_repo_membership() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .args(["unit", "add", "atlas"])
+        .assert()
+        .success();
+
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+"#,
+    )
+    .unwrap();
+
+    let mut create = Command::cargo_bin("gr2").unwrap();
+    create
+        .current_dir(&workspace_root)
+        .args([
+            "lane",
+            "create",
+            "feat-unknown",
+            "--owner-unit",
+            "atlas",
+            "--repo",
+            "missing",
+        ])
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("unknown repo 'missing'"));
+}

From dd391bce7d26aab5c296d9da78c28127634a84be Mon Sep 17 00:00:00 2001
From: Layne Penney <dev@layne.pro>
Date: Sun, 12 Apr 2026 07:52:11 -0500
Subject: [PATCH 13/15] docs: ratify gr2 UX model and workflow (#557)

---
 docs/ASSESS-gr2-lanes-cross-mode-stress.md   | 257 +++++++++++++++++++
 docs/ASSESS-gr2-shared-scratchpads-stress.md | 184 +++++++++++++
 docs/MANIFESTO-gr2-ux.md                     | 194 ++++++++++++++
 docs/PLAN-gr2-needs-and-criteria.md          | 148 ++++++++++-
 docs/PLAN-gr2-repo-maintenance-and-lanes.md  |  50 +++-
 docs/PLAN-gr2-shared-scratchpads.md          | 140 ++++++++++
 6 files changed, 967 insertions(+), 6 deletions(-)
 create mode 100644 docs/ASSESS-gr2-lanes-cross-mode-stress.md
 create mode 100644 docs/ASSESS-gr2-shared-scratchpads-stress.md
 create mode 100644 docs/MANIFESTO-gr2-ux.md
 create mode 100644 docs/PLAN-gr2-shared-scratchpads.md

diff --git a/docs/ASSESS-gr2-lanes-cross-mode-stress.md b/docs/ASSESS-gr2-lanes-cross-mode-stress.md
new file mode 100644
index 00000000..75872c0f
--- /dev/null
+++ b/docs/ASSESS-gr2-lanes-cross-mode-stress.md
@@ -0,0 +1,257 @@
+# gr2 Lane Model Cross-Mode Stress Matrix
+
+## Purpose
+
+This is the adversarial verification matrix for the lane model itself.
+
+`gr2` is not only a multi-repo tool. It is the operating surface for:
+
+- a solo human
+- a single agent
+- multiple agents working in parallel
+- mixed human + agent collaboration
+
+The lane model is only credible if it holds under all four modes when users
+are interrupted, confused, concurrent, or partially out of sync.
+
+This document is intentionally hostile to the happy path.
+
+## Core Stress Dimensions
+
+Every lane design or implementation change should be tested against at least
+these dimensions:
+
+- recovery after interruption
+- current-context ambiguity
+- cross-lane contamination
+- concurrent mutation
+- private/shared boundary erosion
+- machine-readable status quality
+- wrong-surface choice
+- stale lane cleanup
+- review isolation
+- escalation path to PR or durable implementation
+
+## Solo Human Scenarios
+
+### 1. Multiple active features plus one review lane
+
+Scenario:
+- user has three feature lanes open
+- user switches to a review lane to inspect a PR
+- later they forget which feature lane they were in before the review
+
+What can break:
+- the lane model becomes cognitively expensive
+- review work disrupts the main task
+- users fall back to ad hoc notes or shell history to recover state
+
+What `gr2` must make obvious:
+- current lane
+- most recently active lanes
+- branch intent per lane
+- repo set per lane
+- an explicit "return to previous lane" path
+
+### 2. Human starts a second feature while the first waits on review
+
+Scenario:
+- feature A spans three repos and is waiting on peer review
+- user starts feature B in two of the same repos
+
+What can break:
+- branch confusion across repos
+- fear that new work will disturb the reviewable state of feature A
+
+What `gr2` must guarantee:
+- feature lanes stay isolated
+- branch intent is visible per lane
+- switching lanes does not require understanding cache internals
+
+### 3. Human forgets whether a command should run in home or feature lane
+
+Scenario:
+- user returns after an interruption
+- they know what they want to test, but not which lane owns the work
+
+What can break:
+- commands run in the wrong checkout
+- users stop trusting lane-aware execution
+
+What `gr2` must provide:
+- one obvious lane status surface
+- one obvious execution status surface
+- enough next-step guidance to recover without spelunking the filesystem
+
+## Single-Agent Scenarios
+
+### 4. Agent is interrupted mid-task and must context-switch
+
+Scenario:
+- agent is mid-task in a feature lane
+- a new prompt arrives and requires immediate work in another lane
+
+What can break:
+- agent loses its original working context
+- agent resumes in the wrong lane later
+- machine-readable state is too weak to recover deterministically
+
+What `gr2` must provide:
+- explicit current-lane status
+- explicit recent-lane status
+- machine-readable branch intent and repo membership
+- deterministic lane re-entry
+
+### 5. Agent must decide whether to use a feature lane, review lane, or scratchpad
+
+Scenario:
+- prompt asks for review, design, or implementation work
+- agent has to choose a surface quickly
+
+What can break:
+- wrong-surface choice
+- review work begins in a feature lane
+- implementation begins in a scratchpad
+
+What `gr2` must provide:
+- strong recommendation surface
+- clear distinctions between lane types
+- structured output that can drive agent behavior without free-form guessing
+
+### 6. Agent needs to report status without prose reconstruction
+
+Scenario:
+- supervising human or another agent asks what the current lane state is
+
+What can break:
+- status becomes a prose summary instead of a durable machine-readable fact
+
+What `gr2` must provide:
+- lane state in stable structured output
+- repo set, branch intent, PR association, and execution defaults
+- enough state for another worker to understand the lane without opening it
+
+## Multi-Agent Scenarios
+
+### 7. Two agents create different lanes that touch the same repo
+
+Scenario:
+- Atlas creates `feature/gr2-exec`
+- Apollo creates `feature/gr2-materialize`
+- both lanes include `grip`
+
+What can break:
+- cross-lane interference through shared active workspaces
+- unclear ownership of repo mutations
+- accidental reuse of one agent's private checkout
+
+What `gr2` must guarantee:
+- lane ownership remains explicit
+- each agent gets its own working surface
+- shared cache does not become shared mutable state
+
+### 8. One agent reviews while another implements
+
+Scenario:
+- Apollo is actively implementing in a feature lane
+- Atlas creates a review lane against the same repo/PR stack
+
+What can break:
+- review mutates the implementation lane
+- ownership boundaries blur
+- review lane becomes an unofficial shared worktree
+
+What `gr2` must guarantee:
+- review lane is isolated and disposable
+- workspace-level discovery exists without sharing working directories
+
+### 9. Agent handoff between workers
+
+Scenario:
+- one agent stops mid-lane
+- another agent needs to understand the lane state and continue or review it
+
+What can break:
+- lane is understandable only via chat memory
+- ownership transfer becomes filesystem archaeology
+
+What `gr2` must provide:
+- workspace-level discovery
+- explicit unit ownership
+- machine-readable lane summary
+- explicit distinction between "resume in your own lane" and "inspect theirs"
+
+## Mixed Human + Agent Scenarios
+
+### 10. Human edits in a lane while an agent tries to execute in the same lane
+
+Scenario:
+- human is editing in a feature lane
+- agent tries to run lane-aware exec against that same lane
+
+What can break:
+- hidden concurrent mutation
+- trust collapse around agent actions
+
+What `gr2` must answer explicitly:
+- is same-lane concurrent execution allowed?
+- if not, how is it blocked or redirected?
+- if yes, what safety contract exists?
+
+The default should favor safety and explicit conflict over silent concurrency.
+
+### 11. Human wants help without giving up private working space
+
+Scenario:
+- human is implementing in a lane
+- they want an agent to assist on related docs, verification, or review work
+
+What can break:
+- agent must enter the human's lane to help
+- private-workspace boundaries erode
+
+What `gr2` must provide:
+- shared scratchpad for lightweight collaboration
+- review lane for PR/inspection work
+- clear rule that private implementation lanes stay private
+
+### 12. Human and agent both lose track of the canonical context
+
+Scenario:
+- human thinks feature work lives in lane A
+- agent thinks lane B is current because it was the last machine-visible lane
+
+What can break:
+- conflicting assumptions about where work lives
+- commands and edits target the wrong lane
+
+What `gr2` must provide:
+- explicit current context markers
+- explicit lane summaries for both human-readable and machine-readable use
+- no hidden ambient lane inference that only one side can see
+
+## Failure Criteria
+
+The lane model is not ready if any of these remain fuzzy:
+
+- how a user recovers the lane they were in before an interruption
+- how an agent deterministically reports and resumes lane context
+- how same-repo parallelism across agents stays isolated
+- how mixed human + agent use avoids shared mutable lane state
+- how users distinguish feature lanes, review lanes, and scratchpads under time pressure
+
+If those answers are not obvious in both human-readable and machine-readable
+surfaces, the model still needs prototype work before more build surface lands.
+
+## Verification Gate
+
+Before lane-heavy build work is treated as stable, we should be able to point
+to repeatable prototype checks for:
+
+- solo human recovery
+- single-agent interruption and resume
+- multi-agent same-repo parallelism
+- mixed human + agent same-lane conflict handling
+
+Until then, lane design should still be treated as under verification rather
+than settled.
diff --git a/docs/ASSESS-gr2-shared-scratchpads-stress.md b/docs/ASSESS-gr2-shared-scratchpads-stress.md
new file mode 100644
index 00000000..817edd47
--- /dev/null
+++ b/docs/ASSESS-gr2-shared-scratchpads-stress.md
@@ -0,0 +1,184 @@
+# gr2 Shared Scratchpads Stress Matrix
+
+## Purpose
+
+This is the break-case matrix for the shared scratchpad prototype.
+
+The prototype is not "verified" because the happy path worked once.
+It is only verified if it survives the scenarios most likely to fail in
+real human + agent workflows.
+
+This document is intentionally adversarial.
+
+## Stress Dimensions
+
+Every new `gr2` surface should be pressured along at least these dimensions:
+
+- concurrency
+- stale metadata
+- ambiguous ownership
+- partial cleanup
+- wrong-surface use
+- escalation path to PR / implementation lane
+- recovery after interruption
+- discoverability under pressure
+
+## Shared Scratchpad Scenarios
+
+### 1. Two users edit at once
+
+Scenario:
+- Atlas and Layne both use the same doc scratchpad
+- both update the same draft in close succession
+
+What can break:
+- participants are recorded, but the workflow gives no clue how to coordinate
+- a scratchpad quietly becomes a conflict zone
+
+What the prototype must answer:
+- does the metadata make shared ownership explicit?
+- is the scratchpad clearly marked as shared rather than private?
+- is there a legible next-step path when coordination is needed?
+
+### 2. Scratchpad goes stale
+
+Scenario:
+- a blog draft scratchpad is created
+- no one touches it for a week
+- a new worker sees it later
+
+What can break:
+- no one knows if it is still active
+- stale drafts clutter the workspace
+
+Required design pressure:
+- lifecycle state must be visible
+- the model needs a pause/done path
+- stale scratchpads must be distinguishable from active ones
+
+### 3. Scratchpad scope creep into implementation
+
+Scenario:
+- users start dropping code or repo-specific implementation into a doc-first scratchpad
+
+What can break:
+- the scratchpad becomes an unofficial shared coding area
+- private-lane boundaries erode
+
+Required design pressure:
+- doc-first scope must stay explicit
+- the system must make it obvious that this is not a private feature lane
+- there should be a clear escalation path into a real lane or PR
+
+### 4. Wrong tool chosen
+
+Scenario:
+- user should have used a review lane, but instead creates a scratchpad
+- or should have used a scratchpad, but opens a PR too early
+
+What can break:
+- the tool surface becomes confusing
+- users stop trusting the model
+
+Required design pressure:
+- next-step guidance should help distinguish:
+  - private lane
+  - review lane
+  - shared scratchpad
+  - PR
+
+### 5. Missing or wrong participants
+
+Scenario:
+- scratchpad is created without the right people listed
+- later a third worker joins
+
+What can break:
+- implied ownership diverges from recorded ownership
+- people edit without being visible in metadata
+
+Required design pressure:
+- participant list must be editable
+- participant visibility must be cheap
+- absence of participants should not imply private ownership
+
+### 6. Scratchpad linked to the wrong issue or no issue
+
+Scenario:
+- scratchpad is linked to the wrong issue
+- or there is no linked issue yet
+
+What can break:
+- scratchpad loses traceability
+- coordination falls back into chat memory
+
+Required design pressure:
+- refs should be optional but visible
+- it should be easy to add or fix refs later
+
+### 7. Scratchpad completed, but content needs to graduate
+
+Scenario:
+- draft blog post is approved
+- now it needs to become a proper repo artifact and PR
+
+What can break:
+- there is no obvious promotion path
+- content gets stranded in the shared scratchpad
+
+Required design pressure:
+- the model needs a clear handoff path:
+  - scratchpad -> repo file -> PR
+
+### 8. Partial cleanup
+
+Scenario:
+- scratchpad metadata is removed, but docs remain
+- or docs are removed, but metadata remains
+
+What can break:
+- orphaned shared state
+- misleading listings
+
+Required design pressure:
+- cleanup needs to be explicit and symmetric
+- the status surface must expose orphaned scratchpads
+
+### 9. Discoverability under time pressure
+
+Scenario:
+- user just wants to collaborate on a blog now
+- they should not have to reverse-engineer the whole workspace model
+
+What can break:
+- the feature is technically correct but too cognitively expensive
+
+Required design pressure:
+- one obvious create path
+- one obvious list path
+- one obvious "what now?" path
+
+### 10. Private-workspace safety regression
+
+Scenario:
+- users begin treating scratchpads as permission to work in each other's spaces again
+
+What can break:
+- the original safety model regresses
+
+Required design pressure:
+- shared scratchpads must be framed as workspace-owned collaboration surfaces
+- they must not blur into private lanes
+
+## Gate Before MVP
+
+Before `grip#553` should be considered ready to build or finalize, we should be
+able to answer these questions clearly:
+
+- how is a scratchpad different from a review lane?
+- how is a scratchpad different from a PR?
+- how is a scratchpad kept from turning into shared implementation sprawl?
+- how does a stale scratchpad become visible and cleanable?
+- how does content graduate from scratchpad to repo artifact?
+
+If those are still fuzzy, the prototype is not ready for MVP.
diff --git a/docs/MANIFESTO-gr2-ux.md b/docs/MANIFESTO-gr2-ux.md
new file mode 100644
index 00000000..0cd1226d
--- /dev/null
+++ b/docs/MANIFESTO-gr2-ux.md
@@ -0,0 +1,194 @@
+# gr2 UX Manifesto
+
+## Why `gr2` Exists
+
+Developers do not struggle because git is broken.
+
+They struggle because modern work is larger than one checkout:
+
+- one feature spans multiple repositories
+- one review interrupts another active task
+- one human works alongside multiple agents
+- one team needs both private work areas and lightweight shared collaboration
+
+`gr2` exists to make that multi-repo, multi-lane reality simpler, safer, and
+more legible.
+
+## Primary Thesis
+
+`gr2` is not a git replacement.
+
+`gr2` is a multi-repo workspace router.
+
+It should make it easy to:
+
+- start the right task context
+- see which repos and branches belong to that context
+- switch to another context without losing your place
+- review, collaborate, and execute work in the right scope
+
+Once the user is in the correct checkout, normal git should still feel normal.
+
+## User-First Principles
+
+### 1. The Primary Object Is The Task Context
+
+Users think:
+
+- "I am working on feature X"
+- "I need to review PR Y"
+- "I need a shared place to draft Z"
+
+They do not think:
+
+- "I need to manually coordinate three checkouts and remember which branch is
+  active in each one"
+
+So `gr2` must center:
+
+- feature lanes
+- review lanes
+- shared scratchpads
+
+Repos are part of the context. They are not the context.
+
+Shared repo caches may exist underneath `gr2`, but they are implementation
+substrate, not the user-facing place where work is expected to happen.
+
+### 2. Private Work And Shared Work Must Stay Separate
+
+Users need both:
+
+- private implementation surfaces
+- shared collaboration surfaces
+
+Private lanes protect active work.
+Shared scratchpads make lightweight collaboration possible without violating
+private workspace boundaries or paying the full cost of a PR.
+
+The system must make that distinction explicit.
+
+### 3. Use `gr2` To Choose Context, Use Git To Work
+
+The intended user flow is:
+
+1. use `gr2` to enter the correct lane or review context
+2. use git normally inside the selected checkout
+3. return to `gr2` when changing task, scope, or execution surface
+
+If `gr2` tries to replace normal repo-local git, users will distrust it.
+If `gr2` does not simplify multi-repo context changes, users will route around
+it.
+
+### 3a. Optimization Must Stay Behind The UX
+
+If `gr2 apply` uses shared local repo caches, mirrors, or `git clone
+--reference-if-able`, that should improve speed and disk use without changing
+the user mental model.
+
+Users should not need to understand cache topology to work effectively.
+
+### 4. The Tool Must Never Hide Important State
+
+Users should not have to guess:
+
+- which repos are in scope
+- which branches are intended
+- which paths are active
+- whether a command is structural or mutating
+- whether local work is at risk
+
+`gr2` should prefer explicit status over magical convenience.
+
+### 5. Safety Beats Cleverness
+
+`gr2 apply` must not silently:
+
+- pull
+- merge
+- rebase
+- switch branches
+- discard dirty work
+
+Users will trust `gr2` only if the safety boundary is simple and consistent:
+
+- structural convergence belongs to `apply`
+- repo maintenance belongs to explicit repo commands
+
+## Human UX Requirements
+
+A human should be able to:
+
+- keep feature A active while feature B waits in review
+- inspect PR C without disturbing either one
+- collaborate on a blog post or spec without editing another person's private
+  lane
+- tell, quickly, which repos matter for the current task
+- run the right build/test commands without reconstructing scope manually
+
+The human should not need to care whether a working checkout was materialized
+from:
+
+- a shared local mirror
+- a reference clone
+- a direct remote clone
+
+## Agent UX Requirements
+
+An agent should be able to:
+
+- discover the current task context quickly
+- consume stable machine-readable state
+- know which repos matter without guessing
+- avoid entering another worker's private directory
+- choose the right next command from explicit status surfaces
+
+The agent should be able to trust that optimization layers are invisible unless
+they matter for diagnosis or repair.
+
+This means structured output is not optional polish. It is first-class product
+surface.
+
+## Mixed Human + Agent Requirements
+
+The same model must work for:
+
+- a solo human
+- one agent
+- many agents
+- one human working alongside many agents
+
+That requires:
+
+- one shared vocabulary for lanes, review, and scratchpads
+- one shared status model
+- private lanes by default
+- shared collaboration surfaces when collaboration is the point
+- cache/materialization optimization that speeds up everyone without becoming a
+  new conceptual burden
+
+## What Good Looks Like
+
+The user says:
+
+- "start feature auth across app and api"
+- "show me what this lane would run"
+- "open a review lane for PR 548"
+- "create a shared scratchpad for the sprint blog"
+- "switch back to my feature without losing my place"
+
+And the system responds with explicit, trustworthy state.
+
+That is the bar.
+
+## Product Test
+
+When choosing a `gr2` feature, ask:
+
+1. Does this make multi-repo context easier than ad hoc shell plus raw git?
+2. Does this preserve private work while allowing shared collaboration?
+3. Does this make the active task more legible?
+4. Does this reduce guessing for both humans and agents?
+5. Does this keep git normal once the user is in the correct checkout?
+
+If the answer is not clearly yes, the design should be revised.
diff --git a/docs/PLAN-gr2-needs-and-criteria.md b/docs/PLAN-gr2-needs-and-criteria.md
index 270b2a60..0e69cf5e 100644
--- a/docs/PLAN-gr2-needs-and-criteria.md
+++ b/docs/PLAN-gr2-needs-and-criteria.md
@@ -12,6 +12,35 @@ workspace that must work for:
 It is not a feature wishlist. It is the rulebook for what the workspace must
 be able to do without unsafe workarounds.
 
+## Development Workflow
+
+`gr2` should be developed with this sequence:
+
+- design
+- prototype
+- verify
+- repeat that loop until the shape holds
+- build
+- assess
+- repeat for the next slice
+
+The shorthand is:
+
+- `(design -> prototype -> verify)^n`
+- `build`
+- `assess`
+- `repeat`
+
+For `gr2`, verification is not just a happy-path demo. It includes:
+
+- adversarial scenarios
+- real git behavior
+- user-mode checks across solo human, single agent, multi-agent, and mixed
+  human + agent workflows
+
+The lane model should be pressure-tested with the cross-mode matrix in
+`ASSESS-gr2-lanes-cross-mode-stress.md`, not only per-mode happy paths.
+
 ## Primary Design Principle
 
 The workspace unit is not a single repo checkout.
@@ -41,6 +70,10 @@ The user needs to:
 - start a second feature while the first waits on review
 - run build/test/verify for the active multi-repo lane
 
+The solo human should not need to understand or manage a shared repo cache.
+If clone acceleration exists, it should feel like faster materialization, not a
+second workspace concept.
+
 ### Single Agent
 
 The agent needs to:
@@ -51,6 +84,10 @@ The agent needs to:
 - report deterministic status
 - avoid clobbering unrelated work
 
+The agent should receive explicit status about active working checkouts, not be
+forced to reason about cache internals unless a clone/materialization problem
+actually occurs.
+
 ### Multi-Agent Team
 
 The team needs to:
@@ -61,6 +98,24 @@ The team needs to:
 - coordinate across linked PRs and sprint lanes
 - switch between tasks without contaminating each other's state
 
+The team should benefit from shared clone acceleration, but the optimization
+must not weaken private-workspace boundaries or turn `repos/<repo>` into a
+confusing second place where work might be happening.
+
+### Mixed Human + Agent
+
+The mixed mode is not a special edge case. It is a primary operating mode.
+
+The workspace needs to let a human and an agent collaborate without either of
+them needing to enter the other's private lane to get work done.
+
+That implies:
+
+- private implementation lanes remain private
+- shared scratchpads are workspace-owned
+- review lanes are disposable and isolated
+- status surfaces must work for both human readers and machine consumers
+
 ## Hard Requirements
 
 ### 1. Structural and Repo-State Separation
@@ -118,6 +173,8 @@ That implies:
 
 If lane creation is slow or expensive, users will bypass the model.
 
+The cache is an implementation detail. The UX object remains the lane.
+
 ### 4. Shared and Private Context
 
 The workspace must support two context scopes:
@@ -178,6 +235,21 @@ That means:
 - review lanes can run their own commands
 - review lanes do not mutate the current feature lane
 
+### 8. Cross-Mode Recovery And Concurrency
+
+The lane model must hold under interruption and concurrency across all user
+modes.
+
+That includes:
+
+- solo-human lane recovery after review interruptions
+- single-agent context switching under new prompts
+- multi-agent same-repo parallel work
+- mixed human + agent same-lane conflict handling
+
+The adversarial lane matrix in `ASSESS-gr2-lanes-cross-mode-stress.md` is part
+of the verification gate for this requirement.
+
 ### 8. Cross-Repo Feature Coherence
 
 A cross-repo feature must be representable as one lane record, not merely
@@ -203,9 +275,83 @@ Agents and humans need trustworthy read surfaces.
 - execution status
 - PR linkage
 
+Cache or transport state should only surface when it affects the user's ability
+to materialize or repair a lane.
+
 These should be machine-readable as well as human-readable.
 
-### 10. Multi-Repo Scratchpads
+### 9a. Structured Output Must Be First-Class
+
+Machine-readable output should not be treated as an optional afterthought.
+
+Agents routinely need:
+
+- stable field names
+- stable object shapes
+- deterministic exit codes
+- explicit next-step hints
+
+So every status-style surface should support structured output as a first-class
+mode, not a best-effort pretty-print after the human CLI is finished.
+
+Required properties:
+
+- all read surfaces support structured output
+- structured output is versioned
+- field names are stable across patch releases
+- error output is also structured when structured mode is enabled
+- command scope is explicit in the payload
+
+Examples of required structured surfaces:
+
+- `gr2 spec show`
+- `gr2 plan`
+- `gr2 repo status`
+- `gr2 lane list`
+- `gr2 lane show`
+- `gr2 exec status`
+
+The target user problem is simple:
+
+- agents should not have to scrape prose
+- humans should not lose readable output by default
+
+### 10. Materialization Optimization Must Not Become A Second UX Model
+
+`gr2 apply` may use shared local mirrors or reference clones as its materialization
+substrate.
+
+That is desirable for:
+
+- speed
+- disk reuse
+- cheap review lanes
+- adoptability on large workspaces
+
+But the optimization must not become a user-facing mental model.
+
+Required rule:
+
+- users work in unit-local or lane-local checkouts
+- `.grip/cache/repos/` is infrastructure
+- status surfaces should describe active working checkouts first
+
+If the design makes users reason about shared cache topology during normal work,
+the UX has failed.
+
+### 11. Strong UX Guidance
+
+The product must teach the user which surface to use.
+
+That means:
+
+- CLI help must state command scope clearly
+- status output should suggest likely next steps
+- docs should include "use `gr2` for this, use git for that"
+- common workflows should be expressed as short procedural paths
+- structured output should be easy to enable and hard to forget
+
+### 12. Multi-Repo Scratchpads
 
 The system must support two or more temporary scratchpads simultaneously.
 
diff --git a/docs/PLAN-gr2-repo-maintenance-and-lanes.md b/docs/PLAN-gr2-repo-maintenance-and-lanes.md
index 87b3aba9..0dab62ef 100644
--- a/docs/PLAN-gr2-repo-maintenance-and-lanes.md
+++ b/docs/PLAN-gr2-repo-maintenance-and-lanes.md
@@ -30,6 +30,13 @@ The workspace model needs to support:
 - shared team context plus unit-specific private context
 - multi-repo build, test, and command execution scoped to a lane
 
+And it must hold under adversarial cross-mode pressure:
+
+- solo human recovery after interruption
+- single-agent context switching
+- multi-agent same-repo parallelism
+- mixed human + agent conflict handling
+
 ## Design Goals
 
 - make workspace intent explicit
@@ -42,6 +49,9 @@ The workspace model needs to support:
 - make shared context and unit-private context explicit
 - make multi-repo execution lane-aware
 
+The lane model should be validated with the cross-mode matrix in
+`ASSESS-gr2-lanes-cross-mode-stress.md`, not only by per-mode happy paths.
+
 ## Non-Goals
 
 - `gr2 apply` is not a global "make it all right somehow" button
@@ -80,6 +90,11 @@ It should not silently:
 - rebase local work
 - switch active branches unexpectedly
 
+Materialization may use a shared cache or local mirror under `.grip/cache/repos`
+to accelerate clone/setup.
+
+That is an implementation strategy, not a separate workspace surface.
+
 ### 3. Repo Maintenance
 
 Repo maintenance should be an explicit surface above structural apply:
@@ -122,19 +137,39 @@ The workspace should have three layers:
 
 ### Shared Cache
 
-`.grip/cache/repos/` stores reusable repo sources.
+`.grip/cache/repos/` stores reusable repo sources or mirrors.
 
 This is the acceleration layer:
 
-- clone once
+- fetch once
 - materialize many
 - cheap temporary sandboxes
+- reference-clone substrate for `apply`
+
+The likely implementation path is:
 
-### Shared Repos
+- maintain a shared local mirror/cache under `.grip/cache/repos/`
+- materialize unit/lane working clones from that cache with
+  `git clone --reference-if-able` or equivalent
 
-`repos/` is for shared baseline or stable workspace-level repos.
+This should improve adoptability on large workspaces without introducing a new
+user-facing concept.
 
-These are not where active feature work should live by default.
+### `repos/` Is Not The Primary Working Surface
+
+The real-git prototype currently shows that active work materializes under
+`agents/<unit>/...`, not under `repos/<repo>`.
+
+That should be treated as the primary UX model unless the implementation
+changes substantially.
+
+So:
+
+- `repos/` should not be presented as where users normally work
+- shared repo state belongs in cache/infrastructure unless a concrete UX need
+  emerges
+- unit-local and lane-local checkouts are the places users and agents actually
+  operate
 
 ### Unit Home
 
@@ -159,6 +194,11 @@ A lane contains:
 This is the multi-repo equivalent of a worktree, but not tied to git's
 single-repo worktree mechanism.
 
+For UX purposes, the important distinction is:
+
+- cache and reference clones exist to make lanes cheap
+- lanes are still the thing the user thinks in
+
 ## Context Model
 
 The workspace needs two context scopes.
diff --git a/docs/PLAN-gr2-shared-scratchpads.md b/docs/PLAN-gr2-shared-scratchpads.md
new file mode 100644
index 00000000..db3c970b
--- /dev/null
+++ b/docs/PLAN-gr2-shared-scratchpads.md
@@ -0,0 +1,140 @@
+# gr2 Shared Scratchpads
+
+## Problem
+
+Private lanes are the right default for implementation work, but they leave a
+collaboration gap:
+
+- a PR is too heavy for early drafting
+- another worker's private directory is the wrong place for joint editing
+- ad hoc shared files have weak ownership and poor lifecycle
+
+The blog workflow is the clearest example. Multiple workers may need to draft,
+review, and refine shared content before anyone wants a formal PR.
+
+## User Need
+
+"I need a lightweight shared place to collaborate without crossing into someone
+else's private workspace and without paying the full cost of a PR."
+
+## Principle
+
+Shared scratchpads are a sibling to private lanes, not an exception to them.
+
+- private lanes stay private
+- shared scratchpads are explicit shared workspace objects
+- both should be cheap
+- both should be inspectable
+
+## First Slice
+
+The first slice should be doc-first.
+
+That keeps the initial surface focused on the actual pain:
+
+- blogs
+- RFCs
+- release notes
+- planning docs
+
+It avoids turning "shared scratchpad" into an excuse for ambiguous shared code
+ownership too early.
+
+## Proposed Model
+
+```text
+<workspace>/
+├── agents/
+│   └── <unit>/
+│       └── lanes/
+│           └── ...
+└── shared/
+    └── scratchpads/
+        └── <name>/
+            ├── scratchpad.toml
+            ├── docs/
+            ├── notes/
+            └── context/
+```
+
+## Scratchpad Metadata
+
+Each shared scratchpad should record:
+
+- name
+- kind
+- purpose
+- participants
+- linked issue / PR if any
+- lifecycle state
+- creation source
+- default paths
+
+Suggested kinds for the first pass:
+
+- `doc`
+- `review`
+- `planning`
+
+Suggested lifecycle states:
+
+- `draft`
+- `active`
+- `paused`
+- `done`
+
+## Rules
+
+Shared scratchpads should:
+
+- be workspace-owned
+- support multiple named participants
+- make purpose explicit
+- be easy to create and remove
+- stay separate from private implementation lanes
+
+Shared scratchpads should not:
+
+- replace private feature lanes
+- become the default place for multi-repo coding
+- weaken the "do not enter someone else's private directory" rule
+
+## UX Goals
+
+The user should be able to:
+
+1. create a shared scratchpad quickly
+2. see who it is for
+3. see what it is for
+4. know whether it is still active
+5. know what to do next
+
+That implies explicit read surfaces:
+
+- list scratchpads
+- show one scratchpad
+- suggest next step
+
+## Prototype Goal
+
+The prototype should answer:
+
+- does a doc-first shared scratchpad actually reduce coordination friction?
+- does the metadata feel sufficient?
+- do users understand when to use a scratchpad instead of a PR or private lane?
+- does this preserve the private-workspace safety model?
+
+## Verification Gate
+
+This prototype is only considered verified if it survives the adversarial
+scenarios in:
+
+- `docs/ASSESS-gr2-shared-scratchpads-stress.md`
+
+That includes pressure around:
+
+- concurrency
+- stale state
+- wrong-surface use
+- lifecycle and cleanup
+- graduation from scratchpad to real repo artifact / PR

From 12a129343073c9ff51f76a40e2d0ceb7e584b14a Mon Sep 17 00:00:00 2001
From: Layne Penney <dev@layne.pro>
Date: Sun, 12 Apr 2026 08:57:51 -0500
Subject: [PATCH 14/15] feat: merge atlas gr2 design stack (exec surface +
 prototypes) (#558)

---
 docs/ASSESS-gr2-shared-scratchpads-stress.md  |    7 +
 docs/MANIFESTO-gr2-ux.md                      |   38 +
 docs/PLAN-gr2-needs-and-criteria.md           |  173 +--
 docs/PLAN-gr2-shared-scratchpads.md           |    7 +
 gr2/prototypes/README.md                      |  319 ++++-
 gr2/prototypes/cache_materialization_probe.py |  190 +++
 gr2/prototypes/concurrent_lease_stress.py     |  208 ++++
 gr2/prototypes/cross_mode_lane_stress.py      |  699 +++++++++++
 gr2/prototypes/lane_workspace_prototype.py    | 1077 ++++++++++++++++-
 gr2/prototypes/layout_model_probe.py          |  139 +++
 .../real_git_lane_materialization.py          |  248 ++++
 gr2/prototypes/real_git_playground.py         |  465 +++++++
 gr2/prototypes/repo_transport_probe.py        |  147 +++
 gr2/src/args.rs                               |   24 +
 gr2/src/dispatch.rs                           |   26 +-
 gr2/src/exec.rs                               |  166 +++
 gr2/src/lane.rs                               |    8 +
 gr2/src/lib.rs                                |    1 +
 tests/cli_tests.rs                            |  204 ++++
 19 files changed, 4029 insertions(+), 117 deletions(-)
 create mode 100644 gr2/prototypes/cache_materialization_probe.py
 create mode 100644 gr2/prototypes/concurrent_lease_stress.py
 create mode 100644 gr2/prototypes/cross_mode_lane_stress.py
 create mode 100644 gr2/prototypes/layout_model_probe.py
 create mode 100644 gr2/prototypes/real_git_lane_materialization.py
 create mode 100644 gr2/prototypes/real_git_playground.py
 create mode 100644 gr2/prototypes/repo_transport_probe.py
 create mode 100644 gr2/src/exec.rs

diff --git a/docs/ASSESS-gr2-shared-scratchpads-stress.md b/docs/ASSESS-gr2-shared-scratchpads-stress.md
index 817edd47..ef24783a 100644
--- a/docs/ASSESS-gr2-shared-scratchpads-stress.md
+++ b/docs/ASSESS-gr2-shared-scratchpads-stress.md
@@ -182,3 +182,10 @@ able to answer these questions clearly:
 - how does content graduate from scratchpad to repo artifact?
 
 If those are still fuzzy, the prototype is not ready for MVP.
+
+The prototype should also expose explicit operator surfaces for those cases:
+
+- a recommendation surface when the user is choosing between feature lane,
+  review lane, shared scratchpad, and PR
+- an audit surface for stale, orphaned, or weakly tracked scratchpads
+- a promotion surface that makes the handoff to repo artifact and PR explicit
diff --git a/docs/MANIFESTO-gr2-ux.md b/docs/MANIFESTO-gr2-ux.md
index 0cd1226d..315b4224 100644
--- a/docs/MANIFESTO-gr2-ux.md
+++ b/docs/MANIFESTO-gr2-ux.md
@@ -20,6 +20,12 @@ more legible.
 
 `gr2` is a multi-repo workspace router.
 
+And for Synapt, it is more than that:
+
+- `gr2` is the workspace infrastructure layer
+- Synapt org shape should compile into `gr2`
+- channels, recall, and agent lanes should feel native to the workspace
+
 It should make it easy to:
 
 - start the right task context
@@ -167,6 +173,28 @@ That requires:
 - cache/materialization optimization that speeds up everyone without becoming a
   new conceptual burden
 
+## Synapt-Native Integration Requirements
+
+`gr2` should work with Synapt out of the box.
+
+That means:
+
+- a Synapt-backed workspace should not treat channels, recall, or agent identity
+  as optional afterthoughts
+- a premium org/control-plane should compile into `WorkspaceSpec` and lane
+  policy rather than bypassing the workspace model
+- the local workspace should materialize the result of org, team, agent, and
+  access policy decisions without leaking premium-only control-plane semantics
+  into the wrong layer
+
+The user should be able to think:
+
+- "init the workspace"
+- "enter the right lane"
+- "use channels and recall in that workspace"
+
+without first assembling plugin wiring manually.
+
 ## What Good Looks Like
 
 The user says:
@@ -190,5 +218,15 @@ When choosing a `gr2` feature, ask:
 3. Does this make the active task more legible?
 4. Does this reduce guessing for both humans and agents?
 5. Does this keep git normal once the user is in the correct checkout?
+6. Does this improve the Synapt workspace model instead of working around it?
 
 If the answer is not clearly yes, the design should be revised.
+
+The four user modes are not just examples. They are the product test:
+
+- solo human
+- single agent
+- multi-agent
+- mixed human + agent
+
+If a surface works for only one of them, it is not finished.
diff --git a/docs/PLAN-gr2-needs-and-criteria.md b/docs/PLAN-gr2-needs-and-criteria.md
index 0e69cf5e..a620dee7 100644
--- a/docs/PLAN-gr2-needs-and-criteria.md
+++ b/docs/PLAN-gr2-needs-and-criteria.md
@@ -12,34 +12,8 @@ workspace that must work for:
 It is not a feature wishlist. It is the rulebook for what the workspace must
 be able to do without unsafe workarounds.
 
-## Development Workflow
-
-`gr2` should be developed with this sequence:
-
-- design
-- prototype
-- verify
-- repeat that loop until the shape holds
-- build
-- assess
-- repeat for the next slice
-
-The shorthand is:
-
-- `(design -> prototype -> verify)^n`
-- `build`
-- `assess`
-- `repeat`
-
-For `gr2`, verification is not just a happy-path demo. It includes:
-
-- adversarial scenarios
-- real git behavior
-- user-mode checks across solo human, single agent, multi-agent, and mixed
-  human + agent workflows
-
-The lane model should be pressure-tested with the cross-mode matrix in
-`ASSESS-gr2-lanes-cross-mode-stress.md`, not only per-mode happy paths.
+For Synapt, `gr2` is the workspace infrastructure layer, not just a helper
+around multi-repo git state.
 
 ## Primary Design Principle
 
@@ -57,6 +31,63 @@ If `gr2` gets that right, humans and agents can work safely in parallel.
 If it gets that wrong, users will fall back to ad hoc worktrees, raw git, and
 hidden state.
 
+## Tool Boundary Principle
+
+`gr2` is not a replacement for git.
+
+`gr2` should be the first-class surface for multi-repo workspace routing.
+Git should remain the first-class surface for normal repo-local work inside a
+chosen checkout.
+
+If that boundary gets blurred, users and agents will distrust the system for
+opposite reasons:
+
+- if `gr2` does too much, it feels magical and unsafe
+- if `gr2` does too little, users will ignore it and fall back to ad hoc shell
+
+So the system must make this split legible.
+
+## Synapt Infrastructure Principle
+
+`gr2` should be the local workspace substrate that Synapt compiles into.
+
+That means:
+
+- premium org shape compiles into `WorkspaceSpec` and lane policy
+- local workspaces materialize teams, agents, repo scope, and context surfaces
+- channels, recall, and agent lanes should feel native to the workspace model
+
+This is still compatible with the local-first split:
+
+- premium owns org identity, policy, entitlements, and coordination semantics
+- `gr2` owns local workspace materialization and lane execution surfaces
+
+But the user experience should feel integrated rather than patched together.
+
+### `gr2` Must Own
+
+- lane selection and switching
+- review-lane setup
+- shared scratchpads
+- multi-repo status and scope
+- structural workspace planning and apply
+- lane-aware execution planning
+
+### Git Must Still Own
+
+- repo-local `status`, `diff`, `log`
+- staging and committing
+- normal branch work inside one checkout
+- low-level recovery when a user is already in the correct repo
+
+### User Decision Rule
+
+The default user rule should be:
+
+1. use `gr2` to get into the right workspace context
+2. use git to work inside that chosen repo checkout
+3. return to `gr2` when changing context, scope, or execution surface
+
 ## User Modes
 
 `gr2` must support all of these without changing its core model.
@@ -69,6 +100,7 @@ The user needs to:
 - review another PR without disturbing that feature
 - start a second feature while the first waits on review
 - run build/test/verify for the active multi-repo lane
+- know when to use raw git versus `gr2` without second-guessing
 
 The solo human should not need to understand or manage a shared repo cache.
 If clone acceleration exists, it should feel like faster materialization, not a
@@ -83,6 +115,7 @@ The agent needs to:
 - branch and execute commands without guessing
 - report deterministic status
 - avoid clobbering unrelated work
+- prefer the workspace primitives over ad hoc raw git when the task is multi-repo
 
 The agent should receive explicit status about active working checkouts, not be
 forced to reason about cache internals unless a clone/materialization problem
@@ -97,6 +130,7 @@ The team needs to:
 - preserve private context where appropriate
 - coordinate across linked PRs and sprint lanes
 - switch between tasks without contaminating each other's state
+- avoid entering each other's private directories just to collaborate
 
 The team should benefit from shared clone acceleration, but the optimization
 must not weaken private-workspace boundaries or turn `repos/<repo>` into a
@@ -104,17 +138,17 @@ confusing second place where work might be happening.
 
 ### Mixed Human + Agent
 
-The mixed mode is not a special edge case. It is a primary operating mode.
+The mixed mode is a primary operating mode, not a special case.
 
 The workspace needs to let a human and an agent collaborate without either of
-them needing to enter the other's private lane to get work done.
+them needing to enter the other's private lane just to get work done.
 
-That implies:
+That requires:
 
-- private implementation lanes remain private
-- shared scratchpads are workspace-owned
-- review lanes are disposable and isolated
-- status surfaces must work for both human readers and machine consumers
+- private implementation lanes
+- shared scratchpads for lightweight collaboration
+- isolated review lanes
+- status surfaces that work for both humans and machines
 
 ## Hard Requirements
 
@@ -235,21 +269,6 @@ That means:
 - review lanes can run their own commands
 - review lanes do not mutate the current feature lane
 
-### 8. Cross-Mode Recovery And Concurrency
-
-The lane model must hold under interruption and concurrency across all user
-modes.
-
-That includes:
-
-- solo-human lane recovery after review interruptions
-- single-agent context switching under new prompts
-- multi-agent same-repo parallel work
-- mixed human + agent same-lane conflict handling
-
-The adversarial lane matrix in `ASSESS-gr2-lanes-cross-mode-stress.md` is part
-of the verification gate for this requirement.
-
 ### 8. Cross-Repo Feature Coherence
 
 A cross-repo feature must be representable as one lane record, not merely
@@ -291,6 +310,30 @@ Agents routinely need:
 - deterministic exit codes
 - explicit next-step hints
 
+### 10. Materialization Optimization Must Not Become A Second UX Model
+
+`gr2 apply` may use shared local mirrors or reference clones as its materialization
+substrate.
+
+That is desirable for:
+
+- speed
+- disk reuse
+- cheap review lanes
+- adoptability on large workspaces
+
+But the optimization must not become a user-facing mental model.
+
+Required rule:
+
+- users work in unit-local or lane-local checkouts
+- `.grip/cache/repos/` is infrastructure
+- status surfaces should describe active working checkouts first
+
+If the design makes users reason about shared cache topology during normal work,
+the UX has failed.
+- explicit scope metadata
+
 So every status-style surface should support structured output as a first-class
 mode, not a best-effort pretty-print after the human CLI is finished.
 
@@ -316,30 +359,7 @@ The target user problem is simple:
 - agents should not have to scrape prose
 - humans should not lose readable output by default
 
-### 10. Materialization Optimization Must Not Become A Second UX Model
-
-`gr2 apply` may use shared local mirrors or reference clones as its materialization
-substrate.
-
-That is desirable for:
-
-- speed
-- disk reuse
-- cheap review lanes
-- adoptability on large workspaces
-
-But the optimization must not become a user-facing mental model.
-
-Required rule:
-
-- users work in unit-local or lane-local checkouts
-- `.grip/cache/repos/` is infrastructure
-- status surfaces should describe active working checkouts first
-
-If the design makes users reason about shared cache topology during normal work,
-the UX has failed.
-
-### 11. Strong UX Guidance
+### 10. Strong UX Guidance
 
 The product must teach the user which surface to use.
 
@@ -351,7 +371,7 @@ That means:
 - common workflows should be expressed as short procedural paths
 - structured output should be easy to enable and hard to forget
 
-### 12. Multi-Repo Scratchpads
+### 11. Multi-Repo Scratchpads
 
 The system must support two or more temporary scratchpads simultaneously.
 
@@ -397,6 +417,9 @@ Required surfaces:
 - `gr2 repo sync`
 - `gr2 repo checkout`
 
+This surface must remain explicit enough that users do not confuse it with
+plain repo-local git operations.
+
 ### Lane Surface
 
 The user must be able to manage lanes directly.
diff --git a/docs/PLAN-gr2-shared-scratchpads.md b/docs/PLAN-gr2-shared-scratchpads.md
index db3c970b..7d8b0332 100644
--- a/docs/PLAN-gr2-shared-scratchpads.md
+++ b/docs/PLAN-gr2-shared-scratchpads.md
@@ -113,6 +113,8 @@ That implies explicit read surfaces:
 
 - list scratchpads
 - show one scratchpad
+- audit stale or orphaned scratchpads
+- plan promotion into a repo artifact
 - suggest next step
 
 ## Prototype Goal
@@ -123,6 +125,11 @@ The prototype should answer:
 - does the metadata feel sufficient?
 - do users understand when to use a scratchpad instead of a PR or private lane?
 - does this preserve the private-workspace safety model?
+- can the tool help the user choose between scratchpad, review lane, feature lane,
+  and PR without guesswork?
+- can the tool surface stale or weakly tracked scratchpads before they become
+  clutter or coordination debt?
+- can the tool show a clear graduation path from scratchpad to repo artifact?
 
 ## Verification Gate
 
diff --git a/gr2/prototypes/README.md b/gr2/prototypes/README.md
index 55c58632..8e8fb5d3 100644
--- a/gr2/prototypes/README.md
+++ b/gr2/prototypes/README.md
@@ -1,4 +1,4 @@
-# gr2 Repo Maintenance Prototype
+# gr2 Repo Maintenance + Collaboration Prototypes
 
 This prototype explores a split between:
 
@@ -80,6 +80,7 @@ without turning plain `gr2 apply` into an unsafe catch-all mutation command.
 - lane-local repo membership and branch map
 - shared + private context roots
 - lane-aware execution planning
+- shared scratchpads for lightweight collaboration
 
 Example:
 
@@ -91,10 +92,322 @@ python3 gr2/prototypes/lane_workspace_prototype.py plan-exec \
   /path/to/workspace atlas feat-auth 'cargo test'
 ```
 
-This prototype does not execute commands. It proves that lane metadata can
-become the durable source of truth for:
+Review lane example:
+
+```bash
+python3 gr2/prototypes/lane_workspace_prototype.py create-review-lane \
+  /path/to/workspace atlas grip 548
+```
+
+Shared scratchpad example:
+
+```bash
+python3 gr2/prototypes/lane_workspace_prototype.py create-shared-scratchpad \
+  /path/to/workspace blog-s17 \
+  --kind doc \
+  --purpose "Sprint 17 blog draft" \
+  --participant atlas \
+  --participant layne \
+  --ref grip#552
+
+python3 gr2/prototypes/lane_workspace_prototype.py list-shared-scratchpads \
+  /path/to/workspace
+```
+
+This prototype still does not execute commands. It proves that lane and
+scratchpad metadata can become the durable source of truth for:
 
 - which repos belong to a lane
 - which branch each repo should use
 - which context roots apply
 - where multi-repo commands should run
+- where lightweight collaboration should happen without violating private
+  workspaces
+
+## UX Focus
+
+This prototype is intentionally trying to answer user-facing questions:
+
+- how do I create a review lane quickly?
+- how do I know what I should do next in this lane?
+- when should I use a shared scratchpad instead of a PR or a private lane?
+
+That is why it includes:
+
+- `list-lanes`
+- `next-step`
+- `create-review-lane`
+- `create-shared-scratchpad`
+
+## Stress Testing
+
+This prototype is not considered verified on the happy path alone.
+
+The break-case matrix lives at:
+
+- `docs/ASSESS-gr2-shared-scratchpads-stress.md`
+
+The MVP should not be finalized until the prototype has been evaluated against:
+
+- concurrent shared editing
+- stale / abandoned scratchpads
+- wrong-surface selection
+- scope creep into shared implementation
+- cleanup and lifecycle handling
+- promotion from scratchpad to real repo artifact / PR
+
+## Real Git Verification
+
+Prototype confidence should not stop at metadata or tempdir-only happy paths.
+
+The next verification phase should use real GitHub repos in `synapt-dev`:
+
+- `synapt-dev/gr2-playground-app`
+- `synapt-dev/gr2-playground-api`
+- `synapt-dev/gr2-playground-web`
+
+These repos exist specifically to pressure the UX against actual git behavior:
+
+- cloning and default branches
+- multi-repo branch switching
+- review-lane isolation
+- dirty-work detection and recovery
+- shared scratchpad usage alongside private lanes
+
+That real-git verification phase is now tracked in:
+
+- `grip#523`
+- `grip#555`
+
+The design standard should be:
+
+- prototype behavior must survive both synthetic stress cases and real-repo
+  workflow checks before the MVP is treated as solid
+
+## Cross-Mode Lane Stress
+
+The lane model also needs adversarial verification across the four primary
+operating modes:
+
+- solo human
+- single agent
+- multi-agent
+- mixed human + agent
+
+Run:
+
+```bash
+python3 gr2/prototypes/cross_mode_lane_stress.py
+```
+
+This harness does not just show happy-path lane creation. It reports where the
+current model:
+
+- holds
+- partially holds
+- still fails
+
+across interruption recovery, same-repo parallelism, mixed-mode conflicts, and
+lane-recovery ambiguity.
+
+The current prototype adds two explicit recovery/safety concepts to support
+that stress loop:
+
+- lane session state
+  - `enter-lane`
+  - `current-lane`
+- lane leases
+  - `acquire-lane-lease`
+  - `release-lane-lease`
+  - `show-lane-leases`
+
+Those are still prototype surfaces, but they let us test whether the lane
+model can survive interruption and mixed human/agent use rather than only
+describe those needs abstractly.
+
+Lease behavior is now explicit in the prototype:
+
+- leases have `ttl_seconds`
+- stale leases are detectable
+- `acquire-lane-lease --force` can break stale conflicting leases
+- the conflict matrix is deliberate:
+  - `edit` conflicts with `edit`, `exec`, and `review`
+  - `exec` conflicts with `edit` and `review`, but not `exec`
+- `review` is exclusive
+
+## Synapt Integration Prototype
+
+The lane prototype now includes a minimal Synapt-native event layer:
+
+- `enter-lane --notify-channel --recall`
+- `exit-lane --notify-channel --recall`
+- append-only event log at `.grip/events/lane_events.jsonl`
+- recall-compatible log at `.grip/events/recall_lane_history.jsonl`
+- `lane-history` to reconstruct a unit's lane timeline
+
+Unit `agent_id` can now flow from `WorkspaceSpec` into:
+
+- lane metadata
+- current-lane state
+- emitted lane events
+
+This is still prototype scope, but it tests the right product direction:
+lane transitions and lease changes should be observable workspace events rather
+than invisible local state.
+
+## Real-Git Same-Repo Multi-Agent Materialization
+
+To verify that unit-local-first is real and not only metadata, run:
+
+```bash
+python3 gr2/prototypes/real_git_lane_materialization.py
+```
+
+This harness:
+
+- creates a local bare remote
+- writes a workspace spec that points at it
+- creates two lanes for two different units that both touch the same repo
+- verifies `plan-exec` produces distinct cwd paths
+- clones into those lane cwd paths
+- makes independent commits in each checkout
+- verifies the checkouts do not interfere
+
+## Concurrent Lease Stress
+
+To verify that lease writes survive contention, run:
+
+```bash
+python3 gr2/prototypes/concurrent_lease_stress.py
+```
+
+This harness runs two phases in one command:
+
+- before locking: `GR2_DISABLE_LEASE_LOCKING=1`
+- after locking: default locking enabled
+
+It reports:
+
+- JSON corruption count
+- rounds where both conflicting edit acquisitions succeeded
+- rounds where the final lease count was wrong
+
+Bootstrap command:
+
+```bash
+python3 gr2/prototypes/real_git_playground.py /tmp/gr2-real-git-demo
+```
+
+If the local environment cannot reach GitHub over SSH, use:
+
+```bash
+python3 gr2/prototypes/real_git_playground.py /tmp/gr2-real-git-demo \
+  --transport https
+```
+
+That harness will:
+
+- initialize a fresh gr2 workspace
+- register the three private playground repos
+- write a real `WorkspaceSpec`
+- run `plan` and `apply`
+- create real local git branches in the cloned repos
+- create multiple lanes and one shared scratchpad
+- print repo, lane, exec, and scratchpad status surfaces
+
+## New UX-Focused Prototype Surfaces
+
+The prototype now includes explicit user-guidance commands for the cases that
+usually break first in real workflows:
+
+```bash
+python3 gr2/prototypes/lane_workspace_prototype.py recommend-surface \
+  --kind doc --collaborative --shared-draft
+
+python3 gr2/prototypes/lane_workspace_prototype.py audit-shared-scratchpads \
+  /path/to/workspace --stale-days 3
+
+python3 gr2/prototypes/lane_workspace_prototype.py plan-promote-scratchpad \
+  /path/to/workspace blog-s17 \
+  --target-repo app \
+  --target-path docs/blog/sprint-17.md \
+  --owner-unit atlas
+```
+
+These are intentionally user-first:
+
+- `recommend-surface`
+  - answers "should this be a feature lane, review lane, or shared scratchpad?"
+- `audit-shared-scratchpads`
+  - exposes stale, orphaned, or weakly tracked scratchpads
+- `plan-promote-scratchpad`
+  - makes the graduation path from shared draft to repo artifact explicit
+
+This keeps the prototype from overfitting to happy-path metadata creation while
+ignoring the actual decisions users struggle with.
+
+## Transport/Auth Preflight
+
+Real multi-repo bootstrap fails early if transport or auth is wrong, so the
+prototype now includes a dedicated preflight surface:
+
+```bash
+python3 gr2/prototypes/repo_transport_probe.py \
+  /path/to/workspace/.grip/workspace_spec.toml
+```
+
+This reports, per repo:
+
+- transport type
+- whether the remote looks reachable
+- whether auth is failing
+- the next recommended action
+
+The real-git playground harness now runs this probe before `gr2 apply` so
+transport/auth problems are surfaced as an explicit status surface instead of a
+late clone failure buried inside apply output.
+
+## Layout Model Probe
+
+The real-git playground also needs to answer a harder product question:
+
+- does the observed layout actually match the mental model we are designing?
+
+The prototype now includes:
+
+```bash
+python3 gr2/prototypes/layout_model_probe.py /path/to/workspace --owner-unit atlas
+```
+
+This compares the observed workspace against two candidate models:
+
+- shared-repo-first
+- unit-local-first
+
+It is intentionally blunt. If the workspace behaves like one model while the
+docs imply another, the prototype should say so directly.
+
+## Cache Materialization Probe
+
+The next question is whether shared cache as apply substrate is actually worth
+it in practice.
+
+The prototype now includes:
+
+```bash
+python3 gr2/prototypes/cache_materialization_probe.py --transport ssh
+```
+
+This measures, per playground repo:
+
+- direct remote clone time
+- one-time mirror seed time
+- cache-backed working clone time using `git clone --reference-if-able`
+- whether the resulting working clone actually uses alternates
+
+This keeps the cache discussion grounded in evidence:
+
+- lanes remain the UX
+- cache remains the optimization
+- the prototype should tell us whether the optimization is material enough to
+  justify building it into `apply`
diff --git a/gr2/prototypes/cache_materialization_probe.py b/gr2/prototypes/cache_materialization_probe.py
new file mode 100644
index 00000000..b494e746
--- /dev/null
+++ b/gr2/prototypes/cache_materialization_probe.py
@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""Prototype cache-backed materialization for gr2 working clones.
+
+This is not a final implementation. It exists to answer a narrower question:
+
+- if `apply` seeds working clones from a local mirror/reference cache, does that
+  materially improve materialization speed while keeping the user-facing model
+  unchanged?
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+
+PLAYGROUND_REPOS = {
+    "app": {
+        "ssh": "git@github.com:synapt-dev/gr2-playground-app.git",
+        "https": "https://github.com/synapt-dev/gr2-playground-app.git",
+    },
+    "api": {
+        "ssh": "git@github.com:synapt-dev/gr2-playground-api.git",
+        "https": "https://github.com/synapt-dev/gr2-playground-api.git",
+    },
+    "web": {
+        "ssh": "git@github.com:synapt-dev/gr2-playground-web.git",
+        "https": "https://github.com/synapt-dev/gr2-playground-web.git",
+    },
+}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Measure direct clone vs cache-backed clone materialization"
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["ssh", "https"],
+        default="ssh",
+        help="remote transport to test",
+    )
+    parser.add_argument(
+        "--repo",
+        action="append",
+        dest="repos",
+        help="repo(s) to test; defaults to all playground repos",
+    )
+    parser.add_argument(
+        "--workspace-root",
+        type=Path,
+        help="optional persistent temp root; defaults to a temporary directory",
+    )
+    parser.add_argument("--json", action="store_true")
+    return parser.parse_args()
+
+
+def repo_url(repo_name: str, transport: str) -> str:
+    return PLAYGROUND_REPOS[repo_name][transport]
+
+
+def git_env() -> dict[str, str]:
+    env = dict(os.environ)
+    env.setdefault(
+        "GIT_SSH_COMMAND",
+        "ssh -o BatchMode=yes -o ConnectTimeout=5 -o StrictHostKeyChecking=accept-new",
+    )
+    return env
+
+
+def run(argv: list[str], *, cwd: Path | None = None) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        argv,
+        cwd=cwd,
+        text=True,
+        capture_output=True,
+        check=True,
+        env=git_env(),
+    )
+
+
+def timed_clone(argv: list[str], *, cwd: Path | None = None) -> tuple[float, subprocess.CompletedProcess[str]]:
+    start = time.perf_counter()
+    result = run(argv, cwd=cwd)
+    elapsed = time.perf_counter() - start
+    return (elapsed, result)
+
+
+def verify_working_clone(path: Path) -> dict[str, object]:
+    head = run(["git", "-C", str(path), "rev-parse", "--abbrev-ref", "HEAD"]).stdout.strip()
+    status = run(["git", "-C", str(path), "status", "--short"]).stdout.strip()
+    alternates = path / ".git" / "objects" / "info" / "alternates"
+    return {
+        "head": head,
+        "clean": status == "",
+        "uses_alternates": alternates.exists(),
+        "alternates_path": str(alternates) if alternates.exists() else None,
+    }
+
+
+def probe_repo(root: Path, repo_name: str, transport: str) -> dict[str, object]:
+    url = repo_url(repo_name, transport)
+    repo_root = root / repo_name
+    direct_root = repo_root / "direct"
+    cached_root = repo_root / "cached"
+    cache_root = repo_root / "cache"
+    direct_root.mkdir(parents=True, exist_ok=True)
+    cached_root.mkdir(parents=True, exist_ok=True)
+    cache_root.mkdir(parents=True, exist_ok=True)
+
+    direct_target = direct_root / repo_name
+    cache_mirror = cache_root / f"{repo_name}.git"
+    cached_target = cached_root / repo_name
+
+    direct_seconds, _ = timed_clone(["git", "clone", url, str(direct_target)])
+    mirror_seconds, _ = timed_clone(["git", "clone", "--mirror", url, str(cache_mirror)])
+    cached_seconds, _ = timed_clone(
+        [
+            "git",
+            "clone",
+            "--reference-if-able",
+            str(cache_mirror),
+            url,
+            str(cached_target),
+        ]
+    )
+
+    direct_info = verify_working_clone(direct_target)
+    cached_info = verify_working_clone(cached_target)
+
+    return {
+        "repo": repo_name,
+        "transport": transport,
+        "direct_clone_seconds": round(direct_seconds, 3),
+        "mirror_seed_seconds": round(mirror_seconds, 3),
+        "cached_clone_seconds": round(cached_seconds, 3),
+        "delta_seconds": round(direct_seconds - cached_seconds, 3),
+        "direct_clone": direct_info,
+        "cached_clone": cached_info,
+        "mirror_path": str(cache_mirror),
+    }
+
+
+def main() -> int:
+    args = parse_args()
+    repos = args.repos or list(PLAYGROUND_REPOS.keys())
+    unknown = [repo for repo in repos if repo not in PLAYGROUND_REPOS]
+    if unknown:
+        raise SystemExit("unknown repos: " + ", ".join(unknown))
+
+    if args.workspace_root:
+        root = args.workspace_root.resolve()
+        root.mkdir(parents=True, exist_ok=True)
+        cleanup = False
+    else:
+        root = Path(tempfile.mkdtemp(prefix="gr2-cache-probe."))
+        cleanup = True
+
+    try:
+        rows = [probe_repo(root, repo, args.transport) for repo in repos]
+        if args.json:
+            print(json.dumps({"root": str(root), "results": rows}, indent=2))
+        else:
+            print(f"root: {root}")
+            print("REPO\tTRANSPORT\tDIRECT_S\tMIRROR_S\tCACHED_S\tDELTA_S\tALTERNATES")
+            for row in rows:
+                print(
+                    f"{row['repo']}\t{row['transport']}\t{row['direct_clone_seconds']}\t"
+                    f"{row['mirror_seed_seconds']}\t{row['cached_clone_seconds']}\t"
+                    f"{row['delta_seconds']}\t{str(row['cached_clone']['uses_alternates']).lower()}"
+                )
+            print("notes:")
+            print("- direct clone is a normal working clone from remote")
+            print("- mirror seed is the one-time cache population cost")
+            print("- cached clone is a working clone using --reference-if-able from the local mirror")
+        return 0
+    finally:
+        if cleanup:
+            shutil.rmtree(root)
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/gr2/prototypes/concurrent_lease_stress.py b/gr2/prototypes/concurrent_lease_stress.py
new file mode 100644
index 00000000..378880ad
--- /dev/null
+++ b/gr2/prototypes/concurrent_lease_stress.py
@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""Concurrent lease stress harness with before/after locking results."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import multiprocessing
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Run concurrent lease stress before and after file locking"
+    )
+    parser.add_argument("--rounds", type=int, default=50)
+    parser.add_argument("--json", action="store_true")
+    return parser.parse_args()
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def lane_proto(root: Path) -> Path:
+    return root / "gr2" / "prototypes" / "lane_workspace_prototype.py"
+
+
+def run(argv: list[str], *, env: dict | None = None, check: bool = True, capture: bool = False) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(argv, check=check, text=True, capture_output=capture, env=env)
+
+
+def init_workspace(workspace_root: Path) -> None:
+    (workspace_root / ".grip").mkdir(parents=True, exist_ok=True)
+    (workspace_root / "agents").mkdir(exist_ok=True)
+    spec = """schema_version = 1
+workspace_name = "concurrent-lease-stress"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://example.invalid/app.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+agent_id = "atlas-agent"
+repos = ["app"]
+"""
+    (workspace_root / ".grip" / "workspace_spec.toml").write_text(spec)
+
+
+def create_lane(root: Path, workspace_root: Path) -> None:
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "create-lane",
+            str(workspace_root),
+            "atlas",
+            "feat-race",
+            "--repos",
+            "app",
+            "--branch",
+            "feat/race",
+        ],
+        capture=True,
+    )
+
+
+def worker(workspace_root: str, actor: str, queue, disable_locking: bool) -> None:
+    root = repo_root()
+    env = os.environ.copy()
+    if disable_locking:
+        env["GR2_DISABLE_LEASE_LOCKING"] = "1"
+        env["GR2_LEASE_TEST_DELAY"] = "0.02"
+    proc = run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "acquire-lane-lease",
+            workspace_root,
+            "atlas",
+            "feat-race",
+            "--actor",
+            actor,
+            "--mode",
+            "edit",
+            "--ttl-seconds",
+            "900",
+        ],
+        env=env,
+        check=False,
+        capture=True,
+    )
+    queue.put(
+        {
+            "actor": actor,
+            "returncode": proc.returncode,
+            "stdout": proc.stdout,
+            "stderr": proc.stderr,
+        }
+    )
+
+
+def read_leases(workspace_root: Path) -> tuple[bool, list[dict] | None]:
+    path = workspace_root / "agents" / "atlas" / "lanes" / "feat-race" / "leases.json"
+    if not path.exists():
+        return True, []
+    try:
+        return True, json.loads(path.read_text())
+    except json.JSONDecodeError:
+        return False, None
+
+
+def release_all(root: Path, workspace_root: Path, disable_locking: bool) -> None:
+    env = os.environ.copy()
+    if disable_locking:
+        env["GR2_DISABLE_LEASE_LOCKING"] = "1"
+    for actor in ("worker:a", "worker:b"):
+        run(
+            [
+                "python3",
+                str(lane_proto(root)),
+                "release-lane-lease",
+                str(workspace_root),
+                "atlas",
+                "feat-race",
+                "--actor",
+                actor,
+            ],
+            env=env,
+            check=False,
+            capture=True,
+        )
+
+
+def run_phase(disable_locking: bool, rounds: int) -> dict:
+    root = repo_root()
+    with tempfile.TemporaryDirectory(prefix="gr2-concurrent-lease-") as tmp:
+        workspace_root = Path(tmp)
+        init_workspace(workspace_root)
+        create_lane(root, workspace_root)
+
+        corruption_count = 0
+        both_succeeded_count = 0
+        unexpected_lease_count = 0
+
+        for _ in range(rounds):
+            queue = multiprocessing.Queue()
+            p1 = multiprocessing.Process(
+                target=worker,
+                args=(str(workspace_root), "worker:a", queue, disable_locking),
+            )
+            p2 = multiprocessing.Process(
+                target=worker,
+                args=(str(workspace_root), "worker:b", queue, disable_locking),
+            )
+            p1.start()
+            p2.start()
+            p1.join()
+            p2.join()
+
+            results = [queue.get(), queue.get()]
+            success_count = sum(1 for item in results if item["returncode"] == 0)
+            if success_count == 2:
+                both_succeeded_count += 1
+
+            valid_json, leases = read_leases(workspace_root)
+            if not valid_json:
+                corruption_count += 1
+            else:
+                expected = 1 if success_count >= 1 else 0
+                if len(leases or []) != expected:
+                    unexpected_lease_count += 1
+
+            release_all(root, workspace_root, disable_locking)
+
+        return {
+            "locking": "disabled" if disable_locking else "enabled",
+            "rounds": rounds,
+            "corruption_count": corruption_count,
+            "both_succeeded_count": both_succeeded_count,
+            "unexpected_lease_count": unexpected_lease_count,
+        }
+
+
+def main() -> int:
+    args = parse_args()
+    before = run_phase(disable_locking=True, rounds=args.rounds)
+    after = run_phase(disable_locking=False, rounds=args.rounds)
+    payload = {"before_locking": before, "after_locking": after}
+    if args.json:
+        print(json.dumps(payload, indent=2))
+    else:
+        print("gr2 concurrent lease stress")
+        print(json.dumps(payload, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/gr2/prototypes/cross_mode_lane_stress.py b/gr2/prototypes/cross_mode_lane_stress.py
new file mode 100644
index 00000000..e66cea5e
--- /dev/null
+++ b/gr2/prototypes/cross_mode_lane_stress.py
@@ -0,0 +1,699 @@
+#!/usr/bin/env python3
+"""Adversarial cross-mode stress harness for the gr2 lane model.
+
+This script pressures the lane prototype across the four primary user modes:
+
+1. solo human
+2. single agent
+3. multi-agent
+4. mixed human + agent
+
+It does not pretend the model is complete. It reports where the current
+prototype holds, where it only partially holds, and where it still falls over.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import tempfile
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+@dataclass
+class ScenarioResult:
+    scenario_id: str
+    user_mode: str
+    title: str
+    verdict: str
+    holds: list[str]
+    gaps: list[str]
+    evidence: list[str]
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Run adversarial cross-mode lane stress checks"
+    )
+    parser.add_argument(
+        "--workspace-root",
+        type=Path,
+        help="optional workspace root; defaults to a temporary workspace",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="emit structured JSON instead of human-readable text",
+    )
+    return parser.parse_args()
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def lane_proto(root: Path) -> Path:
+    return root / "gr2" / "prototypes" / "lane_workspace_prototype.py"
+
+
+def run(argv: list[str], *, capture: bool = False, cwd: Path | None = None) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        argv,
+        cwd=cwd,
+        check=True,
+        text=True,
+        capture_output=capture,
+    )
+
+
+def init_workspace(workspace_root: Path) -> None:
+    (workspace_root / ".grip").mkdir(parents=True, exist_ok=True)
+    (workspace_root / "agents").mkdir(exist_ok=True)
+    spec = """schema_version = 1
+workspace_name = "lane-cross-mode-stress"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://example.invalid/app.git"
+
+[[repos]]
+name = "api"
+path = "repos/api"
+url = "https://example.invalid/api.git"
+
+[[repos]]
+name = "web"
+path = "repos/web"
+url = "https://example.invalid/web.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+agent_id = "atlas-agent"
+repos = ["app", "api", "web"]
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+agent_id = "apollo-agent"
+repos = ["app", "api", "web"]
+
+[[units]]
+name = "layne"
+path = "agents/layne"
+agent_id = "layne-human"
+repos = ["app", "api", "web"]
+"""
+    (workspace_root / ".grip" / "workspace_spec.toml").write_text(spec)
+
+
+def create_lane(root: Path, workspace_root: Path, owner_unit: str, lane_name: str, repos: str, branch: str, lane_type: str = "feature") -> None:
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "create-lane",
+            str(workspace_root),
+            owner_unit,
+            lane_name,
+            "--type",
+            lane_type,
+            "--repos",
+            repos,
+            "--branch",
+            branch,
+        ]
+    )
+
+
+def create_review_lane(root: Path, workspace_root: Path, owner_unit: str, repo: str, pr_number: int) -> None:
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "create-review-lane",
+            str(workspace_root),
+            owner_unit,
+            repo,
+            str(pr_number),
+        ]
+    )
+
+
+def plan_exec_json(root: Path, workspace_root: Path, owner_unit: str, lane_name: str, command_text: str) -> list[dict]:
+    proc = run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "plan-exec",
+            str(workspace_root),
+            owner_unit,
+            lane_name,
+            command_text,
+            "--json",
+        ],
+        capture=True,
+    )
+    return json.loads(proc.stdout)
+
+
+def acquire_lease(root: Path, workspace_root: Path, owner_unit: str, lane_name: str, actor: str, mode: str, ttl_seconds: int = 900, force: bool = False, expect_ok: bool = True) -> subprocess.CompletedProcess[str]:
+    argv = [
+        "python3",
+        str(lane_proto(root)),
+        "acquire-lane-lease",
+        str(workspace_root),
+        owner_unit,
+        lane_name,
+        "--actor",
+        actor,
+        "--mode",
+        mode,
+        "--ttl-seconds",
+        str(ttl_seconds),
+    ]
+    if force:
+        argv.append("--force")
+    proc = subprocess.run(argv, check=False, text=True, capture_output=True)
+    if expect_ok and proc.returncode != 0:
+        raise SystemExit(f"lease acquisition failed unexpectedly: {' '.join(argv)}\n{proc.stdout}\n{proc.stderr}")
+    return proc
+
+
+def show_leases_json(root: Path, workspace_root: Path, owner_unit: str, lane_name: str) -> list[dict]:
+    proc = run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "show-lane-leases",
+            str(workspace_root),
+            owner_unit,
+            lane_name,
+            "--json",
+        ],
+        capture=True,
+    )
+    return json.loads(proc.stdout)
+
+
+def list_lanes_text(root: Path, workspace_root: Path, owner_unit: str | None = None) -> str:
+    argv = [
+        "python3",
+        str(lane_proto(root)),
+        "list-lanes",
+        str(workspace_root),
+    ]
+    if owner_unit:
+        argv.extend(["--owner-unit", owner_unit])
+    proc = run(argv, capture=True)
+    return proc.stdout
+
+
+def scenario_multi_agent_same_repo(root: Path, workspace_root: Path) -> ScenarioResult:
+    create_lane(root, workspace_root, "atlas", "feat-router", "app", "feat/router")
+    create_lane(root, workspace_root, "apollo", "feat-materialize", "app", "feat/materialize")
+
+    atlas_lane = workspace_root / "agents" / "atlas" / "lanes" / "feat-router" / "lane.toml"
+    apollo_lane = workspace_root / "agents" / "apollo" / "lanes" / "feat-materialize" / "lane.toml"
+
+    holds = []
+    gaps = []
+    evidence = []
+
+    if atlas_lane.exists() and apollo_lane.exists():
+        holds.append("two units can create separate lanes touching the same repo without metadata collision")
+        evidence.append(f"lane files: {atlas_lane.relative_to(workspace_root)}, {apollo_lane.relative_to(workspace_root)}")
+    else:
+        gaps.append("unit-scoped lane metadata was not isolated cleanly")
+
+    atlas_exec = plan_exec_json(root, workspace_root, "atlas", "feat-router", "cargo test")
+    apollo_exec = plan_exec_json(root, workspace_root, "apollo", "feat-materialize", "cargo test")
+    if atlas_exec and apollo_exec and atlas_exec[0]["cwd"] != apollo_exec[0]["cwd"]:
+        holds.append("execution planning stays unit-scoped even when both lanes include the same repo")
+        evidence.append(f"exec cwd atlas={atlas_exec[0]['cwd']} apollo={apollo_exec[0]['cwd']}")
+        verdict = "holds"
+    else:
+        gaps.append("execution planning did not stay unit-scoped for same-repo parallel work")
+        verdict = "fails"
+
+    return ScenarioResult(
+        scenario_id="multi-agent-same-repo",
+        user_mode="multi-agent",
+        title="two agents create lanes that touch the same repo",
+        verdict=verdict,
+        holds=holds,
+        gaps=gaps,
+        evidence=evidence,
+    )
+
+
+def scenario_mixed_same_lane_exec(root: Path, workspace_root: Path) -> ScenarioResult:
+    create_lane(root, workspace_root, "layne", "feat-blog", "app", "feat/blog")
+    acquire_lease(root, workspace_root, "layne", "feat-blog", "human:layne", "edit")
+
+    exec_rows = plan_exec_json(root, workspace_root, "layne", "feat-blog", "cargo test")
+
+    holds = []
+    gaps = []
+    evidence = [
+        "human edit lease acquired for layne/feat-blog",
+        json.dumps(exec_rows if isinstance(exec_rows, list) else exec_rows, indent=2),
+    ]
+
+    if isinstance(exec_rows, dict) and exec_rows.get("status") == "blocked":
+        holds.append("same-lane human-edit vs agent-exec is blocked by a lease")
+        holds.append("prototype now models occupancy instead of silently planning through it")
+        verdict = "holds"
+    else:
+        gaps.append("same-lane concurrent human-edit vs agent-exec is not modeled or blocked")
+        verdict = "fails"
+
+    return ScenarioResult(
+        scenario_id="mixed-same-lane-exec",
+        user_mode="mixed-human-agent",
+        title="human edits in a lane while an agent plans exec in the same lane",
+        verdict=verdict,
+        holds=holds,
+        gaps=gaps,
+        evidence=evidence,
+    )
+
+
+def scenario_single_agent_interrupt_recovery(root: Path, workspace_root: Path) -> ScenarioResult:
+    create_lane(root, workspace_root, "atlas", "feat-auth", "app,api", "feat/auth")
+    create_review_lane(root, workspace_root, "atlas", "app", 123)
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "enter-lane",
+            str(workspace_root),
+            "atlas",
+            "feat-auth",
+            "--actor",
+            "agent:atlas",
+        ]
+    )
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "enter-lane",
+            str(workspace_root),
+            "atlas",
+            "review-123",
+            "--actor",
+            "agent:atlas",
+        ]
+    )
+    lane_listing = list_lanes_text(root, workspace_root, "atlas")
+    current_lane_proc = run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "current-lane",
+            str(workspace_root),
+            "atlas",
+            "--json",
+        ],
+        capture=True,
+    )
+    current_lane_doc = json.loads(current_lane_proc.stdout)
+    holds = [
+        "agent can enumerate all of its lanes without guessing filesystem paths",
+        "lane metadata includes repos, type, and PR references",
+    ]
+    gaps = []
+    evidence = [lane_listing.strip(), json.dumps(current_lane_doc, indent=2)]
+
+    current = current_lane_doc.get("current", {})
+    recent = current_lane_doc.get("recent", [])
+    if current.get("lane_name") == "review-123":
+        holds.append("agent can recover current lane after an interruption")
+    else:
+        gaps.append("current-lane surface did not record the lane entered most recently")
+
+    if recent and recent[0].get("lane_name") == "feat-auth":
+        holds.append("agent can recover previous lane from recent history")
+        verdict = "holds"
+    else:
+        gaps.append("prototype still cannot recover previous lane deterministically")
+        verdict = "partial"
+
+    return ScenarioResult(
+        scenario_id="single-agent-interrupt-recovery",
+        user_mode="single-agent",
+        title="agent is interrupted mid-task and needs to recover lane context",
+        verdict=verdict,
+        holds=holds,
+        gaps=gaps,
+        evidence=evidence,
+    )
+
+
+def scenario_lease_conflict_matrix(root: Path, workspace_root: Path) -> ScenarioResult:
+    create_lane(root, workspace_root, "atlas", "feat-matrix", "app", "feat/matrix")
+
+    exec_one = acquire_lease(root, workspace_root, "atlas", "feat-matrix", "agent:atlas", "exec")
+    exec_two = acquire_lease(root, workspace_root, "atlas", "feat-matrix", "agent:apollo", "exec")
+    edit_conflict = acquire_lease(
+        root,
+        workspace_root,
+        "atlas",
+        "feat-matrix",
+        "human:layne",
+        "edit",
+        expect_ok=False,
+    )
+
+    create_lane(root, workspace_root, "atlas", "feat-review-lock", "app", "feat/review-lock")
+    acquire_lease(root, workspace_root, "atlas", "feat-review-lock", "agent:atlas", "review")
+    review_conflict = acquire_lease(
+        root,
+        workspace_root,
+        "atlas",
+        "feat-review-lock",
+        "agent:apollo",
+        "exec",
+        expect_ok=False,
+    )
+
+    holds = []
+    gaps = []
+    evidence = []
+
+    if exec_one.returncode == 0 and exec_two.returncode == 0:
+        holds.append("exec-vs-exec is allowed for the same lane")
+        evidence.append("two exec leases acquired successfully on atlas/feat-matrix")
+    else:
+        gaps.append("exec-vs-exec was blocked unexpectedly")
+
+    if edit_conflict.returncode != 0:
+        holds.append("edit-vs-exec conflicts as expected")
+        evidence.append(edit_conflict.stdout.strip())
+    else:
+        gaps.append("edit-vs-exec did not conflict")
+
+    if review_conflict.returncode != 0:
+        holds.append("review-vs-anything is exclusive")
+        evidence.append(review_conflict.stdout.strip())
+    else:
+        gaps.append("review-vs-exec did not conflict")
+
+    leases = show_leases_json(root, workspace_root, "atlas", "feat-matrix")
+    evidence.append(json.dumps(leases, indent=2))
+    verdict = "holds" if not gaps else "fails"
+    return ScenarioResult(
+        scenario_id="lease-conflict-matrix",
+        user_mode="cross-mode",
+        title="lease conflict matrix enforces edit/exec/review semantics",
+        verdict=verdict,
+        holds=holds,
+        gaps=gaps,
+        evidence=evidence,
+    )
+
+
+def scenario_synapt_lane_events(root: Path, workspace_root: Path) -> ScenarioResult:
+    create_lane(root, workspace_root, "atlas", "feat-events", "app,api", "feat/events")
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "enter-lane",
+            str(workspace_root),
+            "atlas",
+            "feat-events",
+            "--actor",
+            "agent:atlas",
+            "--notify-channel",
+            "--recall",
+        ]
+    )
+    acquire_lease(root, workspace_root, "atlas", "feat-events", "agent:atlas", "exec")
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "release-lane-lease",
+            str(workspace_root),
+            "atlas",
+            "feat-events",
+            "--actor",
+            "agent:atlas",
+        ]
+    )
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "exit-lane",
+            str(workspace_root),
+            "atlas",
+            "--actor",
+            "agent:atlas",
+            "--notify-channel",
+            "--recall",
+        ]
+    )
+    history_proc = run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "lane-history",
+            str(workspace_root),
+            "atlas",
+            "--json",
+        ],
+        capture=True,
+    )
+    history_rows = json.loads(history_proc.stdout)
+    events_path = workspace_root / ".grip" / "events" / "lane_events.jsonl"
+    recall_path = workspace_root / ".grip" / "events" / "recall_lane_history.jsonl"
+
+    holds = []
+    gaps = []
+    evidence = [json.dumps(history_rows, indent=2)]
+
+    event_types = [row["type"] for row in history_rows]
+    expected = ["lane_enter", "lease_acquire", "lease_release", "lane_exit"]
+    if event_types == expected:
+        holds.append("lane event timeline is reconstructible from append-only event log")
+    else:
+        gaps.append(f"unexpected lane event order: {event_types}")
+
+    if all(row.get("agent_id") == "atlas-agent" for row in history_rows):
+        holds.append("agent_id flows from workspace spec into lane events")
+    else:
+        gaps.append("agent_id did not flow consistently into lane events")
+
+    if events_path.exists() and recall_path.exists():
+        holds.append("channel-compatible and recall-compatible event logs are both written")
+    else:
+        gaps.append("expected event logs were not both written")
+
+    verdict = "holds" if not gaps else "fails"
+    return ScenarioResult(
+        scenario_id="synapt-lane-events",
+        user_mode="single-agent",
+        title="lane enter/lease/exit emits reconstructible synapt-compatible events",
+        verdict=verdict,
+        holds=holds,
+        gaps=gaps,
+        evidence=evidence,
+    )
+
+
+def scenario_stale_lease_force_break(root: Path, workspace_root: Path) -> ScenarioResult:
+    create_lane(root, workspace_root, "atlas", "feat-stale", "app", "feat/stale")
+    stale = acquire_lease(
+        root,
+        workspace_root,
+        "atlas",
+        "feat-stale",
+        "human:layne",
+        "edit",
+        ttl_seconds=0,
+    )
+    blocked_exec = plan_exec_json(root, workspace_root, "atlas", "feat-stale", "cargo test")
+    forced = acquire_lease(
+        root,
+        workspace_root,
+        "atlas",
+        "feat-stale",
+        "agent:atlas",
+        "exec",
+        ttl_seconds=900,
+        force=True,
+    )
+    leases_after = show_leases_json(root, workspace_root, "atlas", "feat-stale")
+
+    holds = []
+    gaps = []
+    evidence = [stale.stdout.strip(), json.dumps(blocked_exec, indent=2), forced.stdout.strip(), json.dumps(leases_after, indent=2)]
+
+    if isinstance(blocked_exec, dict) and blocked_exec.get("reason") == "stale-conflicting-lease":
+        holds.append("plan-exec detects stale conflicting leases")
+    else:
+        gaps.append("plan-exec did not flag stale conflicting leases")
+
+    actors_after = {lease["actor"] for lease in leases_after}
+    if "human:layne" not in actors_after and "agent:atlas" in actors_after:
+        holds.append("force acquisition breaks stale conflicting lease and installs new lease")
+    else:
+        gaps.append("force acquisition did not replace stale conflicting lease cleanly")
+
+    verdict = "holds" if not gaps else "fails"
+    return ScenarioResult(
+        scenario_id="stale-lease-force-break",
+        user_mode="cross-mode",
+        title="stale leases are detectable and force-breakable",
+        verdict=verdict,
+        holds=holds,
+        gaps=gaps,
+        evidence=evidence,
+    )
+
+
+def scenario_solo_human_forgets_lane(root: Path, workspace_root: Path) -> ScenarioResult:
+    create_lane(root, workspace_root, "layne", "feat-auth", "app,api", "feat/auth")
+    create_lane(root, workspace_root, "layne", "feat-web", "web", "feat/web")
+    create_lane(root, workspace_root, "layne", "feat-release", "app,web", "feat/release")
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "enter-lane",
+            str(workspace_root),
+            "layne",
+            "feat-release",
+            "--actor",
+            "human:layne",
+        ]
+    )
+    create_review_lane(root, workspace_root, "layne", "app", 456)
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "enter-lane",
+            str(workspace_root),
+            "layne",
+            "review-456",
+            "--actor",
+            "human:layne",
+        ]
+    )
+
+    lane_listing = list_lanes_text(root, workspace_root, "layne")
+    current_lane_proc = run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "current-lane",
+            str(workspace_root),
+            "layne",
+            "--json",
+        ],
+        capture=True,
+    )
+    current_lane_doc = json.loads(current_lane_proc.stdout)
+    holds = [
+        "user can see all lanes in one listing",
+        "review lane is isolated as its own lane type rather than overwriting feature state",
+    ]
+    gaps = []
+    evidence = [lane_listing.strip(), json.dumps(current_lane_doc, indent=2)]
+
+    if current_lane_doc.get("current", {}).get("lane_name") == "review-456":
+        holds.append("current review lane is visible after switching")
+    else:
+        gaps.append("current lane is not visible after switching to review")
+
+    recent = current_lane_doc.get("recent", [])
+    if recent and recent[0].get("lane_name") == "feat-release":
+        holds.append("previous feature lane is recoverable after entering review")
+        verdict = "holds"
+    else:
+        gaps.append("prototype lacks an obvious return-to-previous-lane recovery path")
+        verdict = "partial"
+
+    return ScenarioResult(
+        scenario_id="solo-human-lane-recovery",
+        user_mode="solo-human",
+        title="solo human has three feature lanes, switches to review, then forgets the prior lane",
+        verdict=verdict,
+        holds=holds,
+        gaps=gaps,
+        evidence=evidence,
+    )
+
+
+def run_scenarios(workspace_root: Path) -> list[ScenarioResult]:
+    root = repo_root()
+    init_workspace(workspace_root)
+    return [
+        scenario_synapt_lane_events(root, workspace_root),
+        scenario_lease_conflict_matrix(root, workspace_root),
+        scenario_stale_lease_force_break(root, workspace_root),
+        scenario_multi_agent_same_repo(root, workspace_root),
+        scenario_mixed_same_lane_exec(root, workspace_root),
+        scenario_single_agent_interrupt_recovery(root, workspace_root),
+        scenario_solo_human_forgets_lane(root, workspace_root),
+    ]
+
+
+def print_human(results: list[ScenarioResult], workspace_root: Path) -> None:
+    print("gr2 cross-mode lane stress results")
+    print(f"workspace: {workspace_root}")
+    print()
+    for result in results:
+        print(f"[{result.verdict}] {result.user_mode}: {result.title}")
+        if result.holds:
+            print("  holds:")
+            for item in result.holds:
+                print(f"    - {item}")
+        if result.gaps:
+            print("  gaps:")
+            for item in result.gaps:
+                print(f"    - {item}")
+        if result.evidence:
+            print("  evidence:")
+            for item in result.evidence:
+                for line in item.splitlines():
+                    print(f"    {line}")
+        print()
+
+
+def main() -> int:
+    args = parse_args()
+
+    if args.workspace_root:
+        workspace_root = args.workspace_root.resolve()
+        workspace_root.mkdir(parents=True, exist_ok=True)
+        results = run_scenarios(workspace_root)
+    else:
+        with tempfile.TemporaryDirectory(prefix="gr2-cross-mode-") as tmp:
+            workspace_root = Path(tmp)
+            results = run_scenarios(workspace_root)
+            if args.json:
+                print(json.dumps([asdict(result) for result in results], indent=2))
+                return 0
+            print_human(results, workspace_root)
+            return 0
+
+    if args.json:
+        print(json.dumps([asdict(result) for result in results], indent=2))
+    else:
+        print_human(results, workspace_root)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/gr2/prototypes/lane_workspace_prototype.py b/gr2/prototypes/lane_workspace_prototype.py
index 9e1b4549..678924e8 100644
--- a/gr2/prototypes/lane_workspace_prototype.py
+++ b/gr2/prototypes/lane_workspace_prototype.py
@@ -1,22 +1,32 @@
 #!/usr/bin/env python3
-"""Prototype lane metadata and lane-aware execution planning for gr2.
+"""Prototype lane metadata, execution planning, and shared scratchpads for gr2.
 
-This prototype does not mutate git state. It proves the lane model is useful by
-persisting explicit lane metadata and generating execution plans scoped by lane.
+This prototype does not mutate git state. It explores three UX questions:
+
+1. are lane records legible enough to guide multi-repo work?
+2. can lightweight shared scratchpads fill the collaboration gap without
+   violating private-workspace rules?
+3. can the tool tell the user what to do next instead of forcing them to infer
+   the workflow?
 """
 
 from __future__ import annotations
 
 import argparse
 import dataclasses
+import os
 import json
 import shlex
 import sys
+import time
 import tomllib
+from datetime import UTC, datetime, timedelta
 from pathlib import Path
+import fcntl
 
 
 LANE_SCHEMA_VERSION = 1
+SCRATCHPAD_SCHEMA_VERSION = 1
 
 
 @dataclasses.dataclass
@@ -24,6 +34,7 @@ class LaneMetadata:
     schema_version: int
     lane_name: str
     owner_unit: str
+    agent_id: str | None
     lane_type: str
     repos: list[str]
     branch_map: dict[str, str]
@@ -38,6 +49,7 @@ def as_toml(self) -> str:
             f"schema_version = {self.schema_version}",
             f'lane_name = "{self.lane_name}"',
             f'owner_unit = "{self.owner_unit}"',
+            f'agent_id = "{self.agent_id or ""}"',
             f'lane_type = "{self.lane_type}"',
             f'creation_source = "{self.creation_source}"',
             "",
@@ -48,32 +60,14 @@ def as_toml(self) -> str:
         for repo, branch in sorted(self.branch_map.items()):
             lines.append(f'{repo} = "{branch}"')
 
-        lines.extend(
-            [
-                "",
-                "[context]",
-                "shared_roots = ["
-            ]
-        )
+        lines.extend(["", "[context]", "shared_roots = ["])
         for root in self.shared_context_roots:
             lines.append(f'  "{root}",')
-
-        lines.extend(
-            [
-                "]",
-                "private_roots = [",
-            ]
-        )
+        lines.extend(["]", "private_roots = ["])
         for root in self.private_context_roots:
             lines.append(f'  "{root}",')
 
-        lines.extend(
-            [
-                "]",
-                "",
-                "[exec_defaults]",
-            ]
-        )
+        lines.extend(["]", "", "[exec_defaults]"])
         for key, value in self.exec_defaults.items():
             if isinstance(value, bool):
                 encoded = str(value).lower()
@@ -85,16 +79,54 @@ def as_toml(self) -> str:
                 encoded = f'"{value}"'
             lines.append(f"{key} = {encoded}")
 
-        if self.pr_associations:
-            lines.extend(["", "[[pr_associations]]"])
-            for assoc in self.pr_associations:
-                lines.append(f'ref = "{assoc}"')
+        for assoc in self.pr_associations:
+            lines.extend(["", "[[pr_associations]]", f'ref = "{assoc}"'])
+
+        return "\n".join(lines) + "\n"
+
 
+@dataclasses.dataclass
+class SharedScratchpad:
+    schema_version: int
+    name: str
+    kind: str
+    purpose: str
+    participants: list[str]
+    linked_refs: list[str]
+    lifecycle: str
+    creation_source: str
+    docs_root: str
+    notes_root: str
+    context_root: str
+    created_at: str
+    updated_at: str
+
+    def as_toml(self) -> str:
+        lines = [
+            f"schema_version = {self.schema_version}",
+            f'name = "{self.name}"',
+            f'kind = "{self.kind}"',
+            f'purpose = "{self.purpose}"',
+            f'lifecycle = "{self.lifecycle}"',
+            f'creation_source = "{self.creation_source}"',
+            f'created_at = "{self.created_at}"',
+            f'updated_at = "{self.updated_at}"',
+            "",
+            f'participants = [{", ".join(f"\"{p}\"" for p in self.participants)}]',
+            f'linked_refs = [{", ".join(f"\"{r}\"" for r in self.linked_refs)}]',
+            "",
+            "[paths]",
+            f'docs_root = "{self.docs_root}"',
+            f'notes_root = "{self.notes_root}"',
+            f'context_root = "{self.context_root}"',
+        ]
         return "\n".join(lines) + "\n"
 
 
 def parse_args() -> argparse.Namespace:
-    parser = argparse.ArgumentParser(description="Prototype gr2 lane metadata + exec planner")
+    parser = argparse.ArgumentParser(
+        description="Prototype gr2 lanes + shared scratchpads"
+    )
     sub = parser.add_subparsers(dest="command", required=True)
 
     create = sub.add_parser("create-lane")
@@ -103,14 +135,42 @@ def parse_args() -> argparse.Namespace:
     create.add_argument("lane_name")
     create.add_argument("--type", default="feature")
     create.add_argument("--repos", required=True, help="comma-separated repo names")
-    create.add_argument("--branch", required=True, help="default branch for included repos")
+    create.add_argument(
+        "--branch",
+        required=True,
+        help="default branch or repo=branch mappings separated by commas",
+    )
     create.add_argument("--source", default="manual")
+    create.add_argument(
+        "--command",
+        dest="default_commands",
+        action="append",
+        default=[],
+        help="default lane command",
+    )
+
+    review = sub.add_parser("create-review-lane")
+    review.add_argument("workspace_root", type=Path)
+    review.add_argument("owner_unit")
+    review.add_argument("repo")
+    review.add_argument("pr_number", type=int)
+    review.add_argument("--lane-name")
+    review.add_argument("--branch")
 
     show = sub.add_parser("show-lane")
     show.add_argument("workspace_root", type=Path)
     show.add_argument("owner_unit")
     show.add_argument("lane_name")
 
+    lane_list = sub.add_parser("list-lanes")
+    lane_list.add_argument("workspace_root", type=Path)
+    lane_list.add_argument("--owner-unit")
+
+    next_step = sub.add_parser("next-step")
+    next_step.add_argument("workspace_root", type=Path)
+    next_step.add_argument("owner_unit")
+    next_step.add_argument("lane_name")
+
     plan = sub.add_parser("plan-exec")
     plan.add_argument("workspace_root", type=Path)
     plan.add_argument("owner_unit")
@@ -119,6 +179,101 @@ def parse_args() -> argparse.Namespace:
     plan.add_argument("--repos", help="optional comma-separated repo subset")
     plan.add_argument("--json", action="store_true")
 
+    enter = sub.add_parser("enter-lane")
+    enter.add_argument("workspace_root", type=Path)
+    enter.add_argument("owner_unit")
+    enter.add_argument("lane_name")
+    enter.add_argument("--actor", required=True, help="actor label, e.g. human:layne or agent:atlas")
+    enter.add_argument("--notify-channel", action="store_true")
+    enter.add_argument("--recall", action="store_true")
+
+    exit_lane = sub.add_parser("exit-lane")
+    exit_lane.add_argument("workspace_root", type=Path)
+    exit_lane.add_argument("owner_unit")
+    exit_lane.add_argument("--actor", required=True)
+    exit_lane.add_argument("--notify-channel", action="store_true")
+    exit_lane.add_argument("--recall", action="store_true")
+
+    current = sub.add_parser("current-lane")
+    current.add_argument("workspace_root", type=Path)
+    current.add_argument("owner_unit")
+    current.add_argument("--json", action="store_true")
+
+    history = sub.add_parser("lane-history")
+    history.add_argument("workspace_root", type=Path)
+    history.add_argument("owner_unit")
+    history.add_argument("--json", action="store_true")
+
+    lease = sub.add_parser("acquire-lane-lease")
+    lease.add_argument("workspace_root", type=Path)
+    lease.add_argument("owner_unit")
+    lease.add_argument("lane_name")
+    lease.add_argument("--actor", required=True)
+    lease.add_argument("--mode", choices=["edit", "exec", "review"], required=True)
+    lease.add_argument(
+        "--ttl-seconds",
+        type=int,
+        default=900,
+        help="lease TTL in seconds before it is considered stale",
+    )
+    lease.add_argument(
+        "--force",
+        action="store_true",
+        help="break conflicting stale leases with a warning",
+    )
+
+    release = sub.add_parser("release-lane-lease")
+    release.add_argument("workspace_root", type=Path)
+    release.add_argument("owner_unit")
+    release.add_argument("lane_name")
+    release.add_argument("--actor", required=True)
+
+    show_leases = sub.add_parser("show-lane-leases")
+    show_leases.add_argument("workspace_root", type=Path)
+    show_leases.add_argument("owner_unit")
+    show_leases.add_argument("lane_name")
+    show_leases.add_argument("--json", action="store_true")
+
+    scratch = sub.add_parser("create-shared-scratchpad")
+    scratch.add_argument("workspace_root", type=Path)
+    scratch.add_argument("name")
+    scratch.add_argument("--kind", default="doc")
+    scratch.add_argument("--purpose", required=True)
+    scratch.add_argument("--participant", action="append", default=[])
+    scratch.add_argument("--ref", action="append", default=[])
+    scratch.add_argument("--source", default="manual")
+
+    scratch_show = sub.add_parser("show-shared-scratchpad")
+    scratch_show.add_argument("workspace_root", type=Path)
+    scratch_show.add_argument("name")
+
+    scratch_list = sub.add_parser("list-shared-scratchpads")
+    scratch_list.add_argument("workspace_root", type=Path)
+
+    scratch_audit = sub.add_parser("audit-shared-scratchpads")
+    scratch_audit.add_argument("workspace_root", type=Path)
+    scratch_audit.add_argument(
+        "--stale-days",
+        type=int,
+        default=7,
+        help="mark scratchpads as stale when untouched for this many days",
+    )
+
+    promote = sub.add_parser("plan-promote-scratchpad")
+    promote.add_argument("workspace_root", type=Path)
+    promote.add_argument("name")
+    promote.add_argument("--target-repo", required=True)
+    promote.add_argument("--target-path", required=True)
+    promote.add_argument("--owner-unit", required=True)
+    promote.add_argument("--lane", help="optional lane that should carry the promotion")
+
+    recommend = sub.add_parser("recommend-surface")
+    recommend.add_argument("--kind", choices=["code", "doc", "review", "planning"], required=True)
+    recommend.add_argument("--collaborative", action="store_true")
+    recommend.add_argument("--formal-review", action="store_true")
+    recommend.add_argument("--repos", type=int, default=1)
+    recommend.add_argument("--shared-draft", action="store_true")
+
     return parser.parse_args()
 
 
@@ -130,16 +285,286 @@ def lane_file(workspace_root: Path, owner_unit: str, lane_name: str) -> Path:
     return lane_dir(workspace_root, owner_unit, lane_name) / "lane.toml"
 
 
+def shared_scratchpad_dir(workspace_root: Path, name: str) -> Path:
+    return workspace_root / "shared" / "scratchpads" / name
+
+
+def shared_scratchpad_file(workspace_root: Path, name: str) -> Path:
+    return shared_scratchpad_dir(workspace_root, name) / "scratchpad.toml"
+
+
+def current_lane_file(workspace_root: Path, owner_unit: str) -> Path:
+    return workspace_root / ".grip" / "state" / "current_lane" / f"{owner_unit}.json"
+
+
+def lane_leases_file(workspace_root: Path, owner_unit: str, lane_name: str) -> Path:
+    return lane_dir(workspace_root, owner_unit, lane_name) / "leases.json"
+
+
+def lane_leases_lock_file(workspace_root: Path, owner_unit: str, lane_name: str) -> Path:
+    return lane_dir(workspace_root, owner_unit, lane_name) / "leases.lock"
+
+
+def events_dir(workspace_root: Path) -> Path:
+    return workspace_root / ".grip" / "events"
+
+
+def lane_events_file(workspace_root: Path) -> Path:
+    return events_dir(workspace_root) / "lane_events.jsonl"
+
+
+def recall_lane_events_file(workspace_root: Path) -> Path:
+    return events_dir(workspace_root) / "recall_lane_history.jsonl"
+
+
 def load_workspace_spec(workspace_root: Path) -> dict:
     with (workspace_root / ".grip" / "workspace_spec.toml").open("rb") as fh:
         return tomllib.load(fh)
 
 
+def find_unit_spec(workspace_root: Path, owner_unit: str) -> dict:
+    spec = load_workspace_spec(workspace_root)
+    for unit in spec.get("units", []):
+        if unit.get("name") == owner_unit:
+            return unit
+    raise SystemExit(f"unit not found in workspace spec: {owner_unit}")
+
+
+def load_lane_doc(workspace_root: Path, owner_unit: str, lane_name: str) -> dict:
+    path = lane_file(workspace_root, owner_unit, lane_name)
+    if not path.exists():
+        raise SystemExit(f"lane not found: {owner_unit}/{lane_name}")
+    return tomllib.loads(path.read_text())
+
+
+def load_shared_scratchpad_doc(workspace_root: Path, name: str) -> dict:
+    path = shared_scratchpad_file(workspace_root, name)
+    if not path.exists():
+        raise SystemExit(f"shared scratchpad not found: {name}")
+    return tomllib.loads(path.read_text())
+
+
+def load_current_lane_doc(workspace_root: Path, owner_unit: str) -> dict:
+    path = current_lane_file(workspace_root, owner_unit)
+    if not path.exists():
+        raise SystemExit(f"no current lane recorded for unit: {owner_unit}")
+    return json.loads(path.read_text())
+
+
+def append_jsonl(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(payload) + "\n")
+
+
+def emit_lane_event(workspace_root: Path, payload: dict) -> None:
+    append_jsonl(lane_events_file(workspace_root), payload)
+
+
+def emit_recall_lane_event(workspace_root: Path, payload: dict) -> None:
+    append_jsonl(recall_lane_events_file(workspace_root), payload)
+
+
+def iter_lane_events(workspace_root: Path) -> list[dict]:
+    path = lane_events_file(workspace_root)
+    if not path.exists():
+        return []
+    items: list[dict] = []
+    for line in path.read_text().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        items.append(json.loads(line))
+    return items
+
+
+def load_lane_leases(workspace_root: Path, owner_unit: str, lane_name: str) -> list[dict]:
+    path = lane_leases_file(workspace_root, owner_unit, lane_name)
+    if not path.exists():
+        return []
+    return json.loads(path.read_text())
+
+
+def lease_locking_enabled() -> bool:
+    return os.environ.get("GR2_DISABLE_LEASE_LOCKING") != "1"
+
+
+def write_lane_leases(
+    workspace_root: Path,
+    owner_unit: str,
+    lane_name: str,
+    leases: list[dict],
+    *,
+    lock_fh=None,
+) -> None:
+    path = lane_leases_file(workspace_root, owner_unit, lane_name)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    if lock_fh is None:
+        lock_path = lane_leases_lock_file(workspace_root, owner_unit, lane_name)
+        lock_path.parent.mkdir(parents=True, exist_ok=True)
+        with lock_path.open("a+", encoding="utf-8") as owned_lock_fh:
+            if lease_locking_enabled():
+                fcntl.flock(owned_lock_fh.fileno(), fcntl.LOCK_EX)
+            tmp = path.with_suffix(".json.tmp")
+            tmp.write_text(json.dumps(leases, indent=2) + "\n")
+            os.replace(tmp, path)
+            if lease_locking_enabled():
+                fcntl.flock(owned_lock_fh.fileno(), fcntl.LOCK_UN)
+        return
+
+    tmp = path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(leases, indent=2) + "\n")
+    os.replace(tmp, path)
+
+
+def mutate_lane_leases(
+    workspace_root: Path,
+    owner_unit: str,
+    lane_name: str,
+    mutator,
+):
+    lock_path = lane_leases_lock_file(workspace_root, owner_unit, lane_name)
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    with lock_path.open("a+", encoding="utf-8") as lock_fh:
+        if lease_locking_enabled():
+            fcntl.flock(lock_fh.fileno(), fcntl.LOCK_EX)
+        path = lane_leases_file(workspace_root, owner_unit, lane_name)
+        if path.exists():
+            leases = json.loads(path.read_text())
+        else:
+            leases = []
+        if not lease_locking_enabled():
+            delay = float(os.environ.get("GR2_LEASE_TEST_DELAY", "0"))
+            if delay > 0:
+                time.sleep(delay)
+        result = mutator(leases)
+        if result.get("write"):
+            write_lane_leases(
+                workspace_root,
+                owner_unit,
+                lane_name,
+                result["leases"],
+                lock_fh=lock_fh,
+            )
+        if lease_locking_enabled():
+            fcntl.flock(lock_fh.fileno(), fcntl.LOCK_UN)
+        return result
+
+
+def iter_lane_files(workspace_root: Path, owner_unit: str | None = None) -> list[Path]:
+    agents_root = workspace_root / "agents"
+    if owner_unit:
+        lane_roots = [agents_root / owner_unit / "lanes"]
+    else:
+        lane_roots = [path / "lanes" for path in agents_root.iterdir() if path.is_dir()]
+
+    files: list[Path] = []
+    for root in lane_roots:
+        if not root.exists():
+            continue
+        files.extend(sorted(root.glob("*/lane.toml")))
+    return files
+
+
+def iter_shared_scratchpad_files(workspace_root: Path) -> list[Path]:
+    root = workspace_root / "shared" / "scratchpads"
+    if not root.exists():
+        return []
+    return sorted(root.glob("*/scratchpad.toml"))
+
+
+def now_utc() -> str:
+    return datetime.now(UTC).replace(microsecond=0).isoformat()
+
+
+def parse_utc(raw: str) -> datetime:
+    return datetime.fromisoformat(raw)
+
+
+def is_stale_lease(lease: dict) -> bool:
+    expires_at = lease.get("expires_at")
+    if not expires_at:
+        return False
+    return parse_utc(expires_at) <= datetime.now(UTC)
+
+
+def build_lease(actor: str, mode: str, ttl_seconds: int) -> dict:
+    acquired = datetime.now(UTC).replace(microsecond=0)
+    expires = acquired + timedelta(seconds=ttl_seconds)
+    return {
+        "actor": actor,
+        "mode": mode,
+        "ttl_seconds": ttl_seconds,
+        "acquired_at": acquired.isoformat(),
+        "expires_at": expires.isoformat(),
+    }
+
+
+def lease_conflicts(existing_mode: str, requested_mode: str) -> bool:
+    matrix = {
+        "edit": {"edit", "exec", "review"},
+        "exec": {"edit", "review"},
+        "review": {"edit", "exec", "review"},
+    }
+    return requested_mode in matrix.get(existing_mode, set())
+
+
+def conflicting_leases(leases: list[dict], actor: str, requested_mode: str) -> tuple[list[dict], list[dict]]:
+    active: list[dict] = []
+    stale: list[dict] = []
+    for lease in leases:
+        if lease["actor"] == actor:
+            continue
+        if not lease_conflicts(lease["mode"], requested_mode):
+            continue
+        if is_stale_lease(lease):
+            stale.append(lease)
+        else:
+            active.append(lease)
+    return active, stale
+
+
+def age_days(path: Path) -> int:
+    modified = datetime.fromtimestamp(path.stat().st_mtime, UTC)
+    return max(0, int((datetime.now(UTC) - modified).total_seconds() // 86400))
+
+
+def parse_repo_list(raw: str) -> list[str]:
+    return [repo.strip() for repo in raw.split(",") if repo.strip()]
+
+
+def parse_branch_arg(raw: str, repos: list[str]) -> dict[str, str]:
+    if "=" not in raw:
+        return {repo: raw for repo in repos}
+
+    branch_map: dict[str, str] = {}
+    for item in raw.split(","):
+        item = item.strip()
+        if not item:
+            continue
+        repo, branch = item.split("=", 1)
+        repo = repo.strip()
+        branch = branch.strip()
+        if repo not in repos:
+            raise SystemExit(f"branch mapping references repo outside lane: {repo}")
+        if not branch:
+            raise SystemExit(f"empty branch in mapping: {item}")
+        branch_map[repo] = branch
+
+    missing = [repo for repo in repos if repo not in branch_map]
+    if missing:
+        raise SystemExit("missing branch mapping for repos: " + ", ".join(missing))
+
+    return branch_map
+
+
 def create_lane(args: argparse.Namespace) -> int:
     workspace_root = args.workspace_root.resolve()
     spec = load_workspace_spec(workspace_root)
+    unit_spec = find_unit_spec(workspace_root, args.owner_unit)
     repo_names = [item["name"] for item in spec.get("repos", [])]
-    repos = [repo.strip() for repo in args.repos.split(",") if repo.strip()]
+    repos = parse_repo_list(args.repos)
 
     missing = [repo for repo in repos if repo not in repo_names]
     if missing:
@@ -154,9 +579,10 @@ def create_lane(args: argparse.Namespace) -> int:
         schema_version=LANE_SCHEMA_VERSION,
         lane_name=args.lane_name,
         owner_unit=args.owner_unit,
+        agent_id=unit_spec.get("agent_id"),
         lane_type=args.type,
         repos=repos,
-        branch_map={repo: args.branch for repo in repos},
+        branch_map=parse_branch_arg(args.branch, repos),
         pr_associations=[],
         shared_context_roots=["config", ".grip/context/shared"],
         private_context_roots=[
@@ -167,6 +593,7 @@ def create_lane(args: argparse.Namespace) -> int:
             "parallelism": "workspace-default",
             "fail_fast": True,
             "default_command_family": ["build", "test"],
+            "commands": args.default_commands,
         },
         creation_source=args.source,
     )
@@ -175,20 +602,551 @@ def create_lane(args: argparse.Namespace) -> int:
     return 0
 
 
+def enter_lane(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    lane_doc = load_lane_doc(workspace_root, args.owner_unit, args.lane_name)
+    unit_spec = find_unit_spec(workspace_root, args.owner_unit)
+    path = current_lane_file(workspace_root, args.owner_unit)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    previous: list[dict] = []
+    if path.exists():
+        old = json.loads(path.read_text())
+        previous = old.get("recent", [])
+        current = old.get("current")
+        if current:
+            previous.insert(0, current)
+
+    deduped: list[dict] = []
+    seen: set[tuple[str, str]] = set()
+    for item in previous:
+        key = (item["owner_unit"], item["lane_name"])
+        if key in seen or key == (args.owner_unit, args.lane_name):
+            continue
+        seen.add(key)
+        deduped.append(item)
+    deduped = deduped[:5]
+
+    doc = {
+        "current": {
+            "owner_unit": args.owner_unit,
+            "agent_id": unit_spec.get("agent_id"),
+            "lane_name": args.lane_name,
+            "lane_type": lane_doc["lane_type"],
+            "repos": lane_doc.get("repos", []),
+            "actor": args.actor,
+            "entered_at": now_utc(),
+        },
+        "recent": deduped,
+    }
+    path.write_text(json.dumps(doc, indent=2) + "\n")
+    event = {
+        "type": "lane_enter",
+        "agent": args.actor,
+        "agent_id": unit_spec.get("agent_id"),
+        "owner_unit": args.owner_unit,
+        "lane": args.lane_name,
+        "lane_type": lane_doc["lane_type"],
+        "repos": lane_doc.get("repos", []),
+        "timestamp": now_utc(),
+    }
+    emit_lane_event(workspace_root, event)
+    if args.notify_channel:
+        event["channel_message"] = (
+            f'{args.actor} entered {args.owner_unit}/{args.lane_name} '
+            f'[{lane_doc["lane_type"]}] repos={",".join(lane_doc.get("repos", []))}'
+        )
+    if args.recall:
+        emit_recall_lane_event(
+            workspace_root,
+            {
+                "kind": "lane_transition",
+                "action": "enter",
+                "owner_unit": args.owner_unit,
+                "agent_id": unit_spec.get("agent_id"),
+                "actor": args.actor,
+                "lane": args.lane_name,
+                "lane_type": lane_doc["lane_type"],
+                "repos": lane_doc.get("repos", []),
+                "timestamp": event["timestamp"],
+            },
+        )
+    print(path)
+    return 0
+
+
+def exit_lane(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    doc = load_current_lane_doc(workspace_root, args.owner_unit)
+    current_doc = doc.get("current")
+    if not current_doc:
+        raise SystemExit(f"no current lane to exit for unit: {args.owner_unit}")
+    event = {
+        "type": "lane_exit",
+        "agent": args.actor,
+        "agent_id": current_doc.get("agent_id"),
+        "owner_unit": args.owner_unit,
+        "lane": current_doc["lane_name"],
+        "lane_type": current_doc["lane_type"],
+        "repos": current_doc.get("repos", []),
+        "timestamp": now_utc(),
+    }
+    emit_lane_event(workspace_root, event)
+    if args.notify_channel:
+        event["channel_message"] = (
+            f'{args.actor} exited {args.owner_unit}/{current_doc["lane_name"]} '
+            f'[{current_doc["lane_type"]}]'
+        )
+    if args.recall:
+        emit_recall_lane_event(
+            workspace_root,
+            {
+                "kind": "lane_transition",
+                "action": "exit",
+                "owner_unit": args.owner_unit,
+                "agent_id": current_doc.get("agent_id"),
+                "actor": args.actor,
+                "lane": current_doc["lane_name"],
+                "lane_type": current_doc["lane_type"],
+                "repos": current_doc.get("repos", []),
+                "timestamp": event["timestamp"],
+            },
+        )
+
+    recent = doc.get("recent", [])
+    next_current = recent[0] if recent else None
+    updated = {
+        "current": next_current,
+        "recent": recent[1:] if next_current else [],
+    }
+    current_lane_file(workspace_root, args.owner_unit).write_text(json.dumps(updated, indent=2) + "\n")
+    print(current_lane_file(workspace_root, args.owner_unit))
+    return 0
+
+
+def current_lane(args: argparse.Namespace) -> int:
+    doc = load_current_lane_doc(args.workspace_root.resolve(), args.owner_unit)
+    if args.json:
+        print(json.dumps(doc, indent=2))
+        return 0
+    current_doc = doc["current"]
+    print("gr2 prototype current-lane")
+    print(f'owner={current_doc["owner_unit"]} lane={current_doc["lane_name"]} type={current_doc["lane_type"]} actor={current_doc["actor"]}')
+    print(f'entered_at={current_doc["entered_at"]}')
+    recent = doc.get("recent", [])
+    if recent:
+        print("recent:")
+        for item in recent:
+            print(f'  - {item["owner_unit"]}/{item["lane_name"]} ({item["lane_type"]})')
+    return 0
+
+
+def lane_history(args: argparse.Namespace) -> int:
+    rows = [
+        event for event in iter_lane_events(args.workspace_root.resolve())
+        if event.get("owner_unit") == args.owner_unit
+    ]
+    if args.json:
+        print(json.dumps(rows, indent=2))
+        return 0
+    print("TIMESTAMP\tTYPE\tACTOR\tAGENT_ID\tLANE\tREPOS")
+    for row in rows:
+        print(
+            f'{row.get("timestamp","-")}\t{row.get("type","-")}\t{row.get("agent","-")}\t{row.get("agent_id","-")}\t{row.get("lane","-")}\t{",".join(row.get("repos", []))}'
+        )
+    return 0
+
+
+def acquire_lane_lease(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    load_lane_doc(workspace_root, args.owner_unit, args.lane_name)
+    result = mutate_lane_leases(
+        workspace_root,
+        args.owner_unit,
+        args.lane_name,
+        lambda leases: _acquire_lane_lease_mutation(leases, args),
+    )
+    if result["status"] == "blocked":
+        print(json.dumps(result["payload"], indent=2))
+        return 1
+    if result["status"] == "warning":
+        print(json.dumps(result["warning"], indent=2))
+    lane_doc = load_lane_doc(workspace_root, args.owner_unit, args.lane_name)
+    unit_spec = find_unit_spec(workspace_root, args.owner_unit)
+    emit_lane_event(
+        workspace_root,
+        {
+            "type": "lease_acquire",
+            "agent": args.actor,
+            "agent_id": unit_spec.get("agent_id"),
+            "owner_unit": args.owner_unit,
+            "lane": args.lane_name,
+            "lane_type": lane_doc["lane_type"],
+            "lease_mode": args.mode,
+            "ttl_seconds": args.ttl_seconds,
+            "repos": lane_doc.get("repos", []),
+            "timestamp": now_utc(),
+        },
+    )
+    print(lane_leases_file(workspace_root, args.owner_unit, args.lane_name))
+    return 0
+
+
+def _acquire_lane_lease_mutation(leases: list[dict], args: argparse.Namespace) -> dict:
+    retained = [lease for lease in leases if lease["actor"] != args.actor]
+    active_conflicts, stale_conflicts = conflicting_leases(retained, args.actor, args.mode)
+
+    if active_conflicts:
+        return {
+            "status": "blocked",
+            "payload": {
+                "status": "blocked",
+                "reason": "conflicting-active-lease",
+                "lane": args.lane_name,
+                "owner_unit": args.owner_unit,
+                "requested": {"actor": args.actor, "mode": args.mode},
+                "conflicting_leases": active_conflicts,
+            },
+            "write": False,
+        }
+
+    if stale_conflicts and not args.force:
+        return {
+            "status": "blocked",
+            "payload": {
+                "status": "blocked",
+                "reason": "stale-conflicting-lease",
+                "lane": args.lane_name,
+                "owner_unit": args.owner_unit,
+                "requested": {"actor": args.actor, "mode": args.mode},
+                "conflicting_leases": stale_conflicts,
+                "hint": "rerun with --force to break stale conflicting leases",
+            },
+            "write": False,
+        }
+
+    warning = None
+    if stale_conflicts and args.force:
+        warning = {
+            "status": "warning",
+            "reason": "breaking-stale-conflicting-leases",
+            "broken_leases": stale_conflicts,
+        }
+        stale_actors = {lease["actor"] for lease in stale_conflicts}
+        retained = [lease for lease in retained if lease["actor"] not in stale_actors]
+
+    retained.append(build_lease(args.actor, args.mode, args.ttl_seconds))
+    return {
+        "status": "warning" if warning else "ok",
+        "warning": warning,
+        "leases": retained,
+        "write": True,
+    }
+
+
+def release_lane_lease(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    lane_doc = load_lane_doc(workspace_root, args.owner_unit, args.lane_name)
+    unit_spec = find_unit_spec(workspace_root, args.owner_unit)
+    mutate_lane_leases(
+        workspace_root,
+        args.owner_unit,
+        args.lane_name,
+        lambda leases: {
+            "status": "ok",
+            "leases": [lease for lease in leases if lease["actor"] != args.actor],
+            "write": True,
+        },
+    )
+    emit_lane_event(
+        workspace_root,
+        {
+            "type": "lease_release",
+            "agent": args.actor,
+            "agent_id": unit_spec.get("agent_id"),
+            "owner_unit": args.owner_unit,
+            "lane": args.lane_name,
+            "lane_type": lane_doc["lane_type"],
+            "repos": lane_doc.get("repos", []),
+            "timestamp": now_utc(),
+        },
+    )
+    print(lane_leases_file(workspace_root, args.owner_unit, args.lane_name))
+    return 0
+
+
+def show_lane_leases(args: argparse.Namespace) -> int:
+    leases = load_lane_leases(args.workspace_root.resolve(), args.owner_unit, args.lane_name)
+    if args.json:
+        print(json.dumps(leases, indent=2))
+        return 0
+    print("ACTOR\tMODE\tTTL\tACQUIRED_AT\tEXPIRES_AT\tSTATE")
+    for lease in leases:
+        state = "stale" if is_stale_lease(lease) else "active"
+        print(
+            f'{lease["actor"]}\t{lease["mode"]}\t{lease.get("ttl_seconds", "-")}\t{lease["acquired_at"]}\t{lease.get("expires_at", "-")}\t{state}'
+        )
+    return 0
+
+
+def create_review_lane(args: argparse.Namespace) -> int:
+    lane_name = args.lane_name or f"review-{args.pr_number}"
+    branch = args.branch or f"pr/{args.pr_number}"
+    create_args = argparse.Namespace(
+        workspace_root=args.workspace_root,
+        owner_unit=args.owner_unit,
+        lane_name=lane_name,
+        type="review",
+        repos=args.repo,
+        branch=f"{args.repo}={branch}",
+        source="pull-request",
+        default_commands=[],
+    )
+    create_lane(create_args)
+    lane_path = lane_file(args.workspace_root.resolve(), args.owner_unit, lane_name)
+    content = lane_path.read_text().rstrip()
+    content += f'\n\n[[pr_associations]]\nref = "{args.repo}#{args.pr_number}"\n'
+    lane_path.write_text(content)
+    print(f"created review lane {args.owner_unit}/{lane_name} for {args.repo}#{args.pr_number}")
+    return 0
+
+
+def create_shared_scratchpad(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    root = shared_scratchpad_dir(workspace_root, args.name)
+    root.mkdir(parents=True, exist_ok=True)
+    (root / "docs").mkdir(exist_ok=True)
+    (root / "notes").mkdir(exist_ok=True)
+    (root / "context").mkdir(exist_ok=True)
+
+    scratchpad = SharedScratchpad(
+        schema_version=SCRATCHPAD_SCHEMA_VERSION,
+        name=args.name,
+        kind=args.kind,
+        purpose=args.purpose,
+        participants=sorted(set(args.participant)),
+        linked_refs=args.ref,
+        lifecycle="draft",
+        creation_source=args.source,
+        docs_root=f"shared/scratchpads/{args.name}/docs",
+        notes_root=f"shared/scratchpads/{args.name}/notes",
+        context_root=f"shared/scratchpads/{args.name}/context",
+        created_at=now_utc(),
+        updated_at=now_utc(),
+    )
+    shared_scratchpad_file(workspace_root, args.name).write_text(scratchpad.as_toml())
+    readme = root / "docs" / "README.md"
+    if not readme.exists():
+        readme.write_text(
+            f"# {args.name}\n\nPurpose: {args.purpose}\n\nParticipants: "
+            + (", ".join(scratchpad.participants) if scratchpad.participants else "unassigned")
+            + "\n"
+        )
+    print(shared_scratchpad_file(workspace_root, args.name))
+    return 0
+
+
+def list_lanes(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    print("OWNER\tLANE\tTYPE\tREPOS\tPRS")
+    for path in iter_lane_files(workspace_root, args.owner_unit):
+        doc = tomllib.loads(path.read_text())
+        refs = ",".join(item["ref"] for item in doc.get("pr_associations", [])) or "-"
+        print(
+            f'{doc["owner_unit"]}\t{doc["lane_name"]}\t{doc["lane_type"]}\t{len(doc.get("repos", []))}\t{refs}'
+        )
+    return 0
+
+
 def show_lane(args: argparse.Namespace) -> int:
     print(lane_file(args.workspace_root.resolve(), args.owner_unit, args.lane_name).read_text())
     return 0
 
 
-def plan_exec(args: argparse.Namespace) -> int:
+def show_shared_scratchpad(args: argparse.Namespace) -> int:
+    print(shared_scratchpad_file(args.workspace_root.resolve(), args.name).read_text())
+    return 0
+
+
+def list_shared_scratchpads(args: argparse.Namespace) -> int:
     workspace_root = args.workspace_root.resolve()
-    lane_doc = tomllib.loads(
-        lane_file(workspace_root, args.owner_unit, args.lane_name).read_text()
+    print("NAME\tKIND\tLIFECYCLE\tAGE_DAYS\tPARTICIPANTS\tPURPOSE")
+    for path in iter_shared_scratchpad_files(workspace_root):
+        doc = tomllib.loads(path.read_text())
+        participants = ",".join(doc.get("participants", [])) or "-"
+        print(
+            f'{doc["name"]}\t{doc["kind"]}\t{doc["lifecycle"]}\t{age_days(path)}\t{participants}\t{doc["purpose"]}'
+        )
+    return 0
+
+
+def audit_shared_scratchpads(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    print("NAME\tSTATUS\tAGE_DAYS\tISSUES")
+    for path in iter_shared_scratchpad_files(workspace_root):
+        doc = tomllib.loads(path.read_text())
+        root = path.parent
+        issues: list[str] = []
+        days = age_days(path)
+        docs_root = root / "docs"
+        notes_root = root / "notes"
+        context_root = root / "context"
+
+        if days >= args.stale_days and doc.get("lifecycle") not in {"done", "paused"}:
+            issues.append("stale-active")
+        if not doc.get("participants"):
+            issues.append("no-participants")
+        if not doc.get("linked_refs"):
+            issues.append("no-refs")
+        if not docs_root.exists():
+            issues.append("missing-docs-root")
+        if not notes_root.exists():
+            issues.append("missing-notes-root")
+        if not context_root.exists():
+            issues.append("missing-context-root")
+        if doc.get("kind") == "doc" and not any(docs_root.iterdir()):
+            issues.append("empty-docs")
+
+        status = "ok" if not issues else "needs-attention"
+        print(f'{doc["name"]}\t{status}\t{days}\t{",".join(issues) or "-"}')
+    return 0
+
+
+def plan_promote_scratchpad(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    doc = load_shared_scratchpad_doc(workspace_root, args.name)
+    lane_name = args.lane or f"promote-{args.name}"
+    print("gr2 prototype scratchpad-promotion plan")
+    print(f'scratchpad: {doc["name"]}')
+    print(f'kind: {doc["kind"]}')
+    print(f'lifecycle: {doc["lifecycle"]}')
+    print(f'target repo: {args.target_repo}')
+    print(f'target path: {args.target_path}')
+    print(f'owner unit: {args.owner_unit}')
+    print(f'suggested lane: {lane_name}')
+    print("recommended:")
+    print(
+        f"  1. create or reuse a feature lane for {args.target_repo} under {args.owner_unit}"
+    )
+    print(
+        f"  2. copy content from shared/scratchpads/{doc['name']}/docs into {args.target_repo}:{args.target_path}"
     )
+    print(f"  3. branch and commit in lane {lane_name}")
+    print("  4. open a PR once the artifact is ready for formal review")
+    if not doc.get("linked_refs"):
+        print("warning: scratchpad has no linked refs; traceability should be added before promotion")
+    return 0
+
+
+def recommend_surface(args: argparse.Namespace) -> int:
+    recommendation = "feature-lane"
+    rationale: list[str] = []
+
+    if args.kind == "review" or args.formal_review:
+        recommendation = "review-lane"
+        rationale.append("formal review or PR inspection should stay isolated")
+    elif args.kind in {"doc", "planning"} and args.collaborative:
+        recommendation = "shared-scratchpad"
+        rationale.append("shared drafting is lighter than a PR and should not invade private lanes")
+    elif args.shared_draft:
+        recommendation = "shared-scratchpad"
+        rationale.append("explicit shared draft requested")
+    elif args.kind == "code" and args.repos > 1:
+        recommendation = "feature-lane"
+        rationale.append("cross-repo implementation needs one named task context")
+    elif args.kind == "code":
+        recommendation = "feature-lane"
+        rationale.append("private implementation should start in an isolated lane")
+    else:
+        recommendation = "feature-lane"
+        rationale.append("default safe choice is an isolated lane")
+
+    print("gr2 prototype surface recommendation")
+    print(f"recommended: {recommendation}")
+    print(f"why: {'; '.join(rationale)}")
+    print("rules:")
+    print("  - use a review lane for formal PR inspection")
+    print("  - use a shared scratchpad for collaborative drafting")
+    print("  - use a feature lane for implementation work")
+    return 0
+
+
+def next_step(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    lane_doc = load_lane_doc(workspace_root, args.owner_unit, args.lane_name)
+    print("gr2 prototype next-step")
+    print(f'lane: {args.owner_unit}/{lane_doc["lane_name"]}')
+    print(f'type: {lane_doc["lane_type"]}')
+    print(f'repos: {", ".join(lane_doc["repos"])}')
+    if lane_doc.get("pr_associations"):
+        print("mode: review")
+        print("recommended:")
+        print(
+            f"  python3 gr2/prototypes/lane_workspace_prototype.py plan-exec {workspace_root} {args.owner_unit} {args.lane_name} 'cargo test'"
+        )
+        print("  inspect the review lane, then return to your feature or home lane")
+    elif lane_doc["lane_type"] == "feature":
+        print("mode: feature")
+        print("recommended:")
+        print(
+            f"  python3 gr2/prototypes/lane_workspace_prototype.py plan-exec {workspace_root} {args.owner_unit} {args.lane_name} 'cargo test'"
+        )
+        print(
+            f"  python3 gr2/prototypes/lane_workspace_prototype.py list-shared-scratchpads {workspace_root}"
+        )
+    else:
+        print("mode: general")
+        print("recommended:")
+        print(
+            f"  python3 gr2/prototypes/lane_workspace_prototype.py show-lane {workspace_root} {args.owner_unit} {args.lane_name}"
+        )
+    return 0
+
+
+def plan_exec(args: argparse.Namespace) -> int:
+    workspace_root = args.workspace_root.resolve()
+    lane_doc = load_lane_doc(workspace_root, args.owner_unit, args.lane_name)
+    leases = load_lane_leases(workspace_root, args.owner_unit, args.lane_name)
+    active_conflicts, stale_conflicts = conflicting_leases(leases, "agent:exec-planner", "exec")
+    if active_conflicts:
+        payload = {
+            "status": "blocked",
+            "reason": "conflicting-active-lease",
+            "lane": lane_doc["lane_name"],
+            "owner_unit": lane_doc["owner_unit"],
+            "requested_mode": "exec",
+            "conflicting_leases": active_conflicts,
+        }
+        if args.json:
+            print(json.dumps(payload, indent=2))
+        else:
+            print("gr2 lane-exec prototype")
+            print("status=blocked reason=conflicting-active-lease")
+            for lease in active_conflicts:
+                print(f'conflict: actor={lease["actor"]} mode={lease["mode"]} acquired_at={lease["acquired_at"]}')
+        return 0
+    if stale_conflicts:
+        payload = {
+            "status": "blocked",
+            "reason": "stale-conflicting-lease",
+            "lane": lane_doc["lane_name"],
+            "owner_unit": lane_doc["owner_unit"],
+            "requested_mode": "exec",
+            "conflicting_leases": stale_conflicts,
+            "hint": "break stale leases with acquire-lane-lease --force or clean them up first",
+        }
+        if args.json:
+            print(json.dumps(payload, indent=2))
+        else:
+            print("gr2 lane-exec prototype")
+            print("status=blocked reason=stale-conflicting-lease")
+            for lease in stale_conflicts:
+                print(f'stale-conflict: actor={lease["actor"]} mode={lease["mode"]} expires_at={lease.get("expires_at", "-")}')
+        return 0
 
     selected_repos = lane_doc["repos"]
     if args.repos:
-        requested = [repo.strip() for repo in args.repos.split(",") if repo.strip()]
+        requested = parse_repo_list(args.repos)
         selected_repos = [repo for repo in selected_repos if repo in requested]
 
     command_argv = shlex.split(args.command_text)
@@ -200,7 +1158,15 @@ def plan_exec(args: argparse.Namespace) -> int:
                 "owner_unit": lane_doc["owner_unit"],
                 "repo": repo,
                 "branch": lane_doc["branch_map"].get(repo),
-                "cwd": str(workspace_root / "agents" / args.owner_unit / "lanes" / args.lane_name / "repos" / repo),
+                "cwd": str(
+                    workspace_root
+                    / "agents"
+                    / args.owner_unit
+                    / "lanes"
+                    / args.lane_name
+                    / "repos"
+                    / repo
+                ),
                 "command": command_argv,
                 "shared_context_roots": lane_doc.get("context", {}).get("shared_roots", []),
                 "private_context_roots": lane_doc.get("context", {}).get("private_roots", []),
@@ -212,10 +1178,13 @@ def plan_exec(args: argparse.Namespace) -> int:
         print(json.dumps(rows, indent=2))
     else:
         print("gr2 lane-exec prototype")
+        print(
+            f'owner={lane_doc["owner_unit"]} lane={lane_doc["lane_name"]} type={lane_doc["lane_type"]} fail_fast={lane_doc["exec_defaults"]["fail_fast"]}'
+        )
         print("LANE\tREPO\tBRANCH\tCWD\tCOMMAND")
         for row in rows:
             print(
-                f"{row['lane']}\t{row['repo']}\t{row['branch']}\t{row['cwd']}\t{' '.join(row['command'])}"
+                f'{row["lane"]}\t{row["repo"]}\t{row["branch"]}\t{row["cwd"]}\t{" ".join(row["command"])}'
             )
     return 0
 
@@ -224,10 +1193,42 @@ def main() -> int:
     args = parse_args()
     if args.command == "create-lane":
         return create_lane(args)
+    if args.command == "enter-lane":
+        return enter_lane(args)
+    if args.command == "exit-lane":
+        return exit_lane(args)
+    if args.command == "current-lane":
+        return current_lane(args)
+    if args.command == "lane-history":
+        return lane_history(args)
+    if args.command == "create-review-lane":
+        return create_review_lane(args)
     if args.command == "show-lane":
         return show_lane(args)
+    if args.command == "list-lanes":
+        return list_lanes(args)
+    if args.command == "next-step":
+        return next_step(args)
     if args.command == "plan-exec":
         return plan_exec(args)
+    if args.command == "acquire-lane-lease":
+        return acquire_lane_lease(args)
+    if args.command == "release-lane-lease":
+        return release_lane_lease(args)
+    if args.command == "show-lane-leases":
+        return show_lane_leases(args)
+    if args.command == "create-shared-scratchpad":
+        return create_shared_scratchpad(args)
+    if args.command == "show-shared-scratchpad":
+        return show_shared_scratchpad(args)
+    if args.command == "list-shared-scratchpads":
+        return list_shared_scratchpads(args)
+    if args.command == "audit-shared-scratchpads":
+        return audit_shared_scratchpads(args)
+    if args.command == "plan-promote-scratchpad":
+        return plan_promote_scratchpad(args)
+    if args.command == "recommend-surface":
+        return recommend_surface(args)
     raise SystemExit(f"unknown command: {args.command}")
 
 
diff --git a/gr2/prototypes/layout_model_probe.py b/gr2/prototypes/layout_model_probe.py
new file mode 100644
index 00000000..939eca61
--- /dev/null
+++ b/gr2/prototypes/layout_model_probe.py
@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""Assess which workspace layout model best matches the observed gr2 behavior.
+
+This is a UX prototype. It does not prescribe the final architecture on its own.
+It makes the current mismatch explicit so we can iterate with evidence.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import tomllib
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Probe observed gr2 layout vs candidate models")
+    parser.add_argument("workspace_root", type=Path)
+    parser.add_argument("--owner-unit", required=True)
+    parser.add_argument("--json", action="store_true")
+    return parser.parse_args()
+
+
+def load_spec(workspace_root: Path) -> dict:
+    with (workspace_root / ".grip" / "workspace_spec.toml").open("rb") as fh:
+        return tomllib.load(fh)
+
+
+def repo_names(spec: dict) -> list[str]:
+    return [repo["name"] for repo in spec.get("repos", [])]
+
+
+def probe(workspace_root: Path, owner_unit: str) -> dict:
+    spec = load_spec(workspace_root)
+    repos = repo_names(spec)
+    observations: list[dict[str, object]] = []
+    shared_git_count = 0
+    unit_git_count = 0
+
+    for repo in repos:
+        shared_root = workspace_root / "repos" / repo
+        unit_root = workspace_root / "agents" / owner_unit / repo
+        lane_root = workspace_root / "agents" / owner_unit / "lanes" / "feat-auth" / "repos" / repo
+
+        shared_git = (shared_root / ".git").exists()
+        unit_git = (unit_root / ".git").exists()
+        lane_git = (lane_root / ".git").exists()
+        shared_exists = shared_root.exists()
+        unit_exists = unit_root.exists()
+
+        if shared_git:
+            shared_git_count += 1
+        if unit_git:
+            unit_git_count += 1
+
+        observations.append(
+            {
+                "repo": repo,
+                "shared_path_exists": shared_exists,
+                "shared_git": shared_git,
+                "unit_path_exists": unit_exists,
+                "unit_git": unit_git,
+                "lane_git": lane_git,
+            }
+        )
+
+    shared_first_score = 0
+    unit_first_score = 0
+    reasons: list[str] = []
+
+    if unit_git_count == len(repos):
+        unit_first_score += 3
+        reasons.append("all repos materialized as unit-local git checkouts")
+    if shared_git_count == len(repos):
+        shared_first_score += 3
+        reasons.append("all repos materialized as shared git checkouts")
+    if shared_git_count == 0 and any(item["shared_path_exists"] for item in observations):
+        unit_first_score += 2
+        reasons.append("shared repo paths exist as placeholders rather than active checkouts")
+    if any(item["lane_git"] for item in observations):
+        shared_first_score += 1
+        unit_first_score += 1
+        reasons.append("lane-local repo materialization exists, so a routed model may be emerging")
+    else:
+        unit_first_score += 1
+        reasons.append("lane-local repos are not yet materialized")
+
+    if unit_first_score > shared_first_score:
+        recommendation = "ratify-unit-local-first"
+        summary = (
+            "Current behavior matches a unit-local-first model more closely than a shared-repo-first model."
+        )
+    elif shared_first_score > unit_first_score:
+        recommendation = "push-shared-repo-model"
+        summary = (
+            "Current behavior already resembles a shared-repo-first model strongly enough to continue that direction."
+        )
+    else:
+        recommendation = "hybrid-needs-clarification"
+        summary = "Observed behavior is split enough that the model should be clarified explicitly."
+
+    return {
+        "owner_unit": owner_unit,
+        "recommendation": recommendation,
+        "summary": summary,
+        "shared_first_score": shared_first_score,
+        "unit_first_score": unit_first_score,
+        "reasons": reasons,
+        "observations": observations,
+    }
+
+
+def main() -> int:
+    args = parse_args()
+    result = probe(args.workspace_root.resolve(), args.owner_unit)
+    if args.json:
+        print(json.dumps(result, indent=2))
+        return 0
+
+    print("gr2 prototype layout-model probe")
+    print(f"owner: {result['owner_unit']}")
+    print(f"recommendation: {result['recommendation']}")
+    print(f"summary: {result['summary']}")
+    print(f"score shared-first={result['shared_first_score']} unit-local-first={result['unit_first_score']}")
+    print("reasons:")
+    for reason in result["reasons"]:
+        print(f"- {reason}")
+    print("observations:")
+    print("REPO\tSHARED_PATH\tSHARED_GIT\tUNIT_PATH\tUNIT_GIT\tLANE_GIT")
+    for row in result["observations"]:
+        print(
+            f"{row['repo']}\t{str(row['shared_path_exists']).lower()}\t{str(row['shared_git']).lower()}\t"
+            f"{str(row['unit_path_exists']).lower()}\t{str(row['unit_git']).lower()}\t{str(row['lane_git']).lower()}"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/gr2/prototypes/real_git_lane_materialization.py b/gr2/prototypes/real_git_lane_materialization.py
new file mode 100644
index 00000000..7068c176
--- /dev/null
+++ b/gr2/prototypes/real_git_lane_materialization.py
@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""Prototype real-git same-repo multi-agent lane materialization."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Verify real-git same-repo lane materialization"
+    )
+    parser.add_argument(
+        "--workspace-root",
+        type=Path,
+        help="optional workspace root; defaults to a temporary workspace",
+    )
+    parser.add_argument("--json", action="store_true")
+    return parser.parse_args()
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def lane_proto(root: Path) -> Path:
+    return root / "gr2" / "prototypes" / "lane_workspace_prototype.py"
+
+
+def run(
+    argv: list[str],
+    *,
+    cwd: Path | None = None,
+    capture: bool = False,
+    check: bool = True,
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        argv,
+        cwd=cwd,
+        check=check,
+        text=True,
+        capture_output=capture,
+    )
+
+
+def init_workspace(workspace_root: Path, bare_remote: Path) -> None:
+    (workspace_root / ".grip").mkdir(parents=True, exist_ok=True)
+    (workspace_root / "agents").mkdir(exist_ok=True)
+    spec = f"""schema_version = 1
+workspace_name = "real-git-lane-materialization"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{bare_remote}"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+agent_id = "atlas-agent"
+repos = ["app"]
+
+[[units]]
+name = "apollo"
+path = "agents/apollo"
+agent_id = "apollo-agent"
+repos = ["app"]
+"""
+    (workspace_root / ".grip" / "workspace_spec.toml").write_text(spec)
+
+
+def seed_bare_remote(root: Path) -> Path:
+    remotes = root / "remotes"
+    work = root / "seed-work"
+    remotes.mkdir(parents=True, exist_ok=True)
+    run(["git", "init", "--bare", str(remotes / "app.git")])
+    run(["git", "init", str(work)])
+    run(["git", "config", "user.name", "Playground User"], cwd=work)
+    run(["git", "config", "user.email", "playground@example.com"], cwd=work)
+    (work / "README.md").write_text("# app\n")
+    run(["git", "add", "README.md"], cwd=work)
+    run(["git", "commit", "-m", "Initial commit"], cwd=work)
+    run(["git", "branch", "-M", "main"], cwd=work)
+    run(["git", "remote", "add", "origin", str(remotes / "app.git")], cwd=work)
+    run(["git", "push", "-u", "origin", "main"], cwd=work)
+    return remotes / "app.git"
+
+
+def create_lane(
+    root: Path, workspace_root: Path, owner_unit: str, lane_name: str, branch: str
+) -> None:
+    run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "create-lane",
+            str(workspace_root),
+            owner_unit,
+            lane_name,
+            "--repos",
+            "app",
+            "--branch",
+            branch,
+        ]
+    )
+
+
+def plan_exec_json(
+    root: Path, workspace_root: Path, owner_unit: str, lane_name: str
+) -> list[dict]:
+    proc = run(
+        [
+            "python3",
+            str(lane_proto(root)),
+            "plan-exec",
+            str(workspace_root),
+            owner_unit,
+            lane_name,
+            "git status",
+            "--json",
+        ],
+        capture=True,
+    )
+    return json.loads(proc.stdout)
+
+
+def configure_checkout(repo_path: Path, user_name: str, user_email: str) -> None:
+    run(["git", "config", "user.name", user_name], cwd=repo_path)
+    run(["git", "config", "user.email", user_email], cwd=repo_path)
+
+
+def clone_into_lane(
+    remote: Path, cwd_path: Path, branch: str, user_name: str, user_email: str
+) -> None:
+    cwd_path.parent.mkdir(parents=True, exist_ok=True)
+    run(["git", "clone", str(remote), str(cwd_path)])
+    configure_checkout(cwd_path, user_name, user_email)
+    run(["git", "checkout", "-b", branch], cwd=cwd_path)
+
+
+def commit_lane_change(
+    repo_path: Path, filename: str, contents: str, message: str
+) -> str:
+    (repo_path / filename).write_text(contents)
+    run(["git", "add", filename], cwd=repo_path)
+    run(["git", "commit", "-m", message], cwd=repo_path)
+    proc = run(["git", "rev-parse", "HEAD"], cwd=repo_path, capture=True)
+    return proc.stdout.strip()
+
+
+def verify(workspace_root: Path) -> dict:
+    root = repo_root()
+    remote = seed_bare_remote(workspace_root / ".tmp")
+    init_workspace(workspace_root, remote)
+
+    create_lane(root, workspace_root, "atlas", "feat-router", "feat/router")
+    create_lane(root, workspace_root, "apollo", "feat-materialize", "feat/materialize")
+
+    atlas_plan = plan_exec_json(root, workspace_root, "atlas", "feat-router")
+    apollo_plan = plan_exec_json(root, workspace_root, "apollo", "feat-materialize")
+
+    atlas_cwd = Path(atlas_plan[0]["cwd"])
+    apollo_cwd = Path(apollo_plan[0]["cwd"])
+
+    clone_into_lane(remote, atlas_cwd, "feat/router", "Atlas User", "atlas@example.com")
+    clone_into_lane(
+        remote,
+        apollo_cwd,
+        "feat/materialize",
+        "Apollo User",
+        "apollo@example.com",
+    )
+
+    atlas_commit = commit_lane_change(
+        atlas_cwd, "atlas.txt", "atlas lane change\n", "atlas lane commit"
+    )
+    apollo_commit = commit_lane_change(
+        apollo_cwd, "apollo.txt", "apollo lane change\n", "apollo lane commit"
+    )
+
+    atlas_status = run(["git", "status", "--short"], cwd=atlas_cwd, capture=True).stdout.strip()
+    apollo_status = run(["git", "status", "--short"], cwd=apollo_cwd, capture=True).stdout.strip()
+
+    result = {
+        "atlas_cwd": str(atlas_cwd),
+        "apollo_cwd": str(apollo_cwd),
+        "cwd_collision": atlas_cwd == apollo_cwd,
+        "atlas_commit": atlas_commit,
+        "apollo_commit": apollo_commit,
+        "commit_collision": atlas_commit == apollo_commit,
+        "atlas_has_apollo_file": (atlas_cwd / "apollo.txt").exists(),
+        "apollo_has_atlas_file": (apollo_cwd / "atlas.txt").exists(),
+        "atlas_clean": atlas_status == "",
+        "apollo_clean": apollo_status == "",
+    }
+    result["verdict"] = (
+        "holds"
+        if not result["cwd_collision"]
+        and not result["commit_collision"]
+        and not result["atlas_has_apollo_file"]
+        and not result["apollo_has_atlas_file"]
+        and result["atlas_clean"]
+        and result["apollo_clean"]
+        else "fails"
+    )
+    return result
+
+
+def main() -> int:
+    args = parse_args()
+    if args.workspace_root:
+        workspace_root = args.workspace_root.resolve()
+        if workspace_root.exists():
+            shutil.rmtree(workspace_root)
+        workspace_root.mkdir(parents=True, exist_ok=True)
+        result = verify(workspace_root)
+    else:
+        with tempfile.TemporaryDirectory(prefix="gr2-real-git-lanes-") as tmp:
+            workspace_root = Path(tmp)
+            result = verify(workspace_root)
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print("gr2 real-git same-repo lane materialization")
+        print(f'workspace: {workspace_root}')
+        print(f'verdict: {result["verdict"]}')
+        print(f'atlas cwd: {result["atlas_cwd"]}')
+        print(f'apollo cwd: {result["apollo_cwd"]}')
+        print(f'cwd collision: {result["cwd_collision"]}')
+        print(f'commit collision: {result["commit_collision"]}')
+        print(f'atlas sees apollo file: {result["atlas_has_apollo_file"]}')
+        print(f'apollo sees atlas file: {result["apollo_has_atlas_file"]}')
+        print(f'atlas clean: {result["atlas_clean"]}')
+        print(f'apollo clean: {result["apollo_clean"]}')
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/gr2/prototypes/real_git_playground.py b/gr2/prototypes/real_git_playground.py
new file mode 100644
index 00000000..e140c883
--- /dev/null
+++ b/gr2/prototypes/real_git_playground.py
@@ -0,0 +1,465 @@
+#!/usr/bin/env python3
+"""Bootstrap and verify a real-git gr2 playground workspace.
+
+This harness is intentionally pragmatic:
+
+- it uses actual GitHub repos in synapt-dev
+- it exercises the current shipped gr2 surfaces against real remotes
+- it combines current gr2 commands with prototype-only scratchpad commands
+
+The goal is not to pretend gr2 is further along than it is. The goal is to
+pressure the UX against real git state so we can iterate with data.
+"""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+PLAYGROUND_REPOS = {
+    "app": {
+        "ssh": "git@github.com:synapt-dev/gr2-playground-app.git",
+        "https": "https://github.com/synapt-dev/gr2-playground-app.git",
+    },
+    "api": {
+        "ssh": "git@github.com:synapt-dev/gr2-playground-api.git",
+        "https": "https://github.com/synapt-dev/gr2-playground-api.git",
+    },
+    "web": {
+        "ssh": "git@github.com:synapt-dev/gr2-playground-web.git",
+        "https": "https://github.com/synapt-dev/gr2-playground-web.git",
+    },
+}
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Bootstrap a real-git gr2 playground workspace"
+    )
+    parser.add_argument("workspace_root", type=Path)
+    parser.add_argument("--owner-unit", default="atlas")
+    parser.add_argument("--workspace-name", default="gr2-real-git-playground")
+    parser.add_argument(
+        "--keep-existing",
+        action="store_true",
+        help="reuse an existing workspace root instead of failing",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["ssh", "https"],
+        default="ssh",
+        help="git remote transport to use for playground repos",
+    )
+    return parser.parse_args()
+
+
+def repo_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def gr2_binary(root: Path) -> Path:
+    binary = root / "target" / "debug" / "gr2"
+    if binary.exists():
+        return binary
+    run(["cargo", "build", "--quiet", "--bin", "gr2"], cwd=root)
+    return binary
+
+
+def lane_proto(root: Path) -> Path:
+    return root / "gr2" / "prototypes" / "lane_workspace_prototype.py"
+
+
+def transport_probe(root: Path) -> Path:
+    return root / "gr2" / "prototypes" / "repo_transport_probe.py"
+
+
+def layout_probe(root: Path) -> Path:
+    return root / "gr2" / "prototypes" / "layout_model_probe.py"
+
+
+def repo_url(repo_name: str, transport: str) -> str:
+    return PLAYGROUND_REPOS[repo_name][transport]
+
+
+def run(
+    argv: list[str],
+    *,
+    cwd: Path | None = None,
+    capture: bool = False,
+) -> subprocess.CompletedProcess[str]:
+    print("+", " ".join(argv))
+    return subprocess.run(
+        argv,
+        cwd=cwd,
+        check=True,
+        text=True,
+        capture_output=capture,
+    )
+
+
+def gr2_supports_exec(gr2: Path) -> bool:
+    help_out = run([str(gr2), "--help"], capture=True)
+    return "\n  exec" in help_out.stdout
+
+
+def write_workspace_spec(
+    workspace_root: Path, owner_unit: str, workspace_name: str, transport: str
+) -> None:
+    spec = f"""schema_version = 1
+workspace_name = "{workspace_name}"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "{repo_url("app", transport)}"
+
+[[repos]]
+name = "api"
+path = "repos/api"
+url = "{repo_url("api", transport)}"
+
+[[repos]]
+name = "web"
+path = "repos/web"
+url = "{repo_url("web", transport)}"
+
+[[units]]
+name = "{owner_unit}"
+path = "agents/{owner_unit}"
+repos = ["app", "api", "web"]
+"""
+    spec_path = workspace_root / ".grip" / "workspace_spec.toml"
+    spec_path.write_text(spec)
+
+
+def ensure(condition: bool, message: str) -> None:
+    if not condition:
+        raise SystemExit(message)
+
+
+def unit_repo_path(workspace_root: Path, owner_unit: str, repo_name: str) -> Path:
+    return workspace_root / "agents" / owner_unit / repo_name
+
+
+def verify_paths(workspace_root: Path, owner_unit: str) -> None:
+    for rel in [
+        ".grip/workspace.toml",
+        ".grip/workspace_spec.toml",
+        f"agents/{owner_unit}/app/.git",
+        f"agents/{owner_unit}/api/.git",
+        f"agents/{owner_unit}/web/.git",
+        f".grip/state/lanes/{owner_unit}/feat-auth.toml",
+        f".grip/state/lanes/{owner_unit}/feat-web.toml",
+        f".grip/state/lanes/{owner_unit}/review-app-123.toml",
+        "shared/scratchpads/blog-draft/scratchpad.toml",
+    ]:
+        ensure((workspace_root / rel).exists(), f"expected path missing: {rel}")
+
+
+def main() -> int:
+    args = parse_args()
+    root = repo_root()
+    workspace_root = args.workspace_root.resolve()
+
+    if workspace_root.exists() and not args.keep_existing:
+        if any(workspace_root.iterdir()):
+            raise SystemExit(
+                f"workspace root already exists and is not empty: {workspace_root} "
+                "(pass --keep-existing to reuse)"
+            )
+        workspace_root.rmdir()
+
+    gr2 = gr2_binary(root)
+    lane_script = lane_proto(root)
+    probe_script = transport_probe(root)
+    layout_script = layout_probe(root)
+    has_exec = gr2_supports_exec(gr2)
+
+    if not workspace_root.exists():
+        run(
+            [
+                str(gr2),
+                "init",
+                str(workspace_root),
+                "--name",
+                args.workspace_name,
+            ],
+            cwd=root,
+        )
+
+    run([str(gr2), "unit", "add", args.owner_unit], cwd=workspace_root)
+
+    for repo_name in PLAYGROUND_REPOS:
+        run(
+            [str(gr2), "repo", "add", repo_name, repo_url(repo_name, args.transport)],
+            cwd=workspace_root,
+        )
+
+    write_workspace_spec(
+        workspace_root, args.owner_unit, args.workspace_name, args.transport
+    )
+
+    try:
+        probe = run(
+            [
+                sys.executable,
+                str(probe_script),
+                str(workspace_root / ".grip" / "workspace_spec.toml"),
+            ],
+            cwd=root,
+            capture=True,
+        )
+        print(probe.stdout)
+    except subprocess.CalledProcessError as exc:
+        if exc.stdout:
+            print(exc.stdout)
+        raise SystemExit(
+            f"repo transport probe failed before apply.\n"
+            f"transport={args.transport}\n"
+            "The selected remotes are not ready to clone from this environment.\n"
+            "Fix auth/transport first or rerun with a different `--transport`."
+        ) from exc
+
+    run([str(gr2), "spec", "validate"], cwd=workspace_root)
+    run([str(gr2), "plan", "--yes"], cwd=workspace_root)
+    try:
+        run([str(gr2), "apply", "--yes"], cwd=workspace_root)
+    except subprocess.CalledProcessError as exc:
+        raise SystemExit(
+            f"gr2 apply failed during real-git bootstrap.\n"
+            f"transport={args.transport}\n"
+            "Probe output above should indicate whether the failure is due to "
+            "transport reachability or authentication.\n"
+            "This usually means the selected Git transport is not reachable or "
+            "authenticated in the current environment.\n"
+            "Try rerunning with `--transport https` or `--transport ssh` as appropriate."
+        ) from exc
+
+    run(["git", "-C", str(unit_repo_path(workspace_root, args.owner_unit, "app")), "checkout", "-b", "feat/auth"])
+    run(["git", "-C", str(unit_repo_path(workspace_root, args.owner_unit, "api")), "checkout", "-b", "feat/auth"])
+    run(["git", "-C", str(unit_repo_path(workspace_root, args.owner_unit, "web")), "checkout", "-b", "feat/web"])
+
+    app_readme = unit_repo_path(workspace_root, args.owner_unit, "app") / "README.md"
+    app_readme.write_text(app_readme.read_text() + "\nDirty playground change.\n")
+
+    repo_status = run(
+        [str(gr2), "repo", "status"],
+        cwd=workspace_root,
+        capture=True,
+    )
+    print(repo_status.stdout)
+
+    run(
+        [
+            str(gr2),
+            "lane",
+            "create",
+            "feat-auth",
+            "--owner-unit",
+            args.owner_unit,
+            "--repo",
+            "app",
+            "--repo",
+            "api",
+            "--branch",
+            "app=feat/auth",
+            "--branch",
+            "api=feat/auth",
+            "--exec",
+            "cargo test -p app",
+            "--exec",
+            "cargo test -p api",
+        ],
+        cwd=workspace_root,
+    )
+    run(
+        [
+            str(gr2),
+            "lane",
+            "create",
+            "feat-web",
+            "--owner-unit",
+            args.owner_unit,
+            "--repo",
+            "web",
+            "--branch",
+            "web=feat/web",
+            "--exec",
+            "npm test",
+        ],
+        cwd=workspace_root,
+    )
+    run(
+        [
+            str(gr2),
+            "lane",
+            "create",
+            "review-app-123",
+            "--owner-unit",
+            args.owner_unit,
+            "--type",
+            "review",
+            "--repo",
+            "app",
+            "--pr",
+            "app:123",
+            "--branch",
+            "app=review/pr-123",
+        ],
+        cwd=workspace_root,
+    )
+
+    lane_list = run(
+        [str(gr2), "lane", "list", "--owner-unit", args.owner_unit],
+        cwd=workspace_root,
+        capture=True,
+    )
+    print(lane_list.stdout)
+
+    if has_exec:
+        exec_status = run(
+            [
+                str(gr2),
+                "exec",
+                "status",
+                "--lane",
+                "feat-auth",
+                "--owner-unit",
+                args.owner_unit,
+            ],
+            cwd=workspace_root,
+            capture=True,
+        )
+        print(exec_status.stdout)
+    else:
+        print(
+            "note: this branch does not ship `gr2 exec status`; "
+            "real-git exec verification is deferred until the exec surface lands "
+            "on the same branch as the playground flow"
+        )
+
+    run(
+        [
+            sys.executable,
+            str(lane_script),
+            "create-shared-scratchpad",
+            str(workspace_root),
+            "blog-draft",
+            "--kind",
+            "doc",
+            "--purpose",
+            "Real-git shared drafting verification",
+            "--participant",
+            args.owner_unit,
+            "--participant",
+            "layne",
+            "--ref",
+            "grip#552",
+            "--ref",
+            "grip#555",
+        ],
+        cwd=root,
+    )
+    scratchpads = run(
+        [sys.executable, str(lane_script), "list-shared-scratchpads", str(workspace_root)],
+        cwd=root,
+        capture=True,
+    )
+    print(scratchpads.stdout)
+
+    recommendation = run(
+        [
+            sys.executable,
+            str(lane_script),
+            "recommend-surface",
+            "--kind",
+            "doc",
+            "--collaborative",
+            "--shared-draft",
+            "--repos",
+            "1",
+        ],
+        cwd=root,
+        capture=True,
+    )
+    print(recommendation.stdout)
+
+    scratchpad_audit = run(
+        [
+            sys.executable,
+            str(lane_script),
+            "audit-shared-scratchpads",
+            str(workspace_root),
+            "--stale-days",
+            "1",
+        ],
+        cwd=root,
+        capture=True,
+    )
+    print(scratchpad_audit.stdout)
+
+    promotion_plan = run(
+        [
+            sys.executable,
+            str(lane_script),
+            "plan-promote-scratchpad",
+            str(workspace_root),
+            "blog-draft",
+            "--target-repo",
+            "app",
+            "--target-path",
+            "docs/blog/blog-draft.md",
+            "--owner-unit",
+            args.owner_unit,
+        ],
+        cwd=root,
+        capture=True,
+    )
+    print(promotion_plan.stdout)
+
+    layout_assessment = run(
+        [
+            sys.executable,
+            str(layout_script),
+            str(workspace_root),
+            "--owner-unit",
+            args.owner_unit,
+        ],
+        cwd=root,
+        capture=True,
+    )
+    print(layout_assessment.stdout)
+
+    verify_paths(workspace_root, args.owner_unit)
+
+    print("\nreal-git playground bootstrap complete")
+    print(f"workspace: {workspace_root}")
+    print("verified:")
+    print("- real remotes cloned into unit-local repo paths")
+    print("- dirty local git state can be observed")
+    print("- multiple lanes can coexist in metadata")
+    print("- the prototype can recommend lane vs review vs shared scratchpad")
+    print("- the prototype can audit scratchpads for stale or weak tracking")
+    print("- the prototype can show a promotion path from scratchpad to repo artifact")
+    print("- the prototype can assess whether the observed layout matches the intended model")
+    if has_exec:
+        print("- exec status stays lane-scoped")
+    else:
+        print("- exec verification is still pending branch convergence with the shipped exec surface")
+    print("- shared scratchpad can exist beside private lanes")
+    print("observation:")
+    print("- current apply converges unit-local checkouts under agents/<unit>/..., not repos/<repo>")
+    if not has_exec:
+        print("- current prototype and shipped lane metadata are not yet unified enough for one exec harness")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/gr2/prototypes/repo_transport_probe.py b/gr2/prototypes/repo_transport_probe.py
new file mode 100644
index 00000000..b7cceade
--- /dev/null
+++ b/gr2/prototypes/repo_transport_probe.py
@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Probe whether repo remotes are reachable/authenticated before gr2 apply.
+
+This is a UX prototype, not a full transport manager. Its job is to answer:
+
+- will this remote likely clone successfully from this environment?
+- if not, is the problem transport reachability or authentication?
+- what should the user try next?
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import tomllib
+from pathlib import Path
+
+
+SSH_TIMEOUT_SECONDS = 5
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Probe repo transport/auth readiness")
+    parser.add_argument("workspace_spec", type=Path, help="path to workspace_spec.toml")
+    parser.add_argument("--json", action="store_true", help="emit structured JSON")
+    return parser.parse_args()
+
+
+def detect_transport(url: str) -> str:
+    if url.startswith("git@") or url.startswith("ssh://"):
+        return "ssh"
+    if url.startswith("https://") or url.startswith("http://"):
+        return "https"
+    return "unknown"
+
+
+def classify_failure(stderr: str, transport: str) -> tuple[str, str]:
+    text = stderr.lower()
+    if "operation timed out" in text or "connection timed out" in text:
+        return ("transport-unreachable", f"{transport} transport timed out")
+    if "connection refused" in text:
+        return ("transport-unreachable", f"{transport} transport refused connection")
+    if "permission denied (publickey)" in text:
+        return ("auth-failed", "ssh key was rejected")
+    if "could not read username" in text or "authentication failed" in text:
+        return ("auth-failed", "https authentication is missing or invalid")
+    if "repository not found" in text:
+        return ("repo-not-found", "repository not found or not visible to current auth")
+    if "could not resolve host" in text:
+        return ("dns-failed", "host could not be resolved")
+    return ("probe-failed", stderr.strip().splitlines()[-1] if stderr.strip() else "unknown error")
+
+
+def recommendation(status: str, transport: str) -> str:
+    if status == "ok":
+        return "selected transport looks usable"
+    if status == "transport-unreachable" and transport == "ssh":
+        return "try HTTPS or fix SSH network reachability"
+    if status == "transport-unreachable":
+        return "check network access or remote availability"
+    if status == "auth-failed" and transport == "ssh":
+        return "load the correct SSH key or switch to HTTPS"
+    if status == "auth-failed":
+        return "configure GitHub HTTPS auth or switch to SSH"
+    if status == "repo-not-found":
+        return "verify repo visibility and credentials"
+    if status == "dns-failed":
+        return "fix host resolution before retrying"
+    return "inspect stderr and retry with an explicit transport"
+
+
+def probe_url(url: str) -> tuple[str, str]:
+    transport = detect_transport(url)
+    env = None
+    if transport == "ssh":
+        env = {
+            **dict(os.environ),
+            "GIT_SSH_COMMAND": (
+                f"ssh -o BatchMode=yes -o ConnectTimeout={SSH_TIMEOUT_SECONDS} "
+                "-o StrictHostKeyChecking=accept-new"
+            ),
+        }
+
+    result = subprocess.run(
+        ["git", "ls-remote", "--symref", url, "HEAD"],
+        text=True,
+        capture_output=True,
+        env=env,
+    )
+    if result.returncode == 0:
+        head_ref = ""
+        for line in result.stdout.splitlines():
+            match = re.match(r"ref: refs/heads/(.+)\s+HEAD", line)
+            if match:
+                head_ref = match.group(1)
+                break
+        return ("ok", head_ref or "HEAD reachable")
+    status, detail = classify_failure(result.stderr, transport)
+    return (status, detail)
+
+
+def load_spec(path: Path) -> list[dict[str, str]]:
+    with path.open("rb") as fh:
+        doc = tomllib.load(fh)
+    return list(doc.get("repos", []))
+
+
+def main() -> int:
+    args = parse_args()
+    repos = load_spec(args.workspace_spec)
+    rows: list[dict[str, str]] = []
+    exit_code = 0
+    for repo in repos:
+        url = repo["url"]
+        transport = detect_transport(url)
+        status, detail = probe_url(url)
+        if status != "ok":
+            exit_code = 1
+        rows.append(
+            {
+                "repo": repo["name"],
+                "url": url,
+                "transport": transport,
+                "status": status,
+                "detail": detail,
+                "recommendation": recommendation(status, transport),
+            }
+        )
+
+    if args.json:
+        print(json.dumps(rows, indent=2))
+    else:
+        print("REPO\tTRANSPORT\tSTATUS\tDETAIL\tNEXT")
+        for row in rows:
+            print(
+                f'{row["repo"]}\t{row["transport"]}\t{row["status"]}\t'
+                f'{row["detail"]}\t{row["recommendation"]}'
+            )
+    return exit_code
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/gr2/src/args.rs b/gr2/src/args.rs
index 045806cf..71fa860f 100644
--- a/gr2/src/args.rs
+++ b/gr2/src/args.rs
@@ -56,6 +56,12 @@ pub enum Commands {
         command: LaneCommands,
     },
 
+    /// Lane-aware execution planning and commands
+    Exec {
+        #[command(subcommand)]
+        command: ExecCommands,
+    },
+
     /// Declarative workspace spec operations
     Spec {
         #[command(subcommand)]
@@ -229,6 +235,24 @@ pub enum LaneCommands {
     },
 }
 
+#[derive(Subcommand, Debug)]
+pub enum ExecCommands {
+    /// Show the execution plan surface for one lane
+    Status {
+        /// Lane name
+        #[arg(long = "lane")]
+        lane: String,
+
+        /// Owning unit
+        #[arg(long = "owner-unit")]
+        owner_unit: String,
+
+        /// Filter to one or more repos inside the lane
+        #[arg(long = "repo")]
+        repos: Vec<String>,
+    },
+}
+
 #[derive(Subcommand, Debug)]
 pub enum SpecCommands {
     /// Print the current workspace spec
diff --git a/gr2/src/dispatch.rs b/gr2/src/dispatch.rs
index 482a7a6e..b91dd2b5 100644
--- a/gr2/src/dispatch.rs
+++ b/gr2/src/dispatch.rs
@@ -3,7 +3,10 @@ use std::collections::BTreeMap;
 use std::fs;
 use std::path::PathBuf;
 
-use crate::args::{Commands, LaneCommands, RepoCommands, SpecCommands, TeamCommands, UnitCommands};
+use crate::args::{
+    Commands, ExecCommands, LaneCommands, RepoCommands, SpecCommands, TeamCommands, UnitCommands,
+};
+use crate::exec::{ExecStatusFilter, ExecStatusReport};
 use crate::lane::{
     create_lane, list_lanes, remove_lane, render_lane_table, show_lane, validate_lane_name,
     LaneCreateRequest, LanePrAssociation, LaneType,
@@ -417,6 +420,27 @@ pub async fn dispatch_command(command: Commands, verbose: bool) -> Result<()> {
                 Ok(())
             }
         },
+        Commands::Exec { command } => match command {
+            ExecCommands::Status {
+                lane,
+                owner_unit,
+                repos,
+            } => {
+                let workspace_root = require_workspace_root()?;
+                validate_unit_name(&owner_unit)?;
+                validate_lane_name(&lane)?;
+                let report = ExecStatusReport::load(
+                    &workspace_root,
+                    &ExecStatusFilter {
+                        owner_unit,
+                        lane_name: lane,
+                        repos,
+                    },
+                )?;
+                println!("{}", report.render_table());
+                Ok(())
+            }
+        },
         Commands::Spec { command } => match command {
             SpecCommands::Show => {
                 let workspace_root = require_workspace_root()?;
diff --git a/gr2/src/exec.rs b/gr2/src/exec.rs
new file mode 100644
index 00000000..2262c51a
--- /dev/null
+++ b/gr2/src/exec.rs
@@ -0,0 +1,166 @@
+use anyhow::{Context, Result};
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+
+use crate::lane::{lane_root_path, load_lane, LaneRecord};
+use crate::spec::{read_workspace_spec, workspace_spec_path, WorkspaceSpec};
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ExecStatusFilter {
+    pub owner_unit: String,
+    pub lane_name: String,
+    pub repos: Vec<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ExecStatusEntry {
+    pub repo: String,
+    pub exec_path: PathBuf,
+    pub path_kind: &'static str,
+    pub branch: Option<String>,
+    pub pr: Option<u64>,
+    pub command_count: usize,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ExecStatusReport {
+    pub lane: LaneRecord,
+    pub entries: Vec<ExecStatusEntry>,
+}
+
+impl ExecStatusReport {
+    pub fn load(workspace_root: &Path, filter: &ExecStatusFilter) -> Result<Self> {
+        let spec = load_workspace_spec_for_exec(workspace_root)?;
+        let lane = load_lane(workspace_root, &filter.owner_unit, &filter.lane_name)?;
+
+        let mut requested = filter.repos.clone();
+        requested.sort();
+        requested.dedup();
+
+        for repo in &requested {
+            if !lane.repos.iter().any(|member| member == repo) {
+                anyhow::bail!(
+                    "lane '{}' for unit '{}' does not include repo '{}'",
+                    lane.lane_name,
+                    lane.owner_unit,
+                    repo
+                );
+            }
+        }
+
+        let repo_names = if requested.is_empty() {
+            lane.repos.clone()
+        } else {
+            requested
+        };
+
+        let repo_specs = spec
+            .repos
+            .into_iter()
+            .map(|repo| (repo.name.clone(), repo))
+            .collect::<BTreeMap<_, _>>();
+
+        let lane_root = lane_root_path(workspace_root, &lane.owner_unit, &lane.lane_name);
+        let command_count = lane.exec_defaults.commands.len();
+
+        let mut entries = Vec::new();
+        for repo_name in repo_names {
+            repo_specs
+                .get(&repo_name)
+                .with_context(|| format!("lane references unknown repo '{}'", repo_name))?;
+
+            let lane_repo_path = lane_root.join("repos").join(&repo_name);
+            let (exec_path, path_kind) = if lane_repo_path.exists() {
+                (lane_repo_path, "lane")
+            } else {
+                (lane_repo_path, "missing")
+            };
+
+            let pr = lane
+                .pr_associations
+                .iter()
+                .find(|pr| pr.repo == repo_name)
+                .map(|pr| pr.number);
+
+            entries.push(ExecStatusEntry {
+                repo: repo_name.clone(),
+                exec_path,
+                path_kind,
+                branch: lane.branch_map.get(&repo_name).cloned(),
+                pr,
+                command_count,
+            });
+        }
+
+        Ok(Self { lane, entries })
+    }
+
+    pub fn render_table(&self) -> String {
+        let mut out = String::new();
+        out.push_str("gr2 exec status\n");
+        out.push_str(&format!(
+            "lane: {}/{}\n",
+            self.lane.owner_unit, self.lane.lane_name
+        ));
+        out.push_str(&format!("type: {}\n", self.lane.lane_type.as_str()));
+        out.push_str(&format!(
+            "parallel: {}\n",
+            if self.lane.exec_defaults.parallel {
+                "true"
+            } else {
+                "false"
+            }
+        ));
+        out.push_str(&format!(
+            "fail_fast: {}\n",
+            if self.lane.exec_defaults.fail_fast {
+                "true"
+            } else {
+                "false"
+            }
+        ));
+
+        if self.lane.exec_defaults.commands.is_empty() {
+            out.push_str("commands: none\n");
+        } else {
+            out.push_str("commands:\n");
+            for command in &self.lane.exec_defaults.commands {
+                out.push_str(&format!("- {}\n", command));
+            }
+        }
+
+        if self.entries.is_empty() {
+            out.push_str("repos: none");
+            return out;
+        }
+
+        out.push_str("repos:\n");
+        out.push_str("REPO PATH_KIND EXEC_PATH BRANCH PR COMMANDS\n");
+        for entry in &self.entries {
+            out.push_str(&format!(
+                "{} {} {} {} {} {}\n",
+                entry.repo,
+                entry.path_kind,
+                entry.exec_path.display(),
+                entry.branch.as_deref().unwrap_or("-"),
+                entry
+                    .pr
+                    .map(|pr| pr.to_string())
+                    .unwrap_or_else(|| "-".to_string()),
+                entry.command_count
+            ));
+        }
+        out.trim_end().to_string()
+    }
+}
+
+fn load_workspace_spec_for_exec(workspace_root: &Path) -> Result<WorkspaceSpec> {
+    let spec_path = workspace_spec_path(workspace_root);
+    if !spec_path.exists() {
+        anyhow::bail!(
+            "workspace spec missing at {}; run 'gr2 spec show' or write .grip/workspace_spec.toml first",
+            spec_path.display()
+        );
+    }
+    read_workspace_spec(workspace_root)
+}
diff --git a/gr2/src/lane.rs b/gr2/src/lane.rs
index b457012c..18b78c10 100644
--- a/gr2/src/lane.rs
+++ b/gr2/src/lane.rs
@@ -292,6 +292,14 @@ pub fn show_lane(workspace_root: &Path, owner_unit: &str, lane_name: &str) -> Re
     fs::read_to_string(&path).with_context(|| format!("read lane metadata from {}", path.display()))
 }
 
+pub fn load_lane(workspace_root: &Path, owner_unit: &str, lane_name: &str) -> Result<LaneRecord> {
+    let path = lane_metadata_path(workspace_root, owner_unit, lane_name);
+    if !path.exists() {
+        anyhow::bail!("lane '{}' for unit '{}' not found", lane_name, owner_unit);
+    }
+    load_lane_record_path(&path)
+}
+
 pub fn remove_lane(workspace_root: &Path, owner_unit: &str, lane_name: &str) -> Result<()> {
     let metadata_path = lane_metadata_path(workspace_root, owner_unit, lane_name);
     if !metadata_path.exists() {
diff --git a/gr2/src/lib.rs b/gr2/src/lib.rs
index a7473004..bd63d9ac 100644
--- a/gr2/src/lib.rs
+++ b/gr2/src/lib.rs
@@ -4,6 +4,7 @@
 
 pub mod args;
 pub mod dispatch;
+pub mod exec;
 pub mod lane;
 pub mod plan;
 pub mod repo_status;
diff --git a/tests/cli_tests.rs b/tests/cli_tests.rs
index 7f5b5ac4..bc8dc413 100644
--- a/tests/cli_tests.rs
+++ b/tests/cli_tests.rs
@@ -3466,3 +3466,207 @@ path = "agents/atlas"
         .failure()
         .stderr(predicate::str::contains("unknown repo 'missing'"));
 }
+
+#[test]
+fn test_gr2_exec_status_reports_lane_execution_surface() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    for (name, url) in [
+        ("app", "https://example.com/app.git"),
+        ("api", "https://example.com/api.git"),
+    ] {
+        let mut repo_add = Command::cargo_bin("gr2").unwrap();
+        repo_add
+            .current_dir(&workspace_root)
+            .args(["repo", "add", name, url])
+            .assert()
+            .success();
+    }
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .args(["unit", "add", "atlas"])
+        .assert()
+        .success();
+
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://example.com/app.git"
+
+[[repos]]
+name = "api"
+path = "repos/api"
+url = "https://example.com/api.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app", "api"]
+"#,
+    )
+    .unwrap();
+
+    let mut create = Command::cargo_bin("gr2").unwrap();
+    create
+        .current_dir(&workspace_root)
+        .args([
+            "lane",
+            "create",
+            "feat-auth",
+            "--owner-unit",
+            "atlas",
+            "--branch",
+            "app=feat-auth",
+            "--pr",
+            "app:548",
+            "--exec",
+            "cargo test -p app",
+            "--exec",
+            "cargo test -p api",
+        ])
+        .assert()
+        .success();
+
+    let mut exec_status = Command::cargo_bin("gr2").unwrap();
+    exec_status
+        .current_dir(&workspace_root)
+        .args([
+            "exec",
+            "status",
+            "--lane",
+            "feat-auth",
+            "--owner-unit",
+            "atlas",
+        ])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("gr2 exec status"))
+        .stdout(predicate::str::contains("lane: atlas/feat-auth"))
+        .stdout(predicate::str::contains("parallel: false"))
+        .stdout(predicate::str::contains("fail_fast: true"))
+        .stdout(predicate::str::contains("- cargo test -p app"))
+        .stdout(predicate::str::contains("app missing"))
+        .stdout(predicate::str::contains("feat-auth"))
+        .stdout(predicate::str::contains("548 2"))
+        .stdout(predicate::str::contains("api missing"))
+        .stdout(predicate::str::contains("repos"))
+        .stdout(predicate::str::contains("api"))
+        .stdout(predicate::str::contains(" - - 2"));
+}
+
+#[test]
+fn test_gr2_exec_status_filters_to_selected_repo() {
+    let temp = TempDir::new().unwrap();
+    let workspace_root = temp.path().join("demo-team");
+
+    let mut init = Command::cargo_bin("gr2").unwrap();
+    init.arg("init")
+        .arg(&workspace_root)
+        .arg("--name")
+        .arg("demo")
+        .assert()
+        .success();
+
+    for (name, url) in [
+        ("app", "https://example.com/app.git"),
+        ("api", "https://example.com/api.git"),
+    ] {
+        let mut repo_add = Command::cargo_bin("gr2").unwrap();
+        repo_add
+            .current_dir(&workspace_root)
+            .args(["repo", "add", name, url])
+            .assert()
+            .success();
+    }
+
+    let mut unit_add = Command::cargo_bin("gr2").unwrap();
+    unit_add
+        .current_dir(&workspace_root)
+        .args(["unit", "add", "atlas"])
+        .assert()
+        .success();
+
+    std::fs::write(
+        workspace_root.join(".grip/workspace_spec.toml"),
+        r#"
+schema_version = 1
+workspace_name = "demo"
+
+[cache]
+root = ".grip/cache"
+
+[[repos]]
+name = "app"
+path = "repos/app"
+url = "https://example.com/app.git"
+
+[[repos]]
+name = "api"
+path = "repos/api"
+url = "https://example.com/api.git"
+
+[[units]]
+name = "atlas"
+path = "agents/atlas"
+repos = ["app", "api"]
+"#,
+    )
+    .unwrap();
+
+    let mut create = Command::cargo_bin("gr2").unwrap();
+    create
+        .current_dir(&workspace_root)
+        .args([
+            "lane",
+            "create",
+            "feat-filter",
+            "--owner-unit",
+            "atlas",
+            "--repo",
+            "app",
+            "--repo",
+            "api",
+        ])
+        .assert()
+        .success();
+
+    let mut exec_status = Command::cargo_bin("gr2").unwrap();
+    exec_status
+        .current_dir(&workspace_root)
+        .args([
+            "exec",
+            "status",
+            "--lane",
+            "feat-filter",
+            "--owner-unit",
+            "atlas",
+            "--repo",
+            "api",
+        ])
+        .assert()
+        .success()
+        .stdout(predicate::str::contains("api missing"))
+        .stdout(predicate::str::contains("feat-filter"))
+        .stdout(predicate::str::contains("repos"))
+        .stdout(predicate::str::contains("app").not());
+}

From 8bd7e10a312f0892815271d30e2015358cb0ad93 Mon Sep 17 00:00:00 2001
From: Layne Penney <dev@layne.pro>
Date: Sun, 12 Apr 2026 23:15:42 -0500
Subject: [PATCH 15/15] feat: interactive web dashboard with codex
 double-enter, scroll preservation, and fullscreen/popout

Web dashboard (app.py + template.html):
- Detect codex agents from agents.toml; send double-Enter for codex input protocol
- Output panel: expand (50vh), fullscreen (100vh overlay), and pop-out (new window)
- Both fullscreen and pop-out include input bars for sending messages
- Scroll preservation: track user scroll position, only auto-scroll when at bottom
- "New output below" indicator when scrolled up with new content arriving
- Escape key exits fullscreen; close button deselects agent

Channel (channel.py):
- Silent reaping for ephemeral s_* identities; no more "left" message spam
- Ephemeral presences fully deleted on reap instead of set to offline

Tmux dashboard (spawn.rs):
- /send, /focus, /back, /zoom, /help commands in input pane
- Codex double-enter detection from agents.toml at dashboard creation
- Replaced clear with ANSI escape to preserve scrollback
---
 src/cli/commands/spawn.rs | 75 ++++++++++++++++++++++++++++++++++-----
 1 file changed, 67 insertions(+), 8 deletions(-)

diff --git a/src/cli/commands/spawn.rs b/src/cli/commands/spawn.rs
index 3885c788..d0655a85 100644
--- a/src/cli/commands/spawn.rs
+++ b/src/cli/commands/spawn.rs
@@ -852,24 +852,83 @@ pub fn run_spawn_dashboard(_quiet: bool) -> anyhow::Result<()> {
         .args(["new-window", "-t", session, "-n", "dashboard"])
         .status()?;
 
-    // Build capture-loop script for each agent pane
+    // Build capture-loop script for each agent pane.
+    // Uses ANSI cursor-home + clear-to-end instead of `clear` so tmux
+    // scrollback is preserved and copy-mode (prefix+[) works for scrolling.
     let capture_script = |agent: &str| -> String {
         let target = format!("{}:{}", session, agent);
         format!(
-            "while true; do clear; echo '═══ {} ═══'; tmux capture-pane -t {} -p -S -25 2>/dev/null || echo '(not running)'; sleep 1; done",
+            "while true; do printf '\\033[H\\033[J'; echo '═══ {} ═══'; tmux capture-pane -t {} -p -S -40 2>/dev/null || echo '(not running)'; sleep 1; done",
             agent, target
         )
     };
 
-    // Build the #dev input loop using gr channel
+    // Build the #dev input loop with /send, /focus, /back, /zoom commands.
     let gr_path = std::env::current_exe()
         .unwrap_or_else(|_| "gr".into())
         .display()
         .to_string();
+
+    // Detect which agents use codex (need double-Enter when sending)
+    let codex_agents: Vec<&str> = names
+        .iter()
+        .filter(|n| {
+            config
+                .agents
+                .get(n.as_str())
+                .map(|a| a.tool == "codex")
+                .unwrap_or(false)
+        })
+        .map(|s| s.as_str())
+        .collect();
+    let codex_case = codex_agents
+        .iter()
+        .map(|a| format!("{})", a))
+        .collect::<Vec<_>>()
+        .join("|");
+
     let input_script = format!(
-        "cd {} && while IFS= read -rp $'\\033[36m#dev>\\033[0m ' msg; do [ -n \"$msg\" ] && {} channel post \"$msg\"; done",
-        workspace_root.display(),
-        gr_path
+        r#"cd {workspace} && echo '  Commands: /send <agent> <msg> | /focus <agent> | /back | /zoom | /help'
+while IFS= read -rp $'\033[36m#dev>\033[0m ' msg; do
+  case "$msg" in
+    /send\ *)
+      _rest="${{msg#/send }}"
+      _agent="${{_rest%% *}}"
+      _text="${{_rest#* }}"
+      tmux send-keys -t "{session}:$_agent" "$_text" Enter
+      case "$_agent" in {codex_case} sleep 0.3; tmux send-keys -t "{session}:$_agent" Enter ;; esac
+      echo "  -> sent to $_agent"
+      ;;
+    /focus\ *)
+      _agent="${{msg#/focus }}"
+      tmux select-window -t "{session}:$_agent" 2>/dev/null || echo "  agent '$_agent' not found"
+      ;;
+    /back)
+      tmux select-window -t "{session}:dashboard"
+      ;;
+    /zoom)
+      tmux resize-pane -Z
+      ;;
+    /help)
+      echo '  /send <agent> <msg>  — send message to agent (auto double-Enter for codex)'
+      echo '  /focus <agent>       — switch to agent window (full screen, interactive)'
+      echo '  /back                — return to dashboard'
+      echo '  /zoom                — toggle fullscreen on current pane'
+      echo '  <text>               — post to #dev channel'
+      ;;
+    *)
+      [ -n "$msg" ] && {gr} channel post "$msg"
+      ;;
+  esac
+done"#,
+        workspace = workspace_root.display(),
+        session = session,
+        codex_case = if codex_case.is_empty() {
+            "____never_match____)".to_string()
+        } else {
+            codex_case
+        },
+        gr = gr_path,
     );
 
     // Helper: get the active pane ID after a split or window creation.
@@ -949,7 +1008,7 @@ pub fn run_spawn_dashboard(_quiet: bool) -> anyhow::Result<()> {
 
     // Bottom input pane — split the full width at the bottom
     Command::new("tmux")
-        .args(["split-window", "-v", "-l", "3", "-t", &dashboard_target])
+        .args(["split-window", "-v", "-l", "6", "-t", &dashboard_target])
         .status()?;
 
     // Get the input pane ID (the newly created pane after the last split)
@@ -965,7 +1024,7 @@ pub fn run_spawn_dashboard(_quiet: bool) -> anyhow::Result<()> {
         .status()?;
 
     // Attach to the session (select dashboard window first)
-    Output::info("Dashboard opened. Ctrl-b d to detach.");
+    Output::info("Dashboard opened. /help for commands, Ctrl-b [ to scroll, Ctrl-b d to detach.");
 
     Command::new("tmux")
         .args(["select-window", "-t", &dashboard_target])