@ktpartners/dgs-platform 2.6.2

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

@@ -0,0 +1,1472 @@
+/**
+ * Tests for execution.cjs — Multi-repo execution engine:
+ * preflight checks, per-repo commits, planning commit body, change detection
+ */
+
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const { createTempDir, cleanupDir, initGitRepo } = require('./test-helpers.cjs');
+
+/**
+ * Helper: create a product root with .planning/REPOS.md and git repos.
+ */
+function setupProductRoot(tmpDir, repoNames) {
+  // Create .planning with REPOS.md
+  const planningDir = path.join(tmpDir, '.planning');
+  fs.mkdirSync(planningDir, { recursive: true });
+
+  let reposMd = '# Repos\n\n';
+  reposMd += '| Name | Path | GitHub URL | Description |\n';
+  reposMd += '|------|------|------------|-------------|\n';
+
+  for (const name of repoNames) {
+    reposMd += `| ${name} | ./${name} | | Test repo |\n`;
+    initGitRepo(path.join(tmpDir, name));
+    // Add README.md as a tracked file (tests depend on modifying it)
+    fs.writeFileSync(path.join(tmpDir, name, 'README.md'), '# Repo\n');
+    execSync('git add README.md', { cwd: path.join(tmpDir, name), stdio: 'pipe' });
+    execSync('git commit -m "add readme"', { cwd: path.join(tmpDir, name), stdio: 'pipe' });
+  }
+
+  fs.writeFileSync(path.join(planningDir, 'REPOS.md'), reposMd);
+  return tmpDir;
+}
+
+const {
+  resolveRepoPath,
+  resolveRepoRelativePath,
+  preflightCheck,
+  commitPerRepo,
+  retryCommitPerRepo,
+  detectManualResolution,
+  buildPlanningCommitBody,
+  detectRepoChanges,
+  createRepoBranches,
+  reportBranchesToMerge,
+  updateRepoStatus,
+  cmdCommitMultiRepo,
+  cmdCommitPreflight,
+} = require('./execution.cjs');
+
+// ─── resolveRepoRelativePath ─────────────────────────────────────────────────
+
+describe('resolveRepoRelativePath', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('resolves src/index.ts in repo web-app to correct absolute path', () => {
+    setupProductRoot(tmpDir, ['web-app']);
+    const result = resolveRepoRelativePath(tmpDir, 'web-app', 'src/index.ts');
+    assert.ok(result);
+    assert.strictEqual(result.absFilePath, path.join(tmpDir, 'web-app', 'src', 'index.ts'));
+    assert.strictEqual(result.repoAbsPath, path.join(tmpDir, 'web-app'));
+    assert.strictEqual(result.repo.name, 'web-app');
+  });
+
+  it('returns null for unknown repo name', () => {
+    setupProductRoot(tmpDir, ['web-app']);
+    const result = resolveRepoRelativePath(tmpDir, 'nonexistent', 'src/index.ts');
+    assert.strictEqual(result, null);
+  });
+
+  it('works with ../repo paths in REPOS.md (sibling layout)', () => {
+    // Create a sibling-layout product root
+    const productRoot = path.join(tmpDir, 'product-root');
+    const planningDir = path.join(productRoot, '.planning');
+    fs.mkdirSync(planningDir, { recursive: true });
+
+    let reposMd = '# Repos\n\n';
+    reposMd += '| Name | Path | GitHub URL | Description |\n';
+    reposMd += '|------|------|------------|-------------|\n';
+    reposMd += '| api-service | ../api-service | | Test repo |\n';
+
+    fs.writeFileSync(path.join(planningDir, 'REPOS.md'), reposMd);
+    fs.mkdirSync(path.join(tmpDir, 'api-service'), { recursive: true });
+
+    const result = resolveRepoRelativePath(productRoot, 'api-service', 'src/server.ts');
+    assert.ok(result);
+    assert.strictEqual(result.absFilePath, path.join(tmpDir, 'api-service', 'src', 'server.ts'));
+    assert.strictEqual(result.repoAbsPath, path.join(tmpDir, 'api-service'));
+  });
+
+  it('handles nested paths like src/components/Button.tsx', () => {
+    setupProductRoot(tmpDir, ['web-app']);
+    const result = resolveRepoRelativePath(tmpDir, 'web-app', 'src/components/Button.tsx');
+    assert.ok(result);
+    assert.strictEqual(result.absFilePath, path.join(tmpDir, 'web-app', 'src', 'components', 'Button.tsx'));
+  });
+
+  it('accepts pre-loaded repos array', () => {
+    setupProductRoot(tmpDir, ['web-app']);
+    const repos = [{ name: 'web-app', path: './web-app' }];
+    const result = resolveRepoRelativePath(tmpDir, 'web-app', 'src/index.ts', repos);
+    assert.ok(result);
+    assert.strictEqual(result.absFilePath, path.join(tmpDir, 'web-app', 'src', 'index.ts'));
+  });
+});
+
+// ─── preflightCheck ─────────────────────────────────────────────────────────
+
+describe('preflightCheck', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('all repos clean — passed: true', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+    const result = preflightCheck(tmpDir, ['repo-a', 'repo-b']);
+    assert.strictEqual(result.passed, true);
+    assert.strictEqual(result.dirty_repos.length, 0);
+  });
+
+  it('one dirty repo (modified tracked files) — passed: false', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+    // Make repo-a dirty by modifying a tracked file
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'README.md'), '# Modified\n');
+    const result = preflightCheck(tmpDir, ['repo-a', 'repo-b']);
+    assert.strictEqual(result.passed, false);
+    assert.ok(result.dirty_repos.length > 0);
+    assert.ok(result.dirty_repos.some(d => d.name === 'repo-a'));
+  });
+
+  it('multiple dirty repos — all listed in dirty_repos', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'README.md'), '# Mod A\n');
+    fs.writeFileSync(path.join(tmpDir, 'repo-b', 'README.md'), '# Mod B\n');
+    const result = preflightCheck(tmpDir, ['repo-a', 'repo-b']);
+    assert.strictEqual(result.passed, false);
+    assert.strictEqual(result.dirty_repos.length, 2);
+  });
+
+  it('untracked-only files (??) — NOT dirty (passed: true)', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    // Add untracked file (not staged, not committed)
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'newfile.txt'), 'untracked');
+    const result = preflightCheck(tmpDir, ['repo-a']);
+    assert.strictEqual(result.passed, true);
+  });
+
+  it('missing repo (not on disk) — missing_repos populated', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    const result = preflightCheck(tmpDir, ['repo-a', 'repo-missing']);
+    assert.ok(result.missing_repos.includes('repo-missing'));
+  });
+
+  it('no SUMMARY.md file exists — partial_execution is null', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    const result = preflightCheck(tmpDir, ['repo-a']);
+    assert.strictEqual(result.partial_execution, null);
+  });
+
+  it('SUMMARY.md with status: partial — passed: false, partial_execution set', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    const phaseDir = path.join(tmpDir, '.planning', 'phases', '04-test');
+    fs.mkdirSync(phaseDir, { recursive: true });
+    fs.writeFileSync(path.join(phaseDir, '04-01-SUMMARY.md'),
+      '---\nphase: 04-test\nplan: 01\nstatus: partial\n---\n# Summary\n');
+    const result = preflightCheck(tmpDir, ['repo-a'], phaseDir);
+    assert.strictEqual(result.passed, false);
+    assert.ok(result.partial_execution !== null);
+  });
+
+  it('SUMMARY.md with status: complete — passed: true', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    const phaseDir = path.join(tmpDir, '.planning', 'phases', '04-test');
+    fs.mkdirSync(phaseDir, { recursive: true });
+    fs.writeFileSync(path.join(phaseDir, '04-01-SUMMARY.md'),
+      '---\nphase: 04-test\nplan: 01\nstatus: complete\n---\n# Summary\n');
+    const result = preflightCheck(tmpDir, ['repo-a'], phaseDir);
+    assert.strictEqual(result.passed, true);
+    assert.strictEqual(result.partial_execution, null);
+  });
+});
+
+// ─── commitPerRepo ──────────────────────────────────────────────────────────
+
+describe('commitPerRepo', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  const options = {
+    type: 'feat',
+    project: 'test-project',
+    phase: '04',
+    plan: '01',
+    description: 'add feature',
+  };
+
+  it('single repo with one changed file — committed, SHA returned', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    // Create a new file to commit
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'new.js'), 'console.log("hi");\n');
+    const repoChanges = [{ repoName: 'repo-a', repoPath: './repo-a', files: ['new.js'] }];
+    const results = commitPerRepo(tmpDir, repoChanges, options);
+    assert.strictEqual(results.length, 1);
+    assert.strictEqual(results[0].repo, 'repo-a');
+    assert.strictEqual(results[0].status, 'complete');
+    assert.ok(results[0].sha);
+  });
+
+  it('two repos with changes — both committed in alphabetical order', () => {
+    setupProductRoot(tmpDir, ['repo-b', 'repo-a']);
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'a.js'), 'a');
+    fs.writeFileSync(path.join(tmpDir, 'repo-b', 'b.js'), 'b');
+    const repoChanges = [
+      { repoName: 'repo-b', repoPath: './repo-b', files: ['b.js'] },
+      { repoName: 'repo-a', repoPath: './repo-a', files: ['a.js'] },
+    ];
+    const results = commitPerRepo(tmpDir, repoChanges, options);
+    assert.strictEqual(results.length, 2);
+    // Should be sorted alphabetically
+    assert.strictEqual(results[0].repo, 'repo-a');
+    assert.strictEqual(results[1].repo, 'repo-b');
+  });
+
+  it('commit message format: type(project/phase-plan): description', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'new.js'), 'code');
+    const repoChanges = [{ repoName: 'repo-a', repoPath: './repo-a', files: ['new.js'] }];
+    commitPerRepo(tmpDir, repoChanges, options);
+    // Check the actual git log
+    const log = execSync('git log --oneline -1', {
+      cwd: path.join(tmpDir, 'repo-a'),
+      encoding: 'utf-8',
+    }).trim();
+    assert.ok(log.includes('feat(test-project/04-01): add feature'));
+  });
+
+  it('repo with no staged changes after add — status: failed or skipped', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    // Don't create any new file — nothing to commit
+    const repoChanges = [{ repoName: 'repo-a', repoPath: './repo-a', files: ['nonexistent.js'] }];
+    const results = commitPerRepo(tmpDir, repoChanges, options);
+    assert.strictEqual(results.length, 1);
+    assert.ok(results[0].status === 'failed' || results[0].status === 'skipped');
+  });
+
+  it('verify actual git log shows correct commit message', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'file.js'), 'x');
+    const repoChanges = [{ repoName: 'repo-a', repoPath: './repo-a', files: ['file.js'] }];
+    const results = commitPerRepo(tmpDir, repoChanges, options);
+    const sha = results[0].sha;
+    const log = execSync(`git log --format="%H %s" -1`, {
+      cwd: path.join(tmpDir, 'repo-a'),
+      encoding: 'utf-8',
+    }).trim();
+    assert.ok(log.includes('feat(test-project/04-01): add feature'));
+  });
+
+  it('multiple files in single repo — all staged and committed', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'a.js'), 'a');
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'b.js'), 'b');
+    const repoChanges = [{ repoName: 'repo-a', repoPath: './repo-a', files: ['a.js', 'b.js'] }];
+    const results = commitPerRepo(tmpDir, repoChanges, options);
+    assert.strictEqual(results[0].status, 'complete');
+    // Check both files are in the commit
+    const diff = execSync('git diff-tree --no-commit-id --name-only -r HEAD', {
+      cwd: path.join(tmpDir, 'repo-a'),
+      encoding: 'utf-8',
+    }).trim();
+    assert.ok(diff.includes('a.js'));
+    assert.ok(diff.includes('b.js'));
+  });
+});
+
+// ─── buildPlanningCommitBody ────────────────────────────────────────────────
+
+describe('buildPlanningCommitBody', () => {
+  it('single completed repo — single line', () => {
+    const results = [{ repo: 'my-app', status: 'complete', sha: 'abc1234' }];
+    const body = buildPlanningCommitBody(results);
+    assert.ok(body.includes('Repo: my-app SHA: abc1234'));
+  });
+
+  it('multiple completed repos — multiple lines, alphabetical', () => {
+    const results = [
+      { repo: 'web-app', status: 'complete', sha: 'def5678' },
+      { repo: 'api-service', status: 'complete', sha: 'abc1234' },
+    ];
+    const body = buildPlanningCommitBody(results);
+    const lines = body.split('\n').filter(l => l.trim());
+    assert.ok(lines[0].includes('api-service'));
+    assert.ok(lines[1].includes('web-app'));
+  });
+
+  it('mix of complete and failed — only complete repos in body', () => {
+    const results = [
+      { repo: 'my-app', status: 'complete', sha: 'abc1234' },
+      { repo: 'broken', status: 'failed', sha: null, error: 'git error' },
+    ];
+    const body = buildPlanningCommitBody(results);
+    assert.ok(body.includes('my-app'));
+    assert.ok(!body.includes('broken'));
+  });
+
+  it('no completed repos — empty string', () => {
+    const results = [
+      { repo: 'broken', status: 'failed', sha: null, error: 'git error' },
+    ];
+    const body = buildPlanningCommitBody(results);
+    assert.strictEqual(body, '');
+  });
+
+  it('empty results array — empty string', () => {
+    const body = buildPlanningCommitBody([]);
+    assert.strictEqual(body, '');
+  });
+});
+
+// ─── detectRepoChanges ──────────────────────────────────────────────────────
+
+describe('detectRepoChanges', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('repo with modified file — listed', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'README.md'), '# Modified\n');
+    const result = detectRepoChanges(tmpDir, ['repo-a']);
+    assert.strictEqual(result.length, 1);
+    assert.strictEqual(result[0].repoName, 'repo-a');
+    assert.ok(result[0].files.length > 0);
+  });
+
+  it('repo with new (untracked) file — listed', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'newfile.txt'), 'new content');
+    const result = detectRepoChanges(tmpDir, ['repo-a']);
+    assert.strictEqual(result.length, 1);
+    assert.ok(result[0].files.some(f => f.includes('newfile.txt')));
+  });
+
+  it('repo with no changes — excluded from results', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+    // Only modify repo-a
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'README.md'), '# Changed\n');
+    const result = detectRepoChanges(tmpDir, ['repo-a', 'repo-b']);
+    assert.strictEqual(result.length, 1);
+    assert.strictEqual(result[0].repoName, 'repo-a');
+  });
+
+  it('multiple repos with mixed changes — correctly grouped', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'a.js'), 'a');
+    fs.writeFileSync(path.join(tmpDir, 'repo-b', 'b.js'), 'b');
+    const result = detectRepoChanges(tmpDir, ['repo-a', 'repo-b']);
+    assert.strictEqual(result.length, 2);
+  });
+
+  it('file paths are relative to repo root, not product root', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    fs.mkdirSync(path.join(tmpDir, 'repo-a', 'src'), { recursive: true });
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'src', 'index.js'), 'code');
+    const result = detectRepoChanges(tmpDir, ['repo-a']);
+    // Files should NOT start with 'repo-a/'
+    for (const f of result[0].files) {
+      assert.ok(!f.startsWith('repo-a/'), `Expected relative to repo root, got: ${f}`);
+    }
+  });
+
+  it('returns empty array when no repos have changes', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+    const result = detectRepoChanges(tmpDir, ['repo-a', 'repo-b']);
+    assert.strictEqual(result.length, 0);
+  });
+});
+
+// ─── Edge Cases ─────────────────────────────────────────────────────────────
+
+describe('preflightCheck edge cases', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('empty repoNames array — passed: true (vacuously)', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    const result = preflightCheck(tmpDir, []);
+    assert.strictEqual(result.passed, true);
+  });
+
+  it('repo with staged but not committed changes — dirty', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'staged.js'), 'staged content');
+    execSync('git add staged.js', { cwd: path.join(tmpDir, 'repo-a'), stdio: 'pipe' });
+    const result = preflightCheck(tmpDir, ['repo-a']);
+    assert.strictEqual(result.passed, false);
+    assert.ok(result.dirty_repos.length > 0);
+  });
+});
+
+describe('commitPerRepo edge cases', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  const options = {
+    type: 'feat',
+    project: 'test-project',
+    phase: '04',
+    plan: '02',
+    description: 'edge case test',
+  };
+
+  it('empty repoChanges array — empty results', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    const results = commitPerRepo(tmpDir, [], options);
+    assert.strictEqual(results.length, 0);
+  });
+});
+
+describe('detectRepoChanges edge cases', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('repo with deleted file — listed', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    // Delete a tracked file
+    fs.unlinkSync(path.join(tmpDir, 'repo-a', 'README.md'));
+    const result = detectRepoChanges(tmpDir, ['repo-a']);
+    assert.strictEqual(result.length, 1);
+    assert.ok(result[0].files.some(f => f.includes('README.md')));
+  });
+});
+
+describe('roundtrip integration', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('detectRepoChanges -> commitPerRepo -> buildPlanningCommitBody produces coherent result', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'new.js'), 'a');
+    fs.writeFileSync(path.join(tmpDir, 'repo-b', 'new.js'), 'b');
+
+    const options = {
+      type: 'feat',
+      project: 'integration',
+      phase: '04',
+      plan: '02',
+      description: 'roundtrip test',
+    };
+
+    // Step 1: detect changes
+    const changes = detectRepoChanges(tmpDir, ['repo-a', 'repo-b']);
+    assert.strictEqual(changes.length, 2);
+
+    // Step 2: commit per repo
+    const results = commitPerRepo(tmpDir, changes, options);
+    assert.strictEqual(results.length, 2);
+    assert.ok(results.every(r => r.status === 'complete'));
+
+    // Step 3: build planning commit body
+    const body = buildPlanningCommitBody(results);
+    assert.ok(body.includes('repo-a'));
+    assert.ok(body.includes('repo-b'));
+    assert.ok(body.includes('SHA:'));
+  });
+});
+
+// ─── createRepoBranches ─────────────────────────────────────────────────────
+
+describe('createRepoBranches', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('branching_strategy none — created: false', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    const result = createRepoBranches(tmpDir, ['repo-a'], 'dgs/test/01-setup', { branching_strategy: 'none' });
+    assert.strictEqual(result.created, false);
+    assert.strictEqual(result.reason, 'branching_disabled');
+  });
+
+  it('new branch created successfully', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    const result = createRepoBranches(tmpDir, ['repo-a'], 'dgs/test/01-setup', { branching_strategy: 'phase' });
+    assert.strictEqual(result.created, true);
+    assert.strictEqual(result.branches.length, 1);
+    assert.strictEqual(result.branches[0].action, 'created');
+    assert.strictEqual(result.branches[0].branch, 'dgs/test/01-setup');
+  });
+
+  it('existing branch reused (no error)', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    // Create branch first time
+    createRepoBranches(tmpDir, ['repo-a'], 'dgs/test/01-setup', { branching_strategy: 'phase' });
+    // Switch back to main
+    execSync('git checkout main', { cwd: path.join(tmpDir, 'repo-a'), stdio: 'pipe' });
+    // Create again — should reuse
+    const result = createRepoBranches(tmpDir, ['repo-a'], 'dgs/test/01-setup', { branching_strategy: 'phase' });
+    assert.strictEqual(result.branches[0].action, 'reused');
+  });
+
+  it('multiple repos all get same branch name', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+    const result = createRepoBranches(tmpDir, ['repo-a', 'repo-b'], 'dgs/test/01-setup', { branching_strategy: 'phase' });
+    assert.strictEqual(result.branches.length, 2);
+    assert.ok(result.branches.every(b => b.branch === 'dgs/test/01-setup'));
+  });
+
+  it('null config treated as branching enabled', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    const result = createRepoBranches(tmpDir, ['repo-a'], 'dgs/test/01-setup', null);
+    assert.strictEqual(result.created, true);
+  });
+});
+
+// ─── createRepoBranches prefix collision ─────────────────────────────────────
+
+describe('createRepoBranches prefix collision', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('detects prefix collision when creating similar branch name', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    // Create first branch
+    createRepoBranches(tmpDir, ['repo-a'], 'dgs/api-v2/phase-01', { branching_strategy: 'phase' });
+    // Switch back to main
+    execSync('git checkout main', { cwd: path.join(tmpDir, 'repo-a'), stdio: 'pipe' });
+    // Create a branch with a similar prefix — should detect collision
+    const result = createRepoBranches(tmpDir, ['repo-a'], 'dgs/api-v2-hotfix/phase-01', { branching_strategy: 'phase' });
+    assert.strictEqual(result.created, true);
+    assert.ok(result.warnings, 'Expected warnings array');
+    // The prefix collision check uses dgs/<projectSlug>* which is dgs/api-v2-hotfix*
+    // This would NOT match dgs/api-v2/phase-01 since "api-v2-hotfix" is the slug
+    // But dgs/api-v2/phase-01 starts with dgs/api-v2 which is a prefix of dgs/api-v2-hotfix
+    // The --list pattern is dgs/api-v2-hotfix* which won't match dgs/api-v2/phase-01
+    // So this specific direction won't trigger. Let's test the other direction.
+  });
+
+  it('no false positive when existing branch has different slug sharing prefix', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    // Create branch for api-v2-hotfix first
+    createRepoBranches(tmpDir, ['repo-a'], 'dgs/api-v2-hotfix/phase-01', { branching_strategy: 'phase' });
+    // Switch back to main
+    execSync('git checkout main', { cwd: path.join(tmpDir, 'repo-a'), stdio: 'pipe' });
+    // Create a branch with shorter slug — dgs/api-v2/* won't match dgs/api-v2-hotfix/phase-01
+    // because the '/' delimiter after the slug prevents partial matches
+    const result = createRepoBranches(tmpDir, ['repo-a'], 'dgs/api-v2/phase-01', { branching_strategy: 'phase' });
+    assert.strictEqual(result.created, true);
+    assert.ok(result.warnings !== undefined, 'warnings should exist');
+    assert.strictEqual(result.warnings.length, 0, 'no collision — different project slugs separated by /');
+  });
+
+  it('existing branch reuse returns empty warnings array', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    createRepoBranches(tmpDir, ['repo-a'], 'dgs/test/01-setup', { branching_strategy: 'phase' });
+    // Switch back to main
+    execSync('git checkout main', { cwd: path.join(tmpDir, 'repo-a'), stdio: 'pipe' });
+    // Reuse the same branch
+    const result = createRepoBranches(tmpDir, ['repo-a'], 'dgs/test/01-setup', { branching_strategy: 'phase' });
+    assert.ok(result.warnings !== undefined, 'warnings should exist');
+    assert.strictEqual(result.warnings.length, 0, 'reused branch should have no warnings');
+  });
+
+  it('new branch with no similar prefix returns empty warnings', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    const result = createRepoBranches(tmpDir, ['repo-a'], 'dgs/unique-project/phase-01', { branching_strategy: 'phase' });
+    assert.strictEqual(result.created, true);
+    assert.ok(result.warnings !== undefined, 'warnings should exist');
+    assert.strictEqual(result.warnings.length, 0);
+  });
+});
+
+// ─── createRepoBranches project-scoped prefix collision ──────────────────────
+
+describe('createRepoBranches project-scoped prefix collision', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('no collision when project slugs differ by / delimiter (checkout vs checkout-v2)', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    // Create branch for checkout-v2 project
+    createRepoBranches(tmpDir, ['repo-a'], 'dgs/checkout-v2/phase-01-init', { branching_strategy: 'phase' });
+    execSync('git checkout main', { cwd: path.join(tmpDir, 'repo-a'), stdio: 'pipe' });
+    // Create branch for checkout project — should NOT collide
+    const result = createRepoBranches(tmpDir, ['repo-a'], 'dgs/checkout/phase-02-auth', { branching_strategy: 'phase' });
+    assert.strictEqual(result.created, true);
+    assert.ok(result.warnings !== undefined, 'warnings should exist');
+    assert.strictEqual(result.warnings.length, 0, 'no collision — dgs/checkout/ does NOT match dgs/checkout-v2/');
+  });
+
+  it('collision detected for branches within same project scope', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    // Create branch for checkout project phase 01
+    createRepoBranches(tmpDir, ['repo-a'], 'dgs/checkout/phase-01-init', { branching_strategy: 'phase' });
+    execSync('git checkout main', { cwd: path.join(tmpDir, 'repo-a'), stdio: 'pipe' });
+    // Create another branch for same checkout project — should detect collision
+    const result = createRepoBranches(tmpDir, ['repo-a'], 'dgs/checkout/phase-02-auth', { branching_strategy: 'phase' });
+    assert.strictEqual(result.created, true);
+    assert.ok(result.warnings !== undefined, 'warnings should exist');
+    assert.ok(result.warnings.length > 0, 'should have collision warning for same-project branch');
+    // The warning object should list the existing branch
+    const collisionWarning = result.warnings.find(w => w.type === 'prefix_collision');
+    assert.ok(collisionWarning, 'should have prefix_collision warning');
+    assert.ok(collisionWarning.existing_branches.includes('dgs/checkout/phase-01-init'),
+      'warning should list the existing branch');
+  });
+
+  it('multi-project collision detection only matches own project', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    // Create branches for two different projects
+    createRepoBranches(tmpDir, ['repo-a'], 'dgs/alpha/phase-01-init', { branching_strategy: 'phase' });
+    execSync('git checkout main', { cwd: path.join(tmpDir, 'repo-a'), stdio: 'pipe' });
+    createRepoBranches(tmpDir, ['repo-a'], 'dgs/beta/phase-01-init', { branching_strategy: 'phase' });
+    execSync('git checkout main', { cwd: path.join(tmpDir, 'repo-a'), stdio: 'pipe' });
+    // Create another branch for alpha project — should only see alpha branches in collision
+    const result = createRepoBranches(tmpDir, ['repo-a'], 'dgs/alpha/phase-02-auth', { branching_strategy: 'phase' });
+    assert.strictEqual(result.created, true);
+    assert.ok(result.warnings !== undefined, 'warnings should exist');
+    assert.ok(result.warnings.length > 0, 'should have collision warning');
+    const collisionWarning = result.warnings.find(w => w.type === 'prefix_collision');
+    assert.ok(collisionWarning, 'should have prefix_collision warning');
+    assert.ok(collisionWarning.existing_branches.includes('dgs/alpha/phase-01-init'),
+      'warning should list alpha phase-01 branch');
+    // Beta project branches should NOT appear in the collision warning
+    const allExistingBranches = collisionWarning.existing_branches.join(' ');
+    assert.ok(!allExistingBranches.includes('dgs/beta/'),
+      'warning should NOT include beta project branches');
+  });
+});
+
+// ─── createRepoBranches base_branch ──────────────────────────────────────────
+
+describe('createRepoBranches base_branch', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('without baseBranch creates branch from HEAD (backwards compat)', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    const result = createRepoBranches(tmpDir, ['repo-a'], 'dgs/phase-01-test', { branching_strategy: 'phase' });
+    assert.strictEqual(result.created, true);
+    assert.strictEqual(result.branches.length, 1);
+    assert.strictEqual(result.branches[0].action, 'created');
+  });
+
+  it('with baseBranch checks out base before creating branch', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    const repoPath = path.join(tmpDir, 'repo-a');
+
+    // Create a 'develop' branch with an additional commit
+    execSync('git checkout -b develop', { cwd: repoPath, stdio: 'pipe' });
+    fs.writeFileSync(path.join(repoPath, 'feature.txt'), 'develop feature\n');
+    execSync('git add feature.txt', { cwd: repoPath, stdio: 'pipe' });
+    execSync('git commit -m "develop commit"', { cwd: repoPath, stdio: 'pipe' });
+    const developHead = execSync('git rev-parse develop', { cwd: repoPath, encoding: 'utf-8', stdio: 'pipe' }).trim();
+
+    // Switch back to main
+    execSync('git checkout main', { cwd: repoPath, stdio: 'pipe' });
+
+    // Create branch from develop baseBranch
+    const result = createRepoBranches(tmpDir, ['repo-a'], 'dgs/phase-01-test', { branching_strategy: 'phase' }, 'develop');
+    assert.strictEqual(result.created, true);
+    assert.strictEqual(result.branches[0].action, 'created');
+
+    // Verify the new branch's HEAD matches develop's HEAD (not main's)
+    const branchHead = execSync('git rev-parse dgs/phase-01-test', { cwd: repoPath, encoding: 'utf-8', stdio: 'pipe' }).trim();
+    assert.strictEqual(branchHead, developHead, 'new branch should start from develop');
+  });
+
+  it('returns error when baseBranch does not exist', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    const result = createRepoBranches(tmpDir, ['repo-a'], 'dgs/phase-01-test', { branching_strategy: 'phase' }, 'nonexistent-branch');
+    assert.strictEqual(result.created, false);
+    assert.strictEqual(result.reason, 'base_branch_missing');
+    assert.ok(result.error.includes('nonexistent-branch'), 'error should mention the missing branch name');
+    assert.ok(result.error.includes('does not exist'), 'error should say branch does not exist');
+  });
+
+  it('validates all repos before creating any branches', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+    const repoAPath = path.join(tmpDir, 'repo-a');
+    const repoBPath = path.join(tmpDir, 'repo-b');
+
+    // Create 'develop' branch in repo-a only
+    execSync('git checkout -b develop', { cwd: repoAPath, stdio: 'pipe' });
+    fs.writeFileSync(path.join(repoAPath, 'feature.txt'), 'feature\n');
+    execSync('git add feature.txt', { cwd: repoAPath, stdio: 'pipe' });
+    execSync('git commit -m "develop commit"', { cwd: repoAPath, stdio: 'pipe' });
+    execSync('git checkout main', { cwd: repoAPath, stdio: 'pipe' });
+
+    // repo-b does NOT have 'develop' branch
+    const result = createRepoBranches(tmpDir, ['repo-a', 'repo-b'], 'dgs/phase-01-test', { branching_strategy: 'phase' }, 'develop');
+    assert.strictEqual(result.created, false);
+    assert.strictEqual(result.reason, 'base_branch_missing');
+
+    // Verify NO branch was created in repo-a (two-pass validation catches repo-b failure before creating anything)
+    try {
+      execSync('git rev-parse --verify dgs/phase-01-test', { cwd: repoAPath, stdio: 'pipe' });
+      assert.fail('branch should NOT exist in repo-a since repo-b failed validation');
+    } catch (e) {
+      // Expected: branch does not exist
+      assert.ok(true, 'branch correctly not created in repo-a');
+    }
+  });
+
+  it('with baseBranch reuses existing branch', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    const repoPath = path.join(tmpDir, 'repo-a');
+
+    // Create the target branch first
+    createRepoBranches(tmpDir, ['repo-a'], 'dgs/phase-01-test', { branching_strategy: 'phase' });
+    // Switch back to main
+    execSync('git checkout main', { cwd: repoPath, stdio: 'pipe' });
+
+    // Call again with baseBranch — should reuse the existing branch
+    const result = createRepoBranches(tmpDir, ['repo-a'], 'dgs/phase-01-test', { branching_strategy: 'phase' }, 'main');
+    assert.strictEqual(result.created, true);
+    assert.strictEqual(result.branches[0].action, 'reused');
+  });
+});
+
+// ─── reportBranchesToMerge ──────────────────────────────────────────────────
+
+describe('reportBranchesToMerge', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('repos with the branch — listed', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    createRepoBranches(tmpDir, ['repo-a'], 'dgs/test/01-setup', { branching_strategy: 'phase' });
+    const result = reportBranchesToMerge(tmpDir, ['repo-a'], 'dgs/test/01-setup');
+    assert.strictEqual(result.branches.length, 1);
+    assert.strictEqual(result.branches[0].exists, true);
+  });
+
+  it('repos without the branch — excluded', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    const result = reportBranchesToMerge(tmpDir, ['repo-a'], 'dgs/nonexistent/branch');
+    assert.strictEqual(result.branches.length, 0);
+  });
+
+  it('returns empty array when no repos have the branch', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+    const result = reportBranchesToMerge(tmpDir, ['repo-a', 'repo-b'], 'dgs/missing/branch');
+    assert.strictEqual(result.branches.length, 0);
+  });
+});
+
+// ─── updateRepoStatus ───────────────────────────────────────────────────────
+
+describe('updateRepoStatus', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('creates Repo Status section in STATE.md', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    // Create initial STATE.md
+    fs.writeFileSync(path.join(tmpDir, '.planning', 'STATE.md'), '# Project State\n\n## Current Position\nPhase: 4\n');
+    const repoResults = [{ repo: 'repo-a', status: 'complete', sha: 'abc1234' }];
+    updateRepoStatus(tmpDir, null, repoResults);
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'STATE.md'), 'utf-8');
+    assert.ok(content.includes('## Repo Status'));
+    assert.ok(content.includes('repo-a'));
+    assert.ok(content.includes('abc1234'));
+  });
+
+  it('updates existing Repo Status section (replace, not duplicate)', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    fs.writeFileSync(path.join(tmpDir, '.planning', 'STATE.md'),
+      '# State\n\n## Repo Status\n\n| Repo | Branch | Last Commit | Touched By |\n|------|--------|-------------|------------|\n| old | main | old123 | - |\n\n## Other\n');
+    const repoResults = [{ repo: 'repo-a', status: 'complete', sha: 'new456' }];
+    updateRepoStatus(tmpDir, null, repoResults);
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'STATE.md'), 'utf-8');
+    assert.ok(content.includes('new456'));
+    assert.ok(!content.includes('old123'));
+    // Should only have one Repo Status section
+    const count = (content.match(/## Repo Status/g) || []).length;
+    assert.strictEqual(count, 1);
+  });
+
+  it('handles repo with no branch (shows current branch)', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    fs.writeFileSync(path.join(tmpDir, '.planning', 'STATE.md'), '# State\n');
+    const repoResults = [{ repo: 'repo-a', status: 'complete', sha: 'abc1234' }];
+    updateRepoStatus(tmpDir, null, repoResults);
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'STATE.md'), 'utf-8');
+    // Should show 'main' or 'master' as current branch
+    assert.ok(content.includes('main') || content.includes('master'));
+  });
+
+  it('works when STATE.md has no existing Repo Status section', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    fs.writeFileSync(path.join(tmpDir, '.planning', 'STATE.md'), '# State\n\n## Current Position\nPhase: 4\n');
+    const repoResults = [{ repo: 'repo-a', status: 'complete', sha: 'abc1234' }];
+    updateRepoStatus(tmpDir, null, repoResults);
+    const content = fs.readFileSync(path.join(tmpDir, '.planning', 'STATE.md'), 'utf-8');
+    assert.ok(content.includes('## Repo Status'));
+  });
+});
+
+// ─── CLI Integration Tests ──────────────────────────────────────────────────
+
+describe('CLI integration: commit preflight', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('commit preflight with clean repos — returns passed: true via CLI', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+    const dgsTools = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+    const result = execSync(
+      `node ${dgsTools} commit preflight repo-a repo-b --raw`,
+      { cwd: tmpDir, encoding: 'utf-8' }
+    );
+    const json = JSON.parse(result.trim());
+    assert.strictEqual(json.passed, true);
+    assert.strictEqual(json.dirty_repos.length, 0);
+    assert.strictEqual(json.missing_repos.length, 0);
+  });
+
+  it('commit preflight with dirty repo — returns passed: false via CLI', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'README.md'), '# Changed\n');
+    const dgsTools = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+    const result = execSync(
+      `node ${dgsTools} commit preflight repo-a repo-b --raw`,
+      { cwd: tmpDir, encoding: 'utf-8' }
+    );
+    const json = JSON.parse(result.trim());
+    assert.strictEqual(json.passed, false);
+    assert.ok(json.dirty_repos.length > 0);
+    assert.ok(json.dirty_repos.some(d => d.name === 'repo-a'));
+  });
+
+  it('commit preflight with missing repo — returns missing_repos', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    const dgsTools = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+    const result = execSync(
+      `node ${dgsTools} commit preflight repo-a repo-missing --raw`,
+      { cwd: tmpDir, encoding: 'utf-8' }
+    );
+    const json = JSON.parse(result.trim());
+    assert.ok(json.missing_repos.includes('repo-missing'));
+  });
+});
+
+describe('CLI integration: commit --multi-repo', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('commit --multi-repo with changes in 2 repos — both committed', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'feature.js'), 'console.log("a");\n');
+    fs.writeFileSync(path.join(tmpDir, 'repo-b', 'feature.js'), 'console.log("b");\n');
+
+    const dgsTools = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+    const result = execSync(
+      `node ${dgsTools} commit --multi-repo --type feat --project test-proj --phase 04 --plan 03 --desc "integration test" --repos repo-a,repo-b --raw`,
+      { cwd: tmpDir, encoding: 'utf-8' }
+    );
+    const json = JSON.parse(result.trim());
+    assert.strictEqual(json.success, true);
+    assert.strictEqual(json.commits.length, 2);
+    assert.ok(json.commits.every(c => c.status === 'complete'));
+    assert.ok(json.commits.every(c => c.sha));
+    assert.ok(json.planning_body.includes('repo-a'));
+    assert.ok(json.planning_body.includes('repo-b'));
+
+    // Verify actual git commits in each repo
+    const logA = execSync('git log --oneline -1', { cwd: path.join(tmpDir, 'repo-a'), encoding: 'utf-8' }).trim();
+    assert.ok(logA.includes('feat(test-proj/04-03): integration test'));
+    const logB = execSync('git log --oneline -1', { cwd: path.join(tmpDir, 'repo-b'), encoding: 'utf-8' }).trim();
+    assert.ok(logB.includes('feat(test-proj/04-03): integration test'));
+  });
+
+  it('commit --multi-repo with no changes — returns success with empty commits', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+    const dgsTools = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+    const result = execSync(
+      `node ${dgsTools} commit --multi-repo --type feat --project test-proj --phase 04 --plan 03 --desc "no changes" --repos repo-a --raw`,
+      { cwd: tmpDir, encoding: 'utf-8' }
+    );
+    const json = JSON.parse(result.trim());
+    assert.strictEqual(json.success, true);
+    assert.ok(json.message.includes('No changes'));
+  });
+
+  it('full lifecycle: preflight clean -> modify -> commit --multi-repo -> preflight clean again', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+    const dgsTools = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+
+    // Step 1: Preflight — should be clean
+    const pre1 = JSON.parse(execSync(
+      `node ${dgsTools} commit preflight repo-a repo-b --raw`,
+      { cwd: tmpDir, encoding: 'utf-8' }
+    ).trim());
+    assert.strictEqual(pre1.passed, true);
+
+    // Step 2: Modify files
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'new-feature.js'), 'export default {};');
+    fs.writeFileSync(path.join(tmpDir, 'repo-b', 'new-feature.js'), 'module.exports = {};');
+
+    // Step 3: Commit --multi-repo
+    const commitResult = JSON.parse(execSync(
+      `node ${dgsTools} commit --multi-repo --type feat --project lifecycle --phase 04 --plan 03 --desc "lifecycle test" --repos repo-a,repo-b --raw`,
+      { cwd: tmpDir, encoding: 'utf-8' }
+    ).trim());
+    assert.strictEqual(commitResult.success, true);
+    assert.strictEqual(commitResult.commits.length, 2);
+
+    // Step 4: Preflight again — should be clean (commits consumed the changes)
+    const pre2 = JSON.parse(execSync(
+      `node ${dgsTools} commit preflight repo-a repo-b --raw`,
+      { cwd: tmpDir, encoding: 'utf-8' }
+    ).trim());
+    assert.strictEqual(pre2.passed, true);
+  });
+});
+
+// ─── retryCommitPerRepo ─────────────────────────────────────────────────────
+
+describe('retryCommitPerRepo', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  const options = {
+    type: 'feat',
+    project: 'test-project',
+    phase: '04',
+    plan: '01',
+    description: 'retry test',
+  };
+
+  it('repo with prior complete status and valid SHA -- skipped, prior result carried forward', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+
+    // Commit something in repo-a to get a real SHA
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'initial.js'), 'init');
+    const repoChanges1 = [{ repoName: 'repo-a', repoPath: './repo-a', files: ['initial.js'] }];
+    const firstResults = commitPerRepo(tmpDir, repoChanges1, options);
+    const repoASha = firstResults[0].sha;
+
+    // Now modify repo-b only
+    fs.writeFileSync(path.join(tmpDir, 'repo-b', 'feature.js'), 'new');
+
+    // Create prior results showing repo-a as complete
+    const priorResults = [
+      { repo: 'repo-a', status: 'complete', sha: repoASha },
+      { repo: 'repo-b', status: 'failed', sha: null, error: 'some error' },
+    ];
+
+    // Retry with both repos but repo-a should be skipped
+    const repoChanges2 = [
+      { repoName: 'repo-a', repoPath: './repo-a', files: ['initial.js'] },
+      { repoName: 'repo-b', repoPath: './repo-b', files: ['feature.js'] },
+    ];
+    const results = retryCommitPerRepo(tmpDir, repoChanges2, options, priorResults);
+
+    assert.strictEqual(results.length, 2);
+    const repoA = results.find(r => r.repo === 'repo-a');
+    const repoB = results.find(r => r.repo === 'repo-b');
+    // repo-a carried forward with same SHA
+    assert.strictEqual(repoA.status, 'complete');
+    assert.strictEqual(repoA.sha, repoASha);
+    // repo-b committed fresh
+    assert.strictEqual(repoB.status, 'complete');
+    assert.ok(repoB.sha);
+    assert.notStrictEqual(repoB.sha, repoASha);
+  });
+
+  it('repo with prior failed status -- retried normally', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'a.js'), 'a');
+    fs.writeFileSync(path.join(tmpDir, 'repo-b', 'b.js'), 'b');
+
+    const priorResults = [
+      { repo: 'repo-a', status: 'failed', sha: null, error: 'disk full' },
+      { repo: 'repo-b', status: 'failed', sha: null, error: 'disk full' },
+    ];
+
+    const repoChanges = [
+      { repoName: 'repo-a', repoPath: './repo-a', files: ['a.js'] },
+      { repoName: 'repo-b', repoPath: './repo-b', files: ['b.js'] },
+    ];
+    const results = retryCommitPerRepo(tmpDir, repoChanges, options, priorResults);
+
+    assert.strictEqual(results.length, 2);
+    assert.ok(results.every(r => r.status === 'complete'));
+    assert.ok(results.every(r => r.sha));
+  });
+
+  it('repo with prior SHA that no longer exists (force-push/rebase) -- retried', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+
+    // Create a second commit to have something to reset away
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'temp.txt'), 'temp');
+    execSync('git add temp.txt && git commit -m "temp commit"', {
+      cwd: path.join(tmpDir, 'repo-a'), stdio: 'pipe',
+    });
+    // Record the SHA of the second commit
+    const staleSha = execSync('git rev-parse --short HEAD', {
+      cwd: path.join(tmpDir, 'repo-a'), encoding: 'utf-8',
+    }).trim();
+
+    // Reset to remove that commit (makes staleSha unreachable after gc, but
+    // rev-parse --verify can still find it via reflog; use a clearly bogus SHA instead)
+    execSync('git reset --hard HEAD~1', {
+      cwd: path.join(tmpDir, 'repo-a'), stdio: 'pipe',
+    });
+
+    // Use a fabricated SHA that definitely doesn't exist
+    const fakeSha = 'aaaa000';
+
+    // Write a new file to commit
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'retry.js'), 'retry');
+
+    const priorResults = [
+      { repo: 'repo-a', status: 'complete', sha: fakeSha },
+    ];
+    const repoChanges = [
+      { repoName: 'repo-a', repoPath: './repo-a', files: ['retry.js'] },
+    ];
+    const results = retryCommitPerRepo(tmpDir, repoChanges, options, priorResults);
+
+    assert.strictEqual(results.length, 1);
+    assert.strictEqual(results[0].status, 'complete');
+    assert.ok(results[0].sha);
+    assert.notStrictEqual(results[0].sha, fakeSha);
+  });
+
+  it('empty priorResults -- all repos committed normally (same as commitPerRepo)', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'a.js'), 'a');
+    fs.writeFileSync(path.join(tmpDir, 'repo-b', 'b.js'), 'b');
+
+    const repoChanges = [
+      { repoName: 'repo-a', repoPath: './repo-a', files: ['a.js'] },
+      { repoName: 'repo-b', repoPath: './repo-b', files: ['b.js'] },
+    ];
+    const results = retryCommitPerRepo(tmpDir, repoChanges, options, []);
+
+    assert.strictEqual(results.length, 2);
+    assert.ok(results.every(r => r.status === 'complete'));
+  });
+
+  it('all repos already complete in priorResults -- returns carried-forward results, no new commits', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+
+    // Create real commits to have valid SHAs
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'done.js'), 'done');
+    fs.writeFileSync(path.join(tmpDir, 'repo-b', 'done.js'), 'done');
+    const initialChanges = [
+      { repoName: 'repo-a', repoPath: './repo-a', files: ['done.js'] },
+      { repoName: 'repo-b', repoPath: './repo-b', files: ['done.js'] },
+    ];
+    const initialResults = commitPerRepo(tmpDir, initialChanges, options);
+    const shaA = initialResults.find(r => r.repo === 'repo-a').sha;
+    const shaB = initialResults.find(r => r.repo === 'repo-b').sha;
+
+    // Get commit counts before retry
+    const countBeforeA = execSync('git rev-list --count HEAD', {
+      cwd: path.join(tmpDir, 'repo-a'), encoding: 'utf-8',
+    }).trim();
+    const countBeforeB = execSync('git rev-list --count HEAD', {
+      cwd: path.join(tmpDir, 'repo-b'), encoding: 'utf-8',
+    }).trim();
+
+    const priorResults = [
+      { repo: 'repo-a', status: 'complete', sha: shaA },
+      { repo: 'repo-b', status: 'complete', sha: shaB },
+    ];
+
+    // repoChanges still references the files but they should not be re-committed
+    const results = retryCommitPerRepo(tmpDir, initialChanges, options, priorResults);
+
+    assert.strictEqual(results.length, 2);
+    assert.ok(results.every(r => r.status === 'complete'));
+    assert.strictEqual(results.find(r => r.repo === 'repo-a').sha, shaA);
+    assert.strictEqual(results.find(r => r.repo === 'repo-b').sha, shaB);
+
+    // No new commits created
+    const countAfterA = execSync('git rev-list --count HEAD', {
+      cwd: path.join(tmpDir, 'repo-a'), encoding: 'utf-8',
+    }).trim();
+    const countAfterB = execSync('git rev-list --count HEAD', {
+      cwd: path.join(tmpDir, 'repo-b'), encoding: 'utf-8',
+    }).trim();
+    assert.strictEqual(countAfterA, countBeforeA);
+    assert.strictEqual(countAfterB, countBeforeB);
+  });
+
+  it('selective staging -- only plan-specified files are committed, other changed files excluded', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+
+    // Write two files but only include one in repoChanges
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'plan-file.txt'), 'plan content');
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'other-file.txt'), 'other content');
+
+    const repoChanges = [
+      { repoName: 'repo-a', repoPath: './repo-a', files: ['plan-file.txt'] },
+    ];
+    const results = retryCommitPerRepo(tmpDir, repoChanges, options, []);
+
+    assert.strictEqual(results.length, 1);
+    assert.strictEqual(results[0].status, 'complete');
+
+    // Verify only plan-file.txt was committed
+    const committed = execSync('git show --name-only --format="" HEAD', {
+      cwd: path.join(tmpDir, 'repo-a'), encoding: 'utf-8',
+    }).trim();
+    assert.ok(committed.includes('plan-file.txt'), `Expected plan-file.txt in commit, got: ${committed}`);
+    assert.ok(!committed.includes('other-file.txt'), `Expected other-file.txt NOT in commit, got: ${committed}`);
+
+    // other-file.txt should still be untracked
+    const status = execSync('git status --porcelain', {
+      cwd: path.join(tmpDir, 'repo-a'), encoding: 'utf-8',
+    }).trim();
+    assert.ok(status.includes('other-file.txt'), `Expected other-file.txt still untracked, got: ${status}`);
+  });
+});
+
+// ─── detectManualResolution ─────────────────────────────────────────────────
+
+describe('detectManualResolution', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('clean working tree with all expected files present -- resolved: true, reason: manually_resolved', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+
+    // Create and commit the expected files (simulating manual user commit)
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'feature.js'), 'manual fix');
+    execSync('git add feature.js && git commit -m "manual fix"', {
+      cwd: path.join(tmpDir, 'repo-a'), stdio: 'pipe',
+    });
+
+    const result = detectManualResolution(tmpDir, 'repo-a', ['feature.js']);
+    assert.strictEqual(result.resolved, true);
+    assert.strictEqual(result.reason, 'manually_resolved');
+  });
+
+  it('expected files still modified (dirty) -- resolved: false, reason: unresolved', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+
+    // Create file but leave it uncommitted (dirty)
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'feature.js'), 'uncommitted');
+
+    const result = detectManualResolution(tmpDir, 'repo-a', ['feature.js']);
+    assert.strictEqual(result.resolved, false);
+    assert.strictEqual(result.reason, 'unresolved');
+  });
+
+  it('prior SHA verified -- resolved: true, reason: sha_verified', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+
+    // Create and commit file, then check with its SHA
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'feature.js'), 'committed');
+    execSync('git add feature.js && git commit -m "dgs commit"', {
+      cwd: path.join(tmpDir, 'repo-a'), stdio: 'pipe',
+    });
+    const sha = execSync('git rev-parse --short HEAD', {
+      cwd: path.join(tmpDir, 'repo-a'), encoding: 'utf-8',
+    }).trim();
+
+    const result = detectManualResolution(tmpDir, 'repo-a', ['feature.js'], sha);
+    assert.strictEqual(result.resolved, true);
+    assert.strictEqual(result.reason, 'sha_verified');
+  });
+
+  it('expected file missing from disk -- resolved: false', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+
+    // Do NOT create the expected file
+    const result = detectManualResolution(tmpDir, 'repo-a', ['missing-file.js']);
+    assert.strictEqual(result.resolved, false);
+    assert.strictEqual(result.reason, 'unresolved');
+  });
+});
+
+// ─── cmdCommitMultiRepo advisory preflight ──────────────────────────────────
+
+describe('cmdCommitMultiRepo advisory preflight', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('dirty repo produces warning but commit proceeds for other repos', () => {
+    setupProductRoot(tmpDir, ['repo-a', 'repo-b']);
+
+    // Make repo-a dirty (modify tracked file) -- this would have blocked before
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'README.md'), '# Dirty changes\n');
+    // Give repo-b a new untracked file to commit
+    fs.writeFileSync(path.join(tmpDir, 'repo-b', 'feature.js'), 'new feature');
+
+    const dgsTools = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+    const result = execSync(
+      `node ${dgsTools} commit --multi-repo --type feat --project test-proj --phase 04 --plan 03 --desc "advisory test" --repos repo-a,repo-b --raw`,
+      { cwd: tmpDir, encoding: 'utf-8' }
+    );
+    const json = JSON.parse(result.trim());
+
+    // Should have warnings about repo-a being dirty
+    assert.ok(json.warnings, 'Expected warnings array in output');
+    assert.ok(json.warnings.length > 0, 'Expected at least one warning');
+    assert.ok(json.warnings.some(w => w.type === 'dirty_repo' && w.repo === 'repo-a'),
+      'Expected dirty_repo warning for repo-a');
+
+    // repo-b should have been committed successfully
+    assert.strictEqual(json.success, true);
+    assert.ok(json.commits.length > 0);
+    assert.ok(json.commits.some(c => c.repo === 'repo-b' && c.status === 'complete'));
+  });
+
+  it('missing repo still blocks execution (hard error)', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+
+    // Reference a repo that doesn't exist
+    const dgsTools = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+    const result = execSync(
+      `node ${dgsTools} commit --multi-repo --type feat --project test-proj --phase 04 --plan 03 --desc "missing test" --repos repo-a,nonexistent --raw`,
+      { cwd: tmpDir, encoding: 'utf-8' }
+    );
+    const json = JSON.parse(result.trim());
+
+    assert.strictEqual(json.success, false);
+    assert.ok(json.preflight.missing_repos.includes('nonexistent'));
+  });
+
+  it('partial_execution detected -- included as info, does not block', () => {
+    setupProductRoot(tmpDir, ['repo-a']);
+
+    // Create a phase dir with a partial SUMMARY.md
+    const phaseDir = path.join(tmpDir, '.planning', 'phases', '04-test');
+    fs.mkdirSync(phaseDir, { recursive: true });
+    fs.writeFileSync(path.join(phaseDir, '04-01-SUMMARY.md'),
+      '---\nphase: 04-test\nplan: 01\nstatus: partial\n---\n# Summary\n');
+
+    // Add new file to repo-a so there's something to commit
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'feature.js'), 'code');
+
+    // Test at the preflight level: partial_execution is detected but we verify
+    // the cmdCommitMultiRepo advisory behavior via the preflight result shape.
+    // cmdCommitMultiRepo calls process.exit(0) via output(), so we test the
+    // advisory logic indirectly: preflight detects partial but cmdCommitMultiRepo
+    // no longer blocks on it — only missing_repos blocks.
+    const preflight = preflightCheck(tmpDir, ['repo-a'], phaseDir);
+    assert.strictEqual(preflight.passed, false, 'Preflight with partial should report passed: false');
+    assert.ok(preflight.partial_execution !== null, 'Expected partial_execution info');
+    assert.strictEqual(preflight.missing_repos.length, 0, 'No missing repos');
+    assert.strictEqual(preflight.dirty_repos.length, 0, 'No dirty repos');
+
+    // Since missing_repos is empty, cmdCommitMultiRepo would proceed (advisory).
+    // Verify by running the commit through CLI via a helper script that passes phaseDir
+    // We write a small script to invoke cmdCommitMultiRepo with phaseDir
+    const helperScript = path.join(tmpDir, '_test_helper.cjs');
+    const executionPath = path.resolve(__dirname, 'execution.cjs');
+    fs.writeFileSync(helperScript, `
+      const execution = require('${executionPath.replace(/\\/g, '\\\\')}');
+      const origExit = process.exit;
+      let exitCode = null;
+      process.exit = (code) => { exitCode = code; };
+      const chunks = [];
+      const origWrite = process.stdout.write;
+      process.stdout.write = (data) => { chunks.push(data); };
+      try {
+        execution.cmdCommitMultiRepo('${tmpDir.replace(/\\/g, '\\\\')}', {
+          type: 'feat', project: 'test-proj', phase: '04', plan: '01',
+          description: 'partial test', repos: ['repo-a'],
+          phaseDir: '${phaseDir.replace(/\\/g, '\\\\')}',
+        }, true);
+      } catch(e) {}
+      process.stdout.write = origWrite;
+      process.exit = origExit;
+      const output = chunks.join('');
+      try {
+        const json = JSON.parse(output);
+        console.log(JSON.stringify(json));
+      } catch(e) { console.log(output); }
+    `);
+
+    const result = execSync(`node ${helperScript}`, { encoding: 'utf-8' }).trim();
+    const json = JSON.parse(result);
+    assert.strictEqual(json.success, true, 'Expected success despite partial_execution');
+    assert.ok(json.warnings, 'Expected warnings array');
+    assert.ok(json.warnings.some(w => w.type === 'partial_execution'),
+      'Expected partial_execution warning');
+    assert.ok(json.commits.length > 0, 'Expected commits despite partial_execution');
+  });
+});
+
+// ─── Flat layout helpers ─────────────────────────────────────────────────────
+
+/**
+ * Helper: create a flat layout with planning-repo and sibling repos using ../path format.
+ * Returns { rootDir, productRoot } where productRoot is the planning repo cwd.
+ */
+function setupFlatLayout(tmpDir, repoNames) {
+  // Create planning repo (product root)
+  const productRoot = path.join(tmpDir, 'planning-repo');
+  const planningDir = path.join(productRoot, '.planning');
+  fs.mkdirSync(planningDir, { recursive: true });
+
+  let reposMd = '# Repos\n\n';
+  reposMd += '| Name | Path | GitHub URL | Description |\n';
+  reposMd += '|------|------|------------|-------------|\n';
+
+  for (const name of repoNames) {
+    reposMd += `| ${name} | ../${name} | | Test repo |\n`;
+    // Create sibling repos as real git repos
+    initGitRepo(path.join(tmpDir, name));
+    // Add README.md as a tracked file
+    fs.writeFileSync(path.join(tmpDir, name, 'README.md'), '# Repo\n');
+    execSync('git add README.md', { cwd: path.join(tmpDir, name), stdio: 'pipe' });
+    execSync('git commit -m "add readme"', { cwd: path.join(tmpDir, name), stdio: 'pipe' });
+  }
+
+  fs.writeFileSync(path.join(planningDir, 'REPOS.md'), reposMd);
+  return { rootDir: tmpDir, productRoot };
+}
+
+// ─── resolveRepoPath with ../repo paths ──────────────────────────────────────
+
+describe('resolveRepoPath with ../repo paths', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('resolves ../api-service to absolute path of sibling directory', () => {
+    const { productRoot } = setupFlatLayout(tmpDir, ['api-service']);
+    const result = resolveRepoPath(productRoot, 'api-service');
+    assert.ok(result, 'Expected result to be non-null');
+    assert.strictEqual(result.absPath, path.join(tmpDir, 'api-service'));
+    assert.strictEqual(result.repo.name, 'api-service');
+    assert.strictEqual(result.repo.path, '../api-service');
+  });
+
+  it('returns null for unknown repo name', () => {
+    const { productRoot } = setupFlatLayout(tmpDir, ['api-service']);
+    const result = resolveRepoPath(productRoot, 'nonexistent');
+    assert.strictEqual(result, null);
+  });
+
+  it('resolves multiple sibling repos to correct absolute paths', () => {
+    const { productRoot } = setupFlatLayout(tmpDir, ['web-app', 'api-service', 'shared-lib']);
+    const web = resolveRepoPath(productRoot, 'web-app');
+    const api = resolveRepoPath(productRoot, 'api-service');
+    const lib = resolveRepoPath(productRoot, 'shared-lib');
+    assert.strictEqual(web.absPath, path.join(tmpDir, 'web-app'));
+    assert.strictEqual(api.absPath, path.join(tmpDir, 'api-service'));
+    assert.strictEqual(lib.absPath, path.join(tmpDir, 'shared-lib'));
+  });
+
+  it('resolved absPath actually exists on disk', () => {
+    const { productRoot } = setupFlatLayout(tmpDir, ['real-repo']);
+    const result = resolveRepoPath(productRoot, 'real-repo');
+    assert.ok(fs.existsSync(result.absPath), `Expected ${result.absPath} to exist on disk`);
+  });
+});
+
+// ─── multi-repo execution with ../repo paths ────────────────────────────────
+
+describe('multi-repo execution with ../repo paths', () => {
+  let tmpDir;
+  beforeEach(() => { tmpDir = createTempDir(); });
+  afterEach(() => { cleanupDir(tmpDir); });
+
+  it('preflightCheck passes for clean sibling repos', () => {
+    const { productRoot } = setupFlatLayout(tmpDir, ['repo-a', 'repo-b']);
+    const result = preflightCheck(productRoot, ['repo-a', 'repo-b']);
+    assert.strictEqual(result.passed, true);
+    assert.strictEqual(result.dirty_repos.length, 0);
+    assert.strictEqual(result.missing_repos.length, 0);
+  });
+
+  it('preflightCheck detects dirty sibling repo', () => {
+    const { productRoot } = setupFlatLayout(tmpDir, ['repo-a']);
+    // Modify a tracked file in the sibling repo
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'README.md'), '# Modified\n');
+    const result = preflightCheck(productRoot, ['repo-a']);
+    assert.strictEqual(result.passed, false);
+    assert.ok(result.dirty_repos.length > 0);
+    assert.ok(result.dirty_repos.some(d => d.name === 'repo-a'));
+  });
+
+  it('detectRepoChanges finds changes in sibling repos', () => {
+    const { productRoot } = setupFlatLayout(tmpDir, ['repo-a', 'repo-b']);
+    // Create new files in sibling repos
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'new-file.js'), 'console.log("a");\n');
+    const result = detectRepoChanges(productRoot, ['repo-a', 'repo-b']);
+    assert.strictEqual(result.length, 1);
+    assert.strictEqual(result[0].repoName, 'repo-a');
+    assert.ok(result[0].files.some(f => f.includes('new-file.js')));
+  });
+
+  it('commitPerRepo successfully commits in sibling repos', () => {
+    const { productRoot } = setupFlatLayout(tmpDir, ['repo-a']);
+    // Create a new file
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'feature.js'), 'module.exports = {};\n');
+    const repoChanges = [{ repoName: 'repo-a', repoPath: '../repo-a', files: ['feature.js'] }];
+    const options = {
+      type: 'feat',
+      project: 'flat-test',
+      phase: '18',
+      plan: '02',
+      description: 'test sibling commit',
+    };
+    const results = commitPerRepo(productRoot, repoChanges, options);
+    assert.strictEqual(results.length, 1);
+    assert.strictEqual(results[0].repo, 'repo-a');
+    assert.strictEqual(results[0].status, 'complete');
+    assert.ok(results[0].sha);
+    // Verify actual commit in sibling repo
+    const log = execSync('git log --oneline -1', {
+      cwd: path.join(tmpDir, 'repo-a'),
+      encoding: 'utf-8',
+    }).trim();
+    assert.ok(log.includes('feat(flat-test/18-02): test sibling commit'));
+  });
+
+  it('full lifecycle: preflight -> modify -> detect -> commit in flat layout', () => {
+    const { productRoot } = setupFlatLayout(tmpDir, ['repo-a', 'repo-b']);
+    const options = {
+      type: 'feat',
+      project: 'lifecycle',
+      phase: '18',
+      plan: '02',
+      description: 'flat layout lifecycle',
+    };
+
+    // Step 1: preflight clean
+    const pre = preflightCheck(productRoot, ['repo-a', 'repo-b']);
+    assert.strictEqual(pre.passed, true);
+
+    // Step 2: modify files
+    fs.writeFileSync(path.join(tmpDir, 'repo-a', 'a.js'), 'a');
+    fs.writeFileSync(path.join(tmpDir, 'repo-b', 'b.js'), 'b');
+
+    // Step 3: detect changes
+    const changes = detectRepoChanges(productRoot, ['repo-a', 'repo-b']);
+    assert.strictEqual(changes.length, 2);
+
+    // Step 4: commit
+    const results = commitPerRepo(productRoot, changes, options);
+    assert.strictEqual(results.length, 2);
+    assert.ok(results.every(r => r.status === 'complete'));
+    assert.ok(results.every(r => r.sha));
+
+    // Step 5: build planning body
+    const body = buildPlanningCommitBody(results);
+    assert.ok(body.includes('repo-a'));
+    assert.ok(body.includes('repo-b'));
+  });
+});