@ktpartners/dgs-platform 2.8.0 → 3.0.4

package/deliver-great-systems/bin/lib/worktrees.test.cjs

@@ -0,0 +1,887 @@
+/**
+ * Tests for worktrees.cjs and resolveCodeContext() — git worktree lifecycle
+ *
+ * Uses real git repos in temp directories. All worktree commands call output()
+ * which exits the process, so tests invoke via subprocess (dgs-tools.cjs CLI).
+ */
+
+'use strict';
+
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { resetPaths, initPaths } = require('./paths.cjs');
+
+const DGS_TOOLS = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+
+// ─── Test Helpers ────────────────────────────────────────────────────────────
+
+const GIT_ENV = {
+  GIT_AUTHOR_NAME: 'Test',
+  GIT_AUTHOR_EMAIL: 'test@test.com',
+  GIT_COMMITTER_NAME: 'Test',
+  GIT_COMMITTER_EMAIL: 'test@test.com',
+};
+
+/**
+ * Create a minimal DGS environment with a real code repo for worktree tests.
+ *
+ * Layout:
+ *   {tmpDir}/
+ *     planning/              <- DGS planning root (git repo)
+ *       config.json
+ *       config.local.json
+ *       REPOS.md
+ *       PROJECTS.md
+ *       projects/tp/STATE.md
+ *     code-repo/             <- simulated code repo (git repo on main branch)
+ */
+function createTestEnv(opts) {
+  opts = opts || {};
+  const tmpDir = fs.realpathSync(fs.mkdtempSync(path.join(require('os').tmpdir(), 'dgs-wt-')));
+  const planDir = path.join(tmpDir, 'planning');
+  const codeDir = path.join(tmpDir, 'code-repo');
+
+  // Create planning root (git repo)
+  fs.mkdirSync(planDir, { recursive: true });
+  execSync('git init -b main', { cwd: planDir, stdio: 'pipe', env: { ...process.env, ...GIT_ENV } });
+  execSync('git config user.email "test@test.com"', { cwd: planDir, stdio: 'pipe' });
+  execSync('git config user.name "Test"', { cwd: planDir, stdio: 'pipe' });
+
+  // Create code repo (git repo on main branch)
+  fs.mkdirSync(codeDir, { recursive: true });
+  execSync('git init -b main', { cwd: codeDir, stdio: 'pipe', env: { ...process.env, ...GIT_ENV } });
+  execSync('git config user.email "test@test.com"', { cwd: codeDir, stdio: 'pipe' });
+  execSync('git config user.name "Test"', { cwd: codeDir, stdio: 'pipe' });
+  fs.writeFileSync(path.join(codeDir, '.gitkeep'), '');
+  execSync('git add .', { cwd: codeDir, stdio: 'pipe' });
+  execSync('git commit -m "initial"', { cwd: codeDir, stdio: 'pipe', env: { ...process.env, ...GIT_ENV } });
+
+  // Setup field for REPOS.md
+  const setupCmd = opts.setup || '';
+  const setupCol = setupCmd ? ' | ' + setupCmd : '';
+  const setupHeader = setupCmd ? ' | Setup' : '';
+  const setupSep = setupCmd ? ' |-------' : '';
+
+  // DGS config files
+  fs.writeFileSync(path.join(planDir, 'config.json'), JSON.stringify({
+    git: { base_branch: 'main' },
+  }, null, 2));
+
+  fs.writeFileSync(path.join(planDir, 'config.local.json'), JSON.stringify({
+    current_project: 'tp',
+  }, null, 2));
+
+  // v2 markers
+  fs.writeFileSync(path.join(planDir, 'PROJECTS.md'), '# Projects\n');
+  fs.writeFileSync(path.join(planDir, 'REPOS.md'),
+    '# Repos\n\n' +
+    '| Name | Path | GitHub URL | Description' + setupHeader + ' |\n' +
+    '|------|------|------------|------------' + setupSep + ' |\n' +
+    '| code-repo | ' + path.relative(planDir, codeDir) + ' |  | Test repo' + setupCol + ' |\n'
+  );
+
+  // Project structure
+  fs.mkdirSync(path.join(planDir, 'projects', 'tp'), { recursive: true });
+  fs.writeFileSync(path.join(planDir, 'projects', 'tp', 'STATE.md'), '# State\nStatus: planning\n');
+
+  // Commit planning files
+  execSync('git add .', { cwd: planDir, stdio: 'pipe' });
+  execSync('git commit -m "setup"', { cwd: planDir, stdio: 'pipe', env: { ...process.env, ...GIT_ENV } });
+
+  initPaths(planDir);
+
+  return {
+    tmpDir,
+    planDir,
+    codeDir,
+    cleanup: function() {
+      resetPaths();
+      // Also clean up any sibling worktree directories
+      try {
+        const parent = path.dirname(codeDir);
+        const entries = fs.readdirSync(parent);
+        for (const e of entries) {
+          if (e.startsWith('code-repo--')) {
+            fs.rmSync(path.join(parent, e), { recursive: true, force: true });
+          }
+        }
+      } catch { /* ignore */ }
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    },
+  };
+}
+
+/**
+ * Run dgs-tools command and return parsed JSON output.
+ */
+function runCmd(cwd, args) {
+  const result = execSync(
+    'node ' + JSON.stringify(DGS_TOOLS) + ' ' + args,
+    { cwd, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8', env: { ...process.env, ...GIT_ENV } }
+  );
+  return JSON.parse(result.trim());
+}
+
+/**
+ * Run dgs-tools command expecting an error.
+ */
+function runCmdError(cwd, args) {
+  try {
+    execSync(
+      'node ' + JSON.stringify(DGS_TOOLS) + ' ' + args,
+      { cwd, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8', env: { ...process.env, ...GIT_ENV } }
+    );
+    return null; // No error
+  } catch (err) {
+    return err.stderr || err.message;
+  }
+}
+
+/**
+ * Read config.local.json from planning dir.
+ */
+function readLocalConfig(planDir) {
+  return JSON.parse(fs.readFileSync(path.join(planDir, 'config.local.json'), 'utf-8'));
+}
+
+/**
+ * Write config.local.json to planning dir.
+ */
+function writeLocalConfig(planDir, data) {
+  fs.writeFileSync(path.join(planDir, 'config.local.json'), JSON.stringify(data, null, 2) + '\n');
+}
+
+// ─── REPOS.md setup field parsing ─────────────────────────────────────────────
+
+describe('REPOS.md setup field parsing', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv({ setup: 'echo hello' }); });
+  afterEach(() => { env.cleanup(); });
+
+  it('parseReposMd returns setup field from 5th column', () => {
+    const { parseReposMd } = require('./repos.cjs');
+    const result = parseReposMd(env.planDir);
+    assert.ok(result);
+    assert.ok(result.repos.length > 0);
+    assert.equal(result.repos[0].setup, 'echo hello');
+  });
+});
+
+describe('REPOS.md without setup column', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('parseReposMd returns empty string when Setup column missing', () => {
+    const { parseReposMd } = require('./repos.cjs');
+    const result = parseReposMd(env.planDir);
+    assert.ok(result);
+    assert.equal(result.repos[0].setup, '');
+  });
+});
+
+// ─── worktree creation ───────────────────────────────────────────────────────
+
+describe('worktree creation', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('creates milestone worktree at sibling path with correct branch', () => {
+    const result = runCmd(env.planDir, 'worktrees create test-ms --type milestone');
+    assert.ok(result.created);
+    assert.equal(result.slug, 'test-ms');
+    assert.equal(result.type, 'milestone');
+
+    // Verify directory exists
+    const wtPath = result.repos['code-repo'];
+    assert.ok(fs.existsSync(wtPath), 'Worktree directory should exist');
+    assert.ok(wtPath.includes('code-repo--tp-test-ms'), 'Path should use sibling naming');
+
+    // Verify branch
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd: wtPath, encoding: 'utf-8', stdio: 'pipe',
+    }).trim();
+    assert.equal(branch, 'milestone/test-ms');
+
+    // Verify config state
+    const config = readLocalConfig(env.planDir);
+    assert.ok(config.projects.tp.worktrees['test-ms']);
+    assert.equal(config.projects.tp.worktrees['test-ms'].type, 'milestone');
+  });
+
+  it('creates quick worktree with quick branch prefix', () => {
+    const result = runCmd(env.planDir, 'worktrees create fix-bug --type quick');
+    assert.ok(result.created);
+    assert.equal(result.type, 'quick');
+
+    const wtPath = result.repos['code-repo'];
+    const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd: wtPath, encoding: 'utf-8', stdio: 'pipe',
+    }).trim();
+    assert.equal(branch, 'quick/fix-bug');
+  });
+
+  it('skips creation if worktree already exists', () => {
+    runCmd(env.planDir, 'worktrees create dup --type milestone');
+    // Second call should not error
+    const result = runCmd(env.planDir, 'worktrees create dup --type milestone');
+    assert.ok(result.created);
+  });
+
+  it('errors when main checkout is not on base_branch', () => {
+    // Switch code repo to a different branch
+    execSync('git checkout -b feature', { cwd: env.codeDir, stdio: 'pipe', env: { ...process.env, ...GIT_ENV } });
+    const err = runCmdError(env.planDir, 'worktrees create off-branch --type milestone');
+    assert.ok(err, 'Should error');
+    assert.ok(err.includes('not on main'), 'Error should mention base branch: ' + err);
+  });
+});
+
+describe('worktree creation with setup command', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv({ setup: 'echo setup-ran > setup-marker.txt' }); });
+  afterEach(() => { env.cleanup(); });
+
+  it('runs setup command when REPOS.md has setup field', () => {
+    const result = runCmd(env.planDir, 'worktrees create with-setup --type milestone');
+    const wtPath = result.repos['code-repo'];
+    // The setup command creates a marker file -- check slug is appended
+    const markerPath = path.join(wtPath, 'setup-marker.txt');
+    assert.ok(fs.existsSync(markerPath), 'Setup marker should exist at ' + markerPath);
+  });
+});
+
+describe('worktree creation with failing setup', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv({ setup: 'exit 1' }); });
+  afterEach(() => { env.cleanup(); });
+
+  it('keeps worktree on setup failure and sets setup_complete false', () => {
+    const result = runCmd(env.planDir, 'worktrees create fail-setup --type milestone');
+    const wtPath = result.repos['code-repo'];
+    assert.ok(fs.existsSync(wtPath), 'Worktree should still exist after setup failure');
+
+    const config = readLocalConfig(env.planDir);
+    assert.equal(config.projects.tp.worktrees['fail-setup'].setup_complete, false);
+  });
+});
+
+// ─── worktree removal ────────────────────────────────────────────────────────
+
+describe('worktree removal', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('removes worktree directory, git registration, and branch', () => {
+    const created = runCmd(env.planDir, 'worktrees create to-remove --type milestone');
+    const wtPath = created.repos['code-repo'];
+    assert.ok(fs.existsSync(wtPath));
+
+    const removed = runCmd(env.planDir, 'worktrees remove to-remove');
+    assert.ok(removed.removed);
+
+    // Directory gone
+    assert.ok(!fs.existsSync(wtPath), 'Worktree dir should be gone');
+
+    // Branch gone
+    const branches = execSync('git branch', { cwd: env.codeDir, encoding: 'utf-8', stdio: 'pipe' });
+    assert.ok(!branches.includes('milestone/to-remove'), 'Branch should be deleted');
+
+    // Config entry gone
+    const config = readLocalConfig(env.planDir);
+    assert.ok(!config.projects.tp.worktrees || !config.projects.tp.worktrees['to-remove']);
+  });
+
+  it('clears active_context if removed worktree was active', () => {
+    runCmd(env.planDir, 'worktrees create active-wt --type milestone');
+
+    // Set active_context
+    const config = readLocalConfig(env.planDir);
+    if (!config.execution) config.execution = {};
+    config.execution.active_context = 'active-wt';
+    writeLocalConfig(env.planDir, config);
+
+    runCmd(env.planDir, 'worktrees remove active-wt');
+
+    const after = readLocalConfig(env.planDir);
+    assert.equal(after.execution.active_context, null);
+  });
+
+  it('handles already-deleted worktree directory gracefully', () => {
+    const created = runCmd(env.planDir, 'worktrees create del-first --type milestone');
+    const wtPath = created.repos['code-repo'];
+
+    // Manually delete the directory
+    fs.rmSync(wtPath, { recursive: true, force: true });
+
+    // Remove should not error
+    const removed = runCmd(env.planDir, 'worktrees remove del-first');
+    assert.ok(removed.removed);
+  });
+});
+
+// ─── worktree list ───────────────────────────────────────────────────────────
+
+describe('worktree list', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('lists tracked worktrees with type, path, and status', () => {
+    runCmd(env.planDir, 'worktrees create list-test --type milestone');
+
+    const list = runCmd(env.planDir, 'worktrees list');
+    assert.ok(Array.isArray(list));
+    assert.ok(list.length >= 1);
+
+    const entry = list.find(e => e.slug === 'list-test');
+    assert.ok(entry);
+    assert.equal(entry.type, 'milestone');
+    assert.equal(entry.stale, false);
+    assert.ok(entry.repos['code-repo'].exists);
+  });
+
+  it('marks worktrees with missing directories as stale', () => {
+    const created = runCmd(env.planDir, 'worktrees create stale-test --type milestone');
+    const wtPath = created.repos['code-repo'];
+
+    // Manually delete directory
+    fs.rmSync(wtPath, { recursive: true, force: true });
+    // Also prune git worktree registry
+    execSync('git worktree prune', { cwd: env.codeDir, stdio: 'pipe' });
+
+    const list = runCmd(env.planDir, 'worktrees list');
+    const entry = list.find(e => e.slug === 'stale-test');
+    assert.ok(entry);
+    assert.equal(entry.stale, true);
+    assert.equal(entry.repos['code-repo'].exists, false);
+  });
+});
+
+// ─── worktree setup re-run ───────────────────────────────────────────────────
+
+describe('worktree setup re-run', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv({ setup: 'echo re-ran > setup-rerun.txt' }); });
+  afterEach(() => { env.cleanup(); });
+
+  it('re-runs setup command and updates setup_complete flag', () => {
+    // First create with a working setup
+    runCmd(env.planDir, 'worktrees create setup-rerun --type milestone');
+
+    // Run setup again
+    const result = runCmd(env.planDir, 'worktrees setup setup-rerun');
+    assert.ok(result.setup_complete);
+    assert.equal(result.results['code-repo'], 'success');
+  });
+});
+
+// ─── setup command $2 worktree path argument ─────────────────────────────────
+
+describe('setup command receives worktree path as second argument', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv({ setup: 'echo "$1 $2" > setup-args.txt' }); });
+  afterEach(() => { env.cleanup(); });
+
+  it('setup command receives worktree path as second argument', () => {
+    const result = runCmd(env.planDir, 'worktrees create path-arg --type milestone');
+    const wtPath = result.repos['code-repo'];
+    const argsFile = path.join(wtPath, 'setup-args.txt');
+    assert.ok(fs.existsSync(argsFile), 'setup-args.txt should exist at ' + argsFile);
+
+    const content = fs.readFileSync(argsFile, 'utf-8').trim();
+    // Content should contain slug and worktree path separated by space
+    assert.ok(content.startsWith('path-arg '), 'Should start with slug: ' + content);
+    assert.ok(content.includes(wtPath), 'Should contain worktree path: ' + content);
+  });
+
+  it('setup re-run passes worktree path as second argument', () => {
+    // First create worktree
+    runCmd(env.planDir, 'worktrees create rerun-path --type milestone');
+
+    // Update REPOS.md to use a different marker file for re-run
+    const reposPath = path.join(env.planDir, 'REPOS.md');
+    let reposMd = fs.readFileSync(reposPath, 'utf-8');
+    reposMd = reposMd.replace('echo "$1 $2" > setup-args.txt', 'echo "$1 $2" > setup-rerun-args.txt');
+    fs.writeFileSync(reposPath, reposMd);
+
+    // Re-run setup
+    const result = runCmd(env.planDir, 'worktrees setup rerun-path');
+    assert.ok(result.setup_complete);
+
+    const config = readLocalConfig(env.planDir);
+    const wtPath = config.projects.tp.worktrees['rerun-path'].repos['code-repo'];
+    const argsFile = path.join(wtPath, 'setup-rerun-args.txt');
+    assert.ok(fs.existsSync(argsFile), 'setup-rerun-args.txt should exist at ' + argsFile);
+
+    const content = fs.readFileSync(argsFile, 'utf-8').trim();
+    assert.ok(content.startsWith('rerun-path '), 'Should start with slug: ' + content);
+    assert.ok(content.includes(wtPath), 'Should contain worktree path: ' + content);
+  });
+});
+
+// ─── worktree prune ──────────────────────────────────────────────────────────
+
+describe('worktree prune', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('removes orphaned entries from config when directory is missing', () => {
+    const created = runCmd(env.planDir, 'worktrees create prune-test --type milestone');
+    const wtPath = created.repos['code-repo'];
+
+    // Manually delete
+    fs.rmSync(wtPath, { recursive: true, force: true });
+    execSync('git worktree prune', { cwd: env.codeDir, stdio: 'pipe' });
+
+    const result = runCmd(env.planDir, 'worktrees prune');
+    assert.ok(result.pruned.includes('prune-test'));
+    assert.ok(result.count >= 1);
+
+    // Config entry should be gone
+    const config = readLocalConfig(env.planDir);
+    assert.ok(!config.projects.tp.worktrees || !config.projects.tp.worktrees['prune-test']);
+  });
+
+  it('cleans up orphaned git branches', () => {
+    runCmd(env.planDir, 'worktrees create prune-branch --type milestone');
+    const created = readLocalConfig(env.planDir);
+    const wtPath = created.projects.tp.worktrees['prune-branch'].repos['code-repo'];
+
+    // Manually delete directory
+    fs.rmSync(wtPath, { recursive: true, force: true });
+    execSync('git worktree prune', { cwd: env.codeDir, stdio: 'pipe' });
+
+    runCmd(env.planDir, 'worktrees prune');
+
+    // Branch should be gone
+    const branches = execSync('git branch', { cwd: env.codeDir, encoding: 'utf-8', stdio: 'pipe' });
+    assert.ok(!branches.includes('milestone/prune-branch'), 'Branch should be deleted');
+  });
+
+  it('clears active_context if pruned worktree was active', () => {
+    runCmd(env.planDir, 'worktrees create prune-active --type milestone');
+
+    // Set active_context
+    const config = readLocalConfig(env.planDir);
+    if (!config.execution) config.execution = {};
+    config.execution.active_context = 'prune-active';
+    writeLocalConfig(env.planDir, config);
+
+    // Delete directory and prune
+    const wtPath = config.projects.tp.worktrees['prune-active'].repos['code-repo'];
+    fs.rmSync(wtPath, { recursive: true, force: true });
+    execSync('git worktree prune', { cwd: env.codeDir, stdio: 'pipe' });
+
+    runCmd(env.planDir, 'worktrees prune');
+
+    const after = readLocalConfig(env.planDir);
+    assert.equal(after.execution.active_context, null);
+  });
+});
+
+// ─── resolveCodeContext ──────────────────────────────────────────────────────
+
+describe('resolveCodeContext', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('returns main checkout when active_context is null', () => {
+    const config = readLocalConfig(env.planDir);
+    config.execution = { active_context: null };
+    writeLocalConfig(env.planDir, config);
+
+    resetPaths();
+    initPaths(env.planDir);
+    const { resolveCodeContext } = require('./context.cjs');
+    const result = resolveCodeContext(env.planDir, 'code-repo');
+    assert.equal(result.type, 'main');
+  });
+
+  it('returns main checkout when active_context is unset', () => {
+    // No execution key at all
+    const config = readLocalConfig(env.planDir);
+    delete config.execution;
+    writeLocalConfig(env.planDir, config);
+
+    resetPaths();
+    initPaths(env.planDir);
+    const { resolveCodeContext } = require('./context.cjs');
+    const result = resolveCodeContext(env.planDir, 'code-repo');
+    assert.equal(result.type, 'main');
+  });
+
+  it('returns milestone worktree directory when milestone context active', () => {
+    const created = runCmd(env.planDir, 'worktrees create ctx-ms --type milestone');
+    const wtPath = created.repos['code-repo'];
+
+    // Set active context
+    const config = readLocalConfig(env.planDir);
+    config.execution = { active_context: 'ctx-ms' };
+    writeLocalConfig(env.planDir, config);
+
+    resetPaths();
+    initPaths(env.planDir);
+    const { resolveCodeContext } = require('./context.cjs');
+    const result = resolveCodeContext(env.planDir, 'code-repo');
+    assert.equal(result.type, 'milestone');
+    assert.equal(result.directory, wtPath);
+    assert.equal(result.slug, 'ctx-ms');
+  });
+
+  it('returns quick worktree with mode when quick context active', () => {
+    const created = runCmd(env.planDir, 'worktrees create ctx-quick --type quick --mode debug');
+
+    // Set active context
+    const config = readLocalConfig(env.planDir);
+    config.execution = { active_context: 'ctx-quick' };
+    writeLocalConfig(env.planDir, config);
+
+    resetPaths();
+    initPaths(env.planDir);
+    const { resolveCodeContext } = require('./context.cjs');
+    const result = resolveCodeContext(env.planDir, 'code-repo');
+    assert.equal(result.type, 'quick');
+    assert.equal(result.mode, 'debug');
+  });
+
+  it('detects stale context and falls back to main when directory missing', () => {
+    const created = runCmd(env.planDir, 'worktrees create ctx-stale --type milestone');
+    const wtPath = created.repos['code-repo'];
+
+    // Set active context then delete directory
+    const config = readLocalConfig(env.planDir);
+    config.execution = { active_context: 'ctx-stale' };
+    writeLocalConfig(env.planDir, config);
+
+    fs.rmSync(wtPath, { recursive: true, force: true });
+    execSync('git worktree prune', { cwd: env.codeDir, stdio: 'pipe' });
+
+    resetPaths();
+    initPaths(env.planDir);
+    const { resolveCodeContext } = require('./context.cjs');
+    const result = resolveCodeContext(env.planDir, 'code-repo');
+    assert.equal(result.type, 'main');
+
+    // active_context should be cleared
+    const after = readLocalConfig(env.planDir);
+    assert.equal(after.execution.active_context, null);
+  });
+
+  it('detects stale context when config entry is missing', () => {
+    // Set active context to non-existent slug
+    const config = readLocalConfig(env.planDir);
+    config.execution = { active_context: 'nonexistent' };
+    writeLocalConfig(env.planDir, config);
+
+    resetPaths();
+    initPaths(env.planDir);
+    const { resolveCodeContext } = require('./context.cjs');
+    const result = resolveCodeContext(env.planDir, 'code-repo');
+    assert.equal(result.type, 'main');
+
+    // active_context should be cleared
+    const after = readLocalConfig(env.planDir);
+    assert.equal(after.execution.active_context, null);
+  });
+});
+
+// ─── rebaseAndMerge ──────────────────────────────────────────────────────────
+
+/**
+ * Create test env with a bare remote for rebase/merge/push testing.
+ * Layout:
+ *   {tmpDir}/
+ *     planning/       <- DGS planning root
+ *     remote.git/     <- bare remote
+ *     code-repo/      <- clone of remote (main checkout)
+ */
+function createRebaseTestEnv() {
+  const tmpDir = fs.realpathSync(fs.mkdtempSync(path.join(require('os').tmpdir(), 'dgs-rb-')));
+  const planDir = path.join(tmpDir, 'planning');
+  const remoteDir = path.join(tmpDir, 'remote.git');
+  const codeDir = path.join(tmpDir, 'code-repo');
+  const fullEnv = { ...process.env, ...GIT_ENV };
+
+  // Create a regular repo first, then clone it bare
+  const seedDir = path.join(tmpDir, '_seed');
+  fs.mkdirSync(seedDir, { recursive: true });
+  execSync('git init -b main', { cwd: seedDir, stdio: 'pipe', env: fullEnv });
+  execSync('git config user.email "test@test.com"', { cwd: seedDir, stdio: 'pipe' });
+  execSync('git config user.name "Test"', { cwd: seedDir, stdio: 'pipe' });
+  fs.writeFileSync(path.join(seedDir, 'file.txt'), 'initial');
+  execSync('git add . && git commit -m "initial"', { cwd: seedDir, stdio: 'pipe', env: fullEnv });
+
+  // Create bare remote from seed
+  execSync('git clone --bare "' + seedDir + '" remote.git', { cwd: tmpDir, stdio: 'pipe', env: fullEnv });
+  fs.rmSync(seedDir, { recursive: true, force: true });
+
+  // Clone to main checkout
+  execSync('git clone "' + remoteDir + '" code-repo', { cwd: tmpDir, stdio: 'pipe', env: fullEnv });
+  execSync('git config user.email "test@test.com"', { cwd: codeDir, stdio: 'pipe' });
+  execSync('git config user.name "Test"', { cwd: codeDir, stdio: 'pipe' });
+
+  // Create planning root
+  fs.mkdirSync(planDir, { recursive: true });
+  execSync('git init -b main', { cwd: planDir, stdio: 'pipe', env: fullEnv });
+  execSync('git config user.email "test@test.com"', { cwd: planDir, stdio: 'pipe' });
+  execSync('git config user.name "Test"', { cwd: planDir, stdio: 'pipe' });
+
+  fs.writeFileSync(path.join(planDir, 'config.json'), JSON.stringify({
+    git: { base_branch: 'main' },
+  }, null, 2));
+  fs.writeFileSync(path.join(planDir, 'config.local.json'), JSON.stringify({
+    current_project: 'tp',
+  }, null, 2));
+  fs.writeFileSync(path.join(planDir, 'PROJECTS.md'), '# Projects\n');
+  fs.writeFileSync(path.join(planDir, 'REPOS.md'),
+    '# Repos\n\n' +
+    '| Name | Path | GitHub URL | Description |\n' +
+    '|------|------|------------|-------------|\n' +
+    '| code-repo | ' + path.relative(planDir, codeDir) + ' |  | Test repo |\n'
+  );
+  fs.mkdirSync(path.join(planDir, 'projects', 'tp'), { recursive: true });
+  fs.writeFileSync(path.join(planDir, 'projects', 'tp', 'STATE.md'), '# State\n');
+  execSync('git add . && git commit -m "setup"', { cwd: planDir, stdio: 'pipe', env: fullEnv });
+
+  initPaths(planDir);
+
+  return {
+    tmpDir, planDir, codeDir, remoteDir, fullEnv,
+    cleanup: function() {
+      resetPaths();
+      try {
+        const parent = path.dirname(codeDir);
+        const entries = fs.readdirSync(parent);
+        for (const e of entries) {
+          if (e.startsWith('code-repo--')) {
+            fs.rmSync(path.join(parent, e), { recursive: true, force: true });
+          }
+        }
+      } catch { /* ignore */ }
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    },
+  };
+}
+
+/**
+ * Create a worktree in a rebase test env and return state.
+ */
+function createWorktreeForRebase(env, slug) {
+  slug = slug || 'test-ms';
+  const result = runCmd(env.planDir, 'worktrees create ' + slug + ' --type milestone');
+  const wtPath = result.repos['code-repo'];
+  return { slug, wtPath, branchName: 'milestone/' + slug };
+}
+
+describe('rebaseAndMerge', () => {
+  let env;
+  beforeEach(() => { env = createRebaseTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('rebases milestone branch onto base_branch and merges', () => {
+    const { slug, wtPath } = createWorktreeForRebase(env);
+
+    // Add a commit on milestone branch in worktree
+    fs.writeFileSync(path.join(wtPath, 'feature.txt'), 'milestone work');
+    execSync('git add . && git commit -m "milestone feature"', { cwd: wtPath, stdio: 'pipe', env: env.fullEnv });
+
+    const { rebaseAndMerge } = require('./worktrees.cjs');
+    const result = rebaseAndMerge(env.planDir, 'code-repo', slug, { push: false });
+
+    assert.ok(result.success, 'Should succeed: ' + (result.error || ''));
+    assert.ok(result.merged);
+    assert.ok(!result.conflicted);
+
+    // Verify milestone commit is on main
+    const log = execSync('git log --oneline', { cwd: env.codeDir, encoding: 'utf-8', stdio: 'pipe' });
+    assert.ok(log.includes('milestone feature'), 'Main should have milestone commit');
+  });
+
+  it('handles divergent branches (base has new commits)', () => {
+    const { slug, wtPath } = createWorktreeForRebase(env);
+
+    // Add commit on main (push to remote so pull works)
+    fs.writeFileSync(path.join(env.codeDir, 'main-change.txt'), 'main work');
+    execSync('git add . && git commit -m "main change"', { cwd: env.codeDir, stdio: 'pipe', env: env.fullEnv });
+    execSync('git push origin main', { cwd: env.codeDir, stdio: 'pipe', env: env.fullEnv });
+
+    // Add commit on milestone branch
+    fs.writeFileSync(path.join(wtPath, 'ms-change.txt'), 'milestone work');
+    execSync('git add . && git commit -m "milestone change"', { cwd: wtPath, stdio: 'pipe', env: env.fullEnv });
+
+    const { rebaseAndMerge } = require('./worktrees.cjs');
+    const result = rebaseAndMerge(env.planDir, 'code-repo', slug, { push: false });
+
+    assert.ok(result.success, 'Should succeed: ' + (result.error || ''));
+    assert.ok(result.merged);
+
+    // Both commits should be on main
+    const log = execSync('git log --oneline', { cwd: env.codeDir, encoding: 'utf-8', stdio: 'pipe' });
+    assert.ok(log.includes('main change'), 'Main should have main commit');
+    assert.ok(log.includes('milestone change'), 'Main should have milestone commit');
+  });
+
+  it('detects conflicts and aborts cleanly', () => {
+    const { slug, wtPath } = createWorktreeForRebase(env);
+
+    // Create conflict: same file different content on both branches
+    fs.writeFileSync(path.join(env.codeDir, 'shared.txt'), 'main version');
+    execSync('git add . && git commit -m "main shared"', { cwd: env.codeDir, stdio: 'pipe', env: env.fullEnv });
+    execSync('git push origin main', { cwd: env.codeDir, stdio: 'pipe', env: env.fullEnv });
+
+    fs.writeFileSync(path.join(wtPath, 'shared.txt'), 'milestone version');
+    execSync('git add . && git commit -m "milestone shared"', { cwd: wtPath, stdio: 'pipe', env: env.fullEnv });
+
+    const { rebaseAndMerge } = require('./worktrees.cjs');
+    const result = rebaseAndMerge(env.planDir, 'code-repo', slug, { push: false });
+
+    assert.ok(!result.success);
+    assert.ok(result.conflicted);
+    assert.ok(result.manualInstructions, 'Should have manual instructions');
+    assert.ok(result.manualInstructions.includes(wtPath), 'Instructions should include worktree path');
+
+    // Worktree should be in clean state (rebase aborted)
+    const status = execSync('git status --porcelain', { cwd: wtPath, encoding: 'utf-8', stdio: 'pipe' });
+    assert.equal(status.trim(), '', 'Worktree should be clean after abort');
+  });
+
+  it('skips rebase when already rebased (idempotent)', () => {
+    const { slug, wtPath, branchName } = createWorktreeForRebase(env);
+
+    // Add commit on milestone and manually rebase
+    fs.writeFileSync(path.join(wtPath, 'feature.txt'), 'work');
+    execSync('git add . && git commit -m "feature"', { cwd: wtPath, stdio: 'pipe', env: env.fullEnv });
+    execSync('git rebase main', { cwd: wtPath, stdio: 'pipe', env: env.fullEnv });
+
+    const { rebaseAndMerge } = require('./worktrees.cjs');
+    const result = rebaseAndMerge(env.planDir, 'code-repo', slug, { push: false });
+
+    assert.ok(result.success, 'Should succeed: ' + (result.error || ''));
+    assert.ok(result.merged);
+  });
+
+  it('pushes to remote after merge', () => {
+    const { slug, wtPath } = createWorktreeForRebase(env);
+
+    fs.writeFileSync(path.join(wtPath, 'pushed.txt'), 'push test');
+    execSync('git add . && git commit -m "to push"', { cwd: wtPath, stdio: 'pipe', env: env.fullEnv });
+
+    const { rebaseAndMerge } = require('./worktrees.cjs');
+    const result = rebaseAndMerge(env.planDir, 'code-repo', slug, { push: true });
+
+    assert.ok(result.success, 'Should succeed: ' + (result.error || ''));
+    assert.ok(result.pushed, 'Should have pushed');
+
+    // Verify remote has the commit
+    const remoteLog = execSync('git log --oneline', { cwd: env.remoteDir, encoding: 'utf-8', stdio: 'pipe' });
+    assert.ok(remoteLog.includes('to push'), 'Remote should have pushed commit');
+  });
+
+  it('returns error when worktree slug not found', () => {
+    const { rebaseAndMerge } = require('./worktrees.cjs');
+    const result = rebaseAndMerge(env.planDir, 'code-repo', 'nonexistent', { push: false });
+
+    assert.ok(!result.success);
+    assert.ok(result.error.includes('nonexistent'));
+  });
+});
+
+// ─── checkWorktreeHealth ─────────────────────────────────────────────────────
+
+describe('checkWorktreeHealth', () => {
+  let env;
+  beforeEach(() => { env = createRebaseTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('reports healthy when branch correct and no uncommitted changes', () => {
+    createWorktreeForRebase(env);
+
+    const { checkWorktreeHealth } = require('./worktrees.cjs');
+    const result = checkWorktreeHealth(env.planDir, 'test-ms');
+
+    assert.ok(result.healthy);
+    assert.equal(result.issues.length, 0);
+  });
+
+  it('detects wrong branch', () => {
+    const { wtPath } = createWorktreeForRebase(env);
+
+    // Switch worktree to a different branch
+    execSync('git checkout -b wrong-branch', { cwd: wtPath, stdio: 'pipe', env: env.fullEnv });
+
+    const { checkWorktreeHealth } = require('./worktrees.cjs');
+    const result = checkWorktreeHealth(env.planDir, 'test-ms');
+
+    assert.ok(!result.healthy);
+    assert.ok(result.issues.length > 0);
+    assert.ok(result.issues[0].includes('expected branch'));
+  });
+
+  it('detects uncommitted changes', () => {
+    const { wtPath } = createWorktreeForRebase(env);
+
+    // Create uncommitted change
+    fs.writeFileSync(path.join(wtPath, 'dirty.txt'), 'uncommitted');
+
+    const { checkWorktreeHealth } = require('./worktrees.cjs');
+    const result = checkWorktreeHealth(env.planDir, 'test-ms');
+
+    assert.ok(!result.healthy);
+    assert.ok(result.issues.some(i => i.includes('uncommitted')));
+  });
+
+  it('detects missing worktree directory', () => {
+    const { wtPath } = createWorktreeForRebase(env);
+
+    // Delete the worktree directory
+    fs.rmSync(wtPath, { recursive: true, force: true });
+
+    const { checkWorktreeHealth } = require('./worktrees.cjs');
+    const result = checkWorktreeHealth(env.planDir, 'test-ms');
+
+    assert.ok(!result.healthy);
+    assert.ok(result.issues.some(i => i.includes('missing')));
+  });
+});
+
+// ─── main checkout invariant ─────────────────────────────────────────────────
+
+describe('main checkout invariant', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('main checkout remains on base_branch after worktree create and remove', () => {
+    // Verify main is on main before
+    let branch = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd: env.codeDir, encoding: 'utf-8', stdio: 'pipe',
+    }).trim();
+    assert.equal(branch, 'main');
+
+    // Create worktree
+    runCmd(env.planDir, 'worktrees create inv-test --type milestone');
+
+    // Verify main still on main
+    branch = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd: env.codeDir, encoding: 'utf-8', stdio: 'pipe',
+    }).trim();
+    assert.equal(branch, 'main');
+
+    // Remove worktree
+    runCmd(env.planDir, 'worktrees remove inv-test');
+
+    // Verify main still on main
+    branch = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd: env.codeDir, encoding: 'utf-8', stdio: 'pipe',
+    }).trim();
+    assert.equal(branch, 'main');
+  });
+});