@ktpartners/dgs-platform 2.6.2

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

@@ -0,0 +1,1271 @@
+/**
+ * Tests for init.cjs v2 project-qualified path resolution
+ *
+ * Uses Node.js built-in test runner (node:test) and assert (node:assert).
+ * Tests invoke dgs-tools.cjs CLI via execSync against isolated temp fixtures
+ * to verify init commands output correct paths in v1 and v2 modes.
+ */
+
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execSync } = require('child_process');
+
+const { createFixture } = require('./test-helpers.cjs');
+
+// Path to CLI entry point
+const CLI = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+
+/**
+ * Run a dgs-tools init command in a fixture directory and return parsed JSON.
+ */
+function runInit(cwd, command) {
+  const stdout = execSync(`node "${CLI}" init ${command}`, {
+    cwd,
+    encoding: 'utf-8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  return JSON.parse(stdout.trim());
+}
+
+// ─── Standard v1 fixture ─────────────────────────────────────────────────────
+
+function v1Fixture() {
+  return createFixture({
+    '.planning/config.json': JSON.stringify({}),
+    '.planning/STATE.md': '# State',
+    '.planning/ROADMAP.md': '# Roadmap\n\n## Phases\n\n- [ ] **Phase 1: Test Phase** - A test\n',
+    '.planning/REQUIREMENTS.md': '# Requirements',
+    '.planning/PROJECT.md': '# Project',
+    '.planning/phases/01-test-phase/01-CONTEXT.md': '# Context',
+    '.planning/phases/01-test-phase/01-01-PLAN.md': '---\nphase: 01-test-phase\nplan: 01\n---\n# Plan',
+  });
+}
+
+// ─── Standard v2 fixture with current project ────────────────────────────────
+
+function v2FixtureWithProject() {
+  return createFixture({
+    '.planning/config.json': JSON.stringify({ current_project: 'test-project' }),
+    '.planning/PROJECTS.md': '# Projects\n\n| Project | Status |\n|---------|--------|\n| test-project | Active |\n',
+    '.planning/REPOS.md': '# Repos\n\n| Name | Path |\n|------|------|\n',
+    '.planning/projects/test-project/STATE.md': '# State',
+    '.planning/projects/test-project/ROADMAP.md': '# Roadmap\n\n## Phases\n\n- [ ] **Phase 1: Test Phase** - A test\n',
+    '.planning/projects/test-project/REQUIREMENTS.md': '# Requirements',
+    '.planning/projects/test-project/PROJECT.md': '# Project',
+    '.planning/projects/test-project/phases/01-test-phase/01-CONTEXT.md': '# Context',
+    '.planning/projects/test-project/phases/01-test-phase/01-01-PLAN.md': '---\nphase: 01-test-phase\nplan: 01\n---\n# Plan',
+  });
+}
+
+// ─── v2 fixture without current_project (for guard tests) ────────────────────
+
+function v2FixtureOneProject() {
+  return createFixture({
+    '.planning/config.json': JSON.stringify({}),
+    '.planning/PROJECTS.md': '# Projects\n\n| Project | Status |\n',
+    '.planning/REPOS.md': '# Repos\n\n| Name | Path |\n',
+    '.planning/projects/test-project/STATE.md': '# State',
+  });
+}
+
+function v2FixtureZeroProjects() {
+  return createFixture({
+    '.planning/config.json': JSON.stringify({}),
+    '.planning/PROJECTS.md': '# Projects\n\n| Project | Status |\n',
+    '.planning/REPOS.md': '# Repos\n\n| Name | Path |\n',
+  });
+}
+
+function v2FixtureMultipleProjects() {
+  return createFixture({
+    '.planning/config.json': JSON.stringify({}),
+    '.planning/PROJECTS.md': '# Projects\n\n| Project | Status |\n',
+    '.planning/REPOS.md': '# Repos\n\n| Name | Path |\n',
+    '.planning/projects/alpha-project/STATE.md': '# State',
+    '.planning/projects/beta-project/STATE.md': '# State',
+  });
+}
+
+// ─── v1 Mode: plan-phase ─────────────────────────────────────────────────────
+
+describe('v1 mode: init plan-phase', () => {
+  let fixture;
+  let result;
+
+  beforeEach(() => {
+    fixture = v1Fixture();
+    result = runInit(fixture.cwd, 'plan-phase 1');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns state_path as .planning/STATE.md', () => {
+    assert.equal(result.state_path, '.planning/STATE.md');
+  });
+
+  it('returns roadmap_path as .planning/ROADMAP.md', () => {
+    assert.equal(result.roadmap_path, '.planning/ROADMAP.md');
+  });
+
+  it('returns requirements_path as .planning/REQUIREMENTS.md', () => {
+    assert.equal(result.requirements_path, '.planning/REQUIREMENTS.md');
+  });
+
+  it('returns dgs_mode v1', () => {
+    assert.equal(result.dgs_mode, 'v1');
+  });
+
+  it('returns current_project null', () => {
+    assert.equal(result.current_project, null);
+  });
+
+  it('returns guard null', () => {
+    assert.equal(result.guard, null);
+  });
+
+  it('returns project_root as .planning', () => {
+    assert.equal(result.project_root, '.planning');
+  });
+
+  it('preserves phase_found', () => {
+    assert.equal(result.phase_found, true);
+  });
+
+  it('preserves phase_number', () => {
+    assert.equal(result.phase_number, '01');
+  });
+});
+
+// ─── v1 Mode: execute-phase ──────────────────────────────────────────────────
+
+describe('v1 mode: init execute-phase', () => {
+  let fixture;
+  let result;
+
+  beforeEach(() => {
+    fixture = v1Fixture();
+    result = runInit(fixture.cwd, 'execute-phase 1');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns state_path as .planning/STATE.md', () => {
+    assert.equal(result.state_path, '.planning/STATE.md');
+  });
+
+  it('returns roadmap_path as .planning/ROADMAP.md', () => {
+    assert.equal(result.roadmap_path, '.planning/ROADMAP.md');
+  });
+
+  it('returns config_path as .planning/dgs.config.json (always product-level)', () => {
+    assert.equal(result.config_path, '.planning/dgs.config.json');
+  });
+
+  it('returns project_path as .planning/PROJECT.md', () => {
+    assert.equal(result.project_path, '.planning/PROJECT.md');
+  });
+
+  it('returns debug_dir as .planning/debug', () => {
+    assert.equal(result.debug_dir, '.planning/debug');
+  });
+
+  it('returns dgs_mode v1', () => {
+    assert.equal(result.dgs_mode, 'v1');
+  });
+
+  it('returns current_project null', () => {
+    assert.equal(result.current_project, null);
+  });
+
+  it('returns base_branch defaulting to main', () => {
+    assert.equal(result.base_branch, 'main');
+  });
+});
+
+// ─── v1 Mode: init new-project ────────────────────────────────────────────────
+
+describe('v1 mode: init new-project', () => {
+  let fixture;
+  let result;
+
+  beforeEach(() => {
+    fixture = v1Fixture();
+    result = runInit(fixture.cwd, 'new-project');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns state_path as .planning/STATE.md', () => {
+    assert.equal(result.state_path, '.planning/STATE.md');
+  });
+
+  it('returns roadmap_path as .planning/ROADMAP.md', () => {
+    assert.equal(result.roadmap_path, '.planning/ROADMAP.md');
+  });
+
+  it('returns requirements_path as .planning/REQUIREMENTS.md', () => {
+    assert.equal(result.requirements_path, '.planning/REQUIREMENTS.md');
+  });
+
+  it('returns research_dir as .planning/research', () => {
+    assert.equal(result.research_dir, '.planning/research');
+  });
+
+  it('returns project_path as .planning/PROJECT.md', () => {
+    assert.equal(result.project_path, '.planning/PROJECT.md');
+  });
+
+  it('returns dgs_mode v1', () => {
+    assert.equal(result.dgs_mode, 'v1');
+  });
+});
+
+// ─── v1 Mode: other init commands ────────────────────────────────────────────
+
+describe('v1 mode: init progress', () => {
+  let fixture;
+  let result;
+
+  beforeEach(() => {
+    fixture = v1Fixture();
+    result = runInit(fixture.cwd, 'progress');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns v1 file paths', () => {
+    assert.equal(result.state_path, '.planning/STATE.md');
+    assert.equal(result.roadmap_path, '.planning/ROADMAP.md');
+    assert.equal(result.project_path, '.planning/PROJECT.md');
+    assert.equal(result.config_path, '.planning/dgs.config.json');
+  });
+
+  it('returns dgs_mode v1', () => {
+    assert.equal(result.dgs_mode, 'v1');
+  });
+});
+
+describe('v1 mode: init todos', () => {
+  let fixture;
+  let result;
+
+  beforeEach(() => {
+    fixture = v1Fixture();
+    result = runInit(fixture.cwd, 'todos');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns v1 pending_dir path', () => {
+    assert.equal(result.pending_dir, '.planning/todos/pending');
+  });
+
+  it('returns v1 completed_dir path', () => {
+    assert.equal(result.completed_dir, '.planning/todos/completed');
+  });
+
+  it('returns dgs_mode v1', () => {
+    assert.equal(result.dgs_mode, 'v1');
+  });
+});
+
+describe('v1 mode: init milestone-op', () => {
+  let fixture;
+  let result;
+
+  beforeEach(() => {
+    fixture = v1Fixture();
+    result = runInit(fixture.cwd, 'milestone-op');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns v1 file paths', () => {
+    assert.equal(result.project_path, '.planning/PROJECT.md');
+    assert.equal(result.roadmap_path, '.planning/ROADMAP.md');
+    assert.equal(result.state_path, '.planning/STATE.md');
+  });
+
+  it('returns dgs_mode v1', () => {
+    assert.equal(result.dgs_mode, 'v1');
+  });
+
+  it('returns base_branch defaulting to main', () => {
+    assert.equal(result.base_branch, 'main');
+  });
+});
+
+describe('v1 mode: init map-codebase', () => {
+  let fixture;
+  let result;
+
+  beforeEach(() => {
+    fixture = v1Fixture();
+    result = runInit(fixture.cwd, 'map-codebase');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('keeps codebase_dir product-level (not project-qualified)', () => {
+    assert.equal(result.codebase_dir, '.planning/codebase');
+  });
+
+  it('returns dgs_mode v1', () => {
+    assert.equal(result.dgs_mode, 'v1');
+  });
+});
+
+// ─── v2 Mode with current_project ────────────────────────────────────────────
+
+describe('v2 mode with project: init plan-phase', () => {
+  let fixture;
+  let result;
+
+  beforeEach(() => {
+    fixture = v2FixtureWithProject();
+    result = runInit(fixture.cwd, 'plan-phase 1');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns project-qualified state_path', () => {
+    assert.equal(result.state_path, path.join('.planning', 'projects', 'test-project', 'STATE.md'));
+  });
+
+  it('returns project-qualified roadmap_path', () => {
+    assert.equal(result.roadmap_path, path.join('.planning', 'projects', 'test-project', 'ROADMAP.md'));
+  });
+
+  it('returns project-qualified requirements_path', () => {
+    assert.equal(result.requirements_path, path.join('.planning', 'projects', 'test-project', 'REQUIREMENTS.md'));
+  });
+
+  it('returns dgs_mode v2', () => {
+    assert.equal(result.dgs_mode, 'v2');
+  });
+
+  it('returns current_project', () => {
+    assert.equal(result.current_project, 'test-project');
+  });
+
+  it('returns project_root', () => {
+    assert.equal(result.project_root, path.join('.planning', 'projects', 'test-project'));
+  });
+
+  it('returns guard null (project is set)', () => {
+    assert.equal(result.guard, null);
+  });
+
+  it('finds phase in project-scoped phases directory', () => {
+    assert.equal(result.phase_found, true);
+    assert.equal(result.phase_number, '01');
+    assert.equal(result.phase_dir, path.join('.planning', 'projects', 'test-project', 'phases', '01-test-phase'));
+  });
+});
+
+describe('v2 mode with project: init execute-phase', () => {
+  let fixture;
+  let result;
+
+  beforeEach(() => {
+    fixture = v2FixtureWithProject();
+    result = runInit(fixture.cwd, 'execute-phase 1');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns project-qualified state_path', () => {
+    assert.equal(result.state_path, path.join('.planning', 'projects', 'test-project', 'STATE.md'));
+  });
+
+  it('returns project-qualified roadmap_path', () => {
+    assert.equal(result.roadmap_path, path.join('.planning', 'projects', 'test-project', 'ROADMAP.md'));
+  });
+
+  it('config_path stays product-level', () => {
+    assert.equal(result.config_path, '.planning/dgs.config.json');
+  });
+
+  it('returns project-qualified project_path', () => {
+    assert.equal(result.project_path, path.join('.planning', 'projects', 'test-project', 'PROJECT.md'));
+  });
+
+  it('returns project-qualified debug_dir', () => {
+    assert.equal(result.debug_dir, path.join('.planning', 'projects', 'test-project', 'debug'));
+  });
+
+  it('returns dgs_mode v2', () => {
+    assert.equal(result.dgs_mode, 'v2');
+  });
+
+  it('finds phase in project-scoped phases directory', () => {
+    assert.equal(result.phase_found, true);
+    assert.equal(result.phase_number, '01');
+    assert.equal(result.phase_dir, path.join('.planning', 'projects', 'test-project', 'phases', '01-test-phase'));
+  });
+});
+
+describe('v2 mode with project: init new-project', () => {
+  let fixture;
+  let result;
+
+  beforeEach(() => {
+    fixture = v2FixtureWithProject();
+    result = runInit(fixture.cwd, 'new-project');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns project-qualified state_path', () => {
+    assert.equal(result.state_path, path.join('.planning', 'projects', 'test-project', 'STATE.md'));
+  });
+
+  it('returns project-qualified roadmap_path', () => {
+    assert.equal(result.roadmap_path, path.join('.planning', 'projects', 'test-project', 'ROADMAP.md'));
+  });
+
+  it('returns project-qualified requirements_path', () => {
+    assert.equal(result.requirements_path, path.join('.planning', 'projects', 'test-project', 'REQUIREMENTS.md'));
+  });
+
+  it('returns project-qualified research_dir', () => {
+    assert.equal(result.research_dir, path.join('.planning', 'projects', 'test-project', 'research'));
+  });
+
+  it('returns project-qualified project_path', () => {
+    assert.equal(result.project_path, path.join('.planning', 'projects', 'test-project', 'PROJECT.md'));
+  });
+
+  it('returns dgs_mode v2', () => {
+    assert.equal(result.dgs_mode, 'v2');
+  });
+});
+
+describe('v2 mode with project: init progress', () => {
+  let fixture;
+  let result;
+
+  beforeEach(() => {
+    fixture = v2FixtureWithProject();
+    result = runInit(fixture.cwd, 'progress');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns project-qualified state_path', () => {
+    assert.equal(result.state_path, path.join('.planning', 'projects', 'test-project', 'STATE.md'));
+  });
+
+  it('config_path stays product-level', () => {
+    assert.equal(result.config_path, '.planning/dgs.config.json');
+  });
+
+  it('phase directory is project-qualified', () => {
+    if (result.phases.length > 0) {
+      assert.ok(result.phases[0].directory.startsWith(path.join('.planning', 'projects', 'test-project', 'phases')));
+    }
+  });
+});
+
+describe('v2 mode with project: init todos', () => {
+  let fixture;
+  let result;
+
+  beforeEach(() => {
+    fixture = v2FixtureWithProject();
+    result = runInit(fixture.cwd, 'todos');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns project-qualified pending_dir', () => {
+    assert.equal(result.pending_dir, path.join('.planning', 'projects', 'test-project', 'todos', 'pending'));
+  });
+
+  it('returns project-qualified completed_dir', () => {
+    assert.equal(result.completed_dir, path.join('.planning', 'projects', 'test-project', 'todos', 'completed'));
+  });
+
+  it('returns dgs_mode v2', () => {
+    assert.equal(result.dgs_mode, 'v2');
+  });
+});
+
+describe('v2 mode with project: init milestone-op', () => {
+  let fixture;
+  let result;
+
+  beforeEach(() => {
+    fixture = v2FixtureWithProject();
+    result = runInit(fixture.cwd, 'milestone-op');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns project-qualified file paths', () => {
+    assert.equal(result.project_path, path.join('.planning', 'projects', 'test-project', 'PROJECT.md'));
+    assert.equal(result.roadmap_path, path.join('.planning', 'projects', 'test-project', 'ROADMAP.md'));
+    assert.equal(result.state_path, path.join('.planning', 'projects', 'test-project', 'STATE.md'));
+  });
+
+  it('returns dgs_mode v2', () => {
+    assert.equal(result.dgs_mode, 'v2');
+  });
+});
+
+describe('v2 mode with project: init map-codebase', () => {
+  let fixture;
+  let result;
+
+  beforeEach(() => {
+    fixture = v2FixtureWithProject();
+    result = runInit(fixture.cwd, 'map-codebase');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('keeps codebase_dir product-level (shared, not project-qualified)', () => {
+    assert.equal(result.codebase_dir, '.planning/codebase');
+  });
+
+  it('returns dgs_mode v2', () => {
+    assert.equal(result.dgs_mode, 'v2');
+  });
+});
+
+// ─── init map-codebase: multi-repo fields ────────────────────────────────────
+
+describe('init map-codebase: multi-repo with valid repos', () => {
+  let fixture;
+  let repoDir;
+
+  beforeEach(() => {
+    // Create a sibling repo directory with .git
+    repoDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-repo-'));
+    fs.mkdirSync(path.join(repoDir, '.git'));
+
+    // Use a fixture with REPOS.md containing the sibling repo via relative path
+    fixture = createFixture({
+      '.planning/config.json': JSON.stringify({}),
+      '.planning/REPOS.md': `# Repos\n\nRegistered repositories for this product. Managed by DGS — manual edits may be overwritten.\n\n| Name | Path | GitHub URL | Description |\n|------|------|------------|-------------|\n| testrepo | ../${path.basename(repoDir)} | | Test repo |\n`,
+      '.planning/STATE.md': '# State',
+      '.planning/ROADMAP.md': '# Roadmap\n\n## Phases\n\n',
+    });
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+    fs.rmSync(repoDir, { recursive: true, force: true });
+  });
+
+  it('returns multi_repo true when repos are registered', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.equal(result.multi_repo, true);
+  });
+
+  it('returns repos array with resolved absolute paths', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.ok(Array.isArray(result.repos));
+    assert.equal(result.repos.length, 1);
+    assert.equal(result.repos[0].name, 'testrepo');
+    assert.ok(path.isAbsolute(result.repos[0].path), 'Repo path should be absolute');
+  });
+
+  it('returns valid_repos array with repo names', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.deepEqual(result.valid_repos, ['testrepo']);
+  });
+
+  it('returns empty existing_repo_maps when no per-repo codebase dirs exist', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.deepEqual(result.existing_repo_maps, {});
+  });
+
+  it('preserves backward-compatible codebase_dir field', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.equal(result.codebase_dir, '.planning/codebase');
+  });
+});
+
+describe('init map-codebase: no repos registered', () => {
+  let fixture;
+
+  beforeEach(() => {
+    fixture = createFixture({
+      '.planning/config.json': JSON.stringify({}),
+      '.planning/STATE.md': '# State',
+      '.planning/ROADMAP.md': '# Roadmap\n\n## Phases\n\n',
+    });
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns multi_repo false when no REPOS.md exists', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.equal(result.multi_repo, false);
+  });
+
+  it('returns empty repos array when no REPOS.md exists', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.deepEqual(result.repos, []);
+  });
+
+  it('returns empty valid_repos when no REPOS.md exists', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.deepEqual(result.valid_repos, []);
+  });
+});
+
+describe('init map-codebase: empty REPOS.md table', () => {
+  let fixture;
+
+  beforeEach(() => {
+    fixture = createFixture({
+      '.planning/config.json': JSON.stringify({}),
+      '.planning/REPOS.md': '# Repos\n\nRegistered repositories.\n\n| Name | Path | GitHub URL | Description |\n|------|------|------------|-------------|\n',
+      '.planning/STATE.md': '# State',
+      '.planning/ROADMAP.md': '# Roadmap\n\n## Phases\n\n',
+    });
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns multi_repo false when REPOS.md has no data rows', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.equal(result.multi_repo, false);
+  });
+
+  it('returns empty repos array when REPOS.md has no data rows', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.deepEqual(result.repos, []);
+  });
+});
+
+describe('init map-codebase: existing per-repo maps detected', () => {
+  let fixture;
+  let repoDir;
+
+  beforeEach(() => {
+    repoDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-repo-'));
+    fs.mkdirSync(path.join(repoDir, '.git'));
+
+    fixture = createFixture({
+      '.planning/config.json': JSON.stringify({}),
+      '.planning/REPOS.md': `# Repos\n\nRegistered repositories.\n\n| Name | Path | GitHub URL | Description |\n|------|------|------------|-------------|\n| myrepo | ../${path.basename(repoDir)} | | My repo |\n`,
+      '.planning/STATE.md': '# State',
+      '.planning/ROADMAP.md': '# Roadmap\n\n## Phases\n\n',
+      '.planning/codebase/myrepo/STACK.md': '# Stack\n',
+      '.planning/codebase/myrepo/ARCHITECTURE.md': '# Architecture\n',
+    });
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+    fs.rmSync(repoDir, { recursive: true, force: true });
+  });
+
+  it('returns existing_repo_maps with md files for repos that have them', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.ok(result.existing_repo_maps.myrepo, 'Should have myrepo entry');
+    assert.ok(result.existing_repo_maps.myrepo.includes('STACK.md'));
+    assert.ok(result.existing_repo_maps.myrepo.includes('ARCHITECTURE.md'));
+    assert.equal(result.existing_repo_maps.myrepo.length, 2);
+  });
+});
+
+describe('init map-codebase: invalid repo paths produce errors', () => {
+  let fixture;
+
+  beforeEach(() => {
+    fixture = createFixture({
+      '.planning/config.json': JSON.stringify({}),
+      '.planning/REPOS.md': '# Repos\n\nRegistered repositories.\n\n| Name | Path | GitHub URL | Description |\n|------|------|------------|-------------|\n| badrepo | ../nonexistent-path-nowhere | | Bad repo |\n',
+      '.planning/STATE.md': '# State',
+      '.planning/ROADMAP.md': '# Roadmap\n\n## Phases\n\n',
+    });
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns multi_repo false when all repos are invalid', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.equal(result.multi_repo, false);
+  });
+
+  it('returns empty repos array when all repos are invalid', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.deepEqual(result.repos, []);
+  });
+
+  it('returns repo_errors with validation messages', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.ok(result.repo_errors.length > 0, 'Should have validation errors');
+  });
+});
+
+// ─── init map-codebase: --only flag ───────────────────────────────────────────
+
+describe('init map-codebase: --only with valid repo name returns only that repo', () => {
+  let fixture;
+  let repoDirA;
+  let repoDirB;
+
+  beforeEach(() => {
+    repoDirA = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-repo-a-'));
+    fs.mkdirSync(path.join(repoDirA, '.git'));
+    repoDirB = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-repo-b-'));
+    fs.mkdirSync(path.join(repoDirB, '.git'));
+
+    fixture = createFixture({
+      '.planning/config.json': JSON.stringify({}),
+      '.planning/REPOS.md': `# Repos\n\nRegistered repositories.\n\n| Name | Path | GitHub URL | Description |\n|------|------|------------|-------------|\n| repo-a | ../${path.basename(repoDirA)} | | Repo A |\n| repo-b | ../${path.basename(repoDirB)} | | Repo B |\n`,
+      '.planning/STATE.md': '# State',
+      '.planning/ROADMAP.md': '# Roadmap\n\n## Phases\n\n',
+    });
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+    fs.rmSync(repoDirA, { recursive: true, force: true });
+    fs.rmSync(repoDirB, { recursive: true, force: true });
+  });
+
+  it('returns only_repo set to the targeted repo', () => {
+    const result = runInit(fixture.cwd, 'map-codebase --only repo-a');
+    assert.equal(result.only_repo, 'repo-a');
+  });
+
+  it('returns mode as update', () => {
+    const result = runInit(fixture.cwd, 'map-codebase --only repo-a');
+    assert.equal(result.mode, 'update');
+  });
+
+  it('returns valid_repos with only the targeted repo', () => {
+    const result = runInit(fixture.cwd, 'map-codebase --only repo-a');
+    assert.equal(result.valid_repos.length, 1);
+    assert.equal(result.valid_repos[0], 'repo-a');
+  });
+
+  it('returns repos array with only the targeted repo', () => {
+    const result = runInit(fixture.cwd, 'map-codebase --only repo-a');
+    assert.equal(result.repos.length, 1);
+    assert.equal(result.repos[0].name, 'repo-a');
+  });
+});
+
+describe('init map-codebase: --only with invalid repo name throws error', () => {
+  let fixture;
+  let repoDirA;
+
+  beforeEach(() => {
+    repoDirA = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-repo-a-'));
+    fs.mkdirSync(path.join(repoDirA, '.git'));
+
+    fixture = createFixture({
+      '.planning/config.json': JSON.stringify({}),
+      '.planning/REPOS.md': `# Repos\n\nRegistered repositories.\n\n| Name | Path | GitHub URL | Description |\n|------|------|------------|-------------|\n| repo-a | ../${path.basename(repoDirA)} | | Repo A |\n`,
+      '.planning/STATE.md': '# State',
+      '.planning/ROADMAP.md': '# Roadmap\n\n## Phases\n\n',
+    });
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+    fs.rmSync(repoDirA, { recursive: true, force: true });
+  });
+
+  it('errors with message containing the invalid name', () => {
+    assert.throws(() => {
+      runInit(fixture.cwd, 'map-codebase --only nonexistent');
+    }, (err) => {
+      assert.ok(err.stderr.includes("'nonexistent' not found in REPOS.md"), 'Should mention invalid repo name');
+      return true;
+    });
+  });
+
+  it('error message includes available repo names', () => {
+    assert.throws(() => {
+      runInit(fixture.cwd, 'map-codebase --only nonexistent');
+    }, (err) => {
+      assert.ok(err.stderr.includes('repo-a'), 'Should list available repos');
+      return true;
+    });
+  });
+});
+
+describe('init map-codebase: without --only returns refresh mode', () => {
+  let fixture;
+  let repoDirA;
+  let repoDirB;
+
+  beforeEach(() => {
+    repoDirA = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-repo-a-'));
+    fs.mkdirSync(path.join(repoDirA, '.git'));
+    repoDirB = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-repo-b-'));
+    fs.mkdirSync(path.join(repoDirB, '.git'));
+
+    fixture = createFixture({
+      '.planning/config.json': JSON.stringify({}),
+      '.planning/REPOS.md': `# Repos\n\nRegistered repositories.\n\n| Name | Path | GitHub URL | Description |\n|------|------|------------|-------------|\n| repo-a | ../${path.basename(repoDirA)} | | Repo A |\n| repo-b | ../${path.basename(repoDirB)} | | Repo B |\n`,
+      '.planning/STATE.md': '# State',
+      '.planning/ROADMAP.md': '# Roadmap\n\n## Phases\n\n',
+    });
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+    fs.rmSync(repoDirA, { recursive: true, force: true });
+    fs.rmSync(repoDirB, { recursive: true, force: true });
+  });
+
+  it('returns only_repo as null', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.equal(result.only_repo, null);
+  });
+
+  it('returns mode as refresh', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.equal(result.mode, 'refresh');
+  });
+
+  it('returns all valid repos', () => {
+    const result = runInit(fixture.cwd, 'map-codebase');
+    assert.equal(result.valid_repos.length, 2);
+    assert.ok(result.valid_repos.includes('repo-a'));
+    assert.ok(result.valid_repos.includes('repo-b'));
+  });
+});
+
+describe('init map-codebase: --only without repo name argument throws error', () => {
+  let fixture;
+  let repoDirA;
+
+  beforeEach(() => {
+    repoDirA = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-repo-a-'));
+    fs.mkdirSync(path.join(repoDirA, '.git'));
+
+    fixture = createFixture({
+      '.planning/config.json': JSON.stringify({}),
+      '.planning/REPOS.md': `# Repos\n\nRegistered repositories.\n\n| Name | Path | GitHub URL | Description |\n|------|------|------------|-------------|\n| repo-a | ../${path.basename(repoDirA)} | | Repo A |\n`,
+      '.planning/STATE.md': '# State',
+      '.planning/ROADMAP.md': '# Roadmap\n\n## Phases\n\n',
+    });
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+    fs.rmSync(repoDirA, { recursive: true, force: true });
+  });
+
+  it('errors when --only is provided without a following argument', () => {
+    assert.throws(() => {
+      runInit(fixture.cwd, 'map-codebase --only');
+    }, (err) => {
+      assert.ok(err.stderr.includes('--only requires a repo name'), 'Should mention missing argument');
+      return true;
+    });
+  });
+});
+
+// ─── init map-codebase: positional argument (shorthand for --only) ─────────
+//
+// Positional argument parsing happens in dgs-tools.cjs: when the first
+// non-flag argument after "map-codebase" is not prefixed with "--", it is
+// treated as a repo name and passed to cmdInitMapCodebase as onlyRepo.
+// This converges with the --only flag path at the same function call, so
+// the existing --only tests above also validate the downstream behavior
+// of cmdInitMapCodebase when a repo name is supplied.
+
+describe('init map-codebase: positional argument with valid repo name', () => {
+  let fixture;
+  let repoDirA;
+  let repoDirB;
+
+  beforeEach(() => {
+    repoDirA = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-repo-a-'));
+    fs.mkdirSync(path.join(repoDirA, '.git'));
+    repoDirB = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-repo-b-'));
+    fs.mkdirSync(path.join(repoDirB, '.git'));
+
+    fixture = createFixture({
+      '.planning/config.json': JSON.stringify({}),
+      '.planning/REPOS.md': `# Repos\n\nRegistered repositories.\n\n| Name | Path | GitHub URL | Description |\n|------|------|------------|-------------|\n| repo-a | ../${path.basename(repoDirA)} | | Repo A |\n| repo-b | ../${path.basename(repoDirB)} | | Repo B |\n`,
+      '.planning/STATE.md': '# State',
+      '.planning/ROADMAP.md': '# Roadmap\n\n## Phases\n\n',
+    });
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+    fs.rmSync(repoDirA, { recursive: true, force: true });
+    fs.rmSync(repoDirB, { recursive: true, force: true });
+  });
+
+  it('returns only_repo set to the positional repo name', () => {
+    // Positional: "map-codebase repo-a" instead of "map-codebase --only repo-a"
+    const result = runInit(fixture.cwd, 'map-codebase repo-a');
+    assert.equal(result.only_repo, 'repo-a');
+  });
+
+  it('returns mode as update (same as --only)', () => {
+    const result = runInit(fixture.cwd, 'map-codebase repo-a');
+    assert.equal(result.mode, 'update');
+  });
+
+  it('returns valid_repos with only the targeted repo', () => {
+    const result = runInit(fixture.cwd, 'map-codebase repo-a');
+    assert.equal(result.valid_repos.length, 1);
+    assert.equal(result.valid_repos[0], 'repo-a');
+  });
+
+  it('produces identical output to --only flag', () => {
+    const positional = runInit(fixture.cwd, 'map-codebase repo-a');
+    const flagged = runInit(fixture.cwd, 'map-codebase --only repo-a');
+    assert.equal(positional.only_repo, flagged.only_repo);
+    assert.equal(positional.mode, flagged.mode);
+    assert.deepEqual(positional.valid_repos, flagged.valid_repos);
+  });
+});
+
+describe('init map-codebase: positional argument with invalid repo name', () => {
+  let fixture;
+  let repoDirA;
+
+  beforeEach(() => {
+    repoDirA = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-repo-a-'));
+    fs.mkdirSync(path.join(repoDirA, '.git'));
+
+    fixture = createFixture({
+      '.planning/config.json': JSON.stringify({}),
+      '.planning/REPOS.md': `# Repos\n\nRegistered repositories.\n\n| Name | Path | GitHub URL | Description |\n|------|------|------------|-------------|\n| repo-a | ../${path.basename(repoDirA)} | | Repo A |\n`,
+      '.planning/STATE.md': '# State',
+      '.planning/ROADMAP.md': '# Roadmap\n\n## Phases\n\n',
+    });
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+    fs.rmSync(repoDirA, { recursive: true, force: true });
+  });
+
+  it('errors with message listing valid repos when positional name is invalid', () => {
+    assert.throws(() => {
+      runInit(fixture.cwd, 'map-codebase nonexistent');
+    }, (err) => {
+      assert.ok(err.stderr.includes("'nonexistent' not found in REPOS.md"), 'Should mention invalid repo name');
+      assert.ok(err.stderr.includes('repo-a'), 'Should list available repos');
+      return true;
+    });
+  });
+});
+
+describe('init map-codebase: argument starting with -- is not treated as positional repo name', () => {
+  let fixture;
+  let repoDirA;
+
+  beforeEach(() => {
+    repoDirA = fs.mkdtempSync(path.join(os.tmpdir(), 'dgs-repo-a-'));
+    fs.mkdirSync(path.join(repoDirA, '.git'));
+
+    fixture = createFixture({
+      '.planning/config.json': JSON.stringify({}),
+      '.planning/REPOS.md': `# Repos\n\nRegistered repositories.\n\n| Name | Path | GitHub URL | Description |\n|------|------|------------|-------------|\n| repo-a | ../${path.basename(repoDirA)} | | Repo A |\n`,
+      '.planning/STATE.md': '# State',
+      '.planning/ROADMAP.md': '# Roadmap\n\n## Phases\n\n',
+    });
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+    fs.rmSync(repoDirA, { recursive: true, force: true });
+  });
+
+  it('treats --raw as a flag, not a repo name (refresh mode)', () => {
+    const result = runInit(fixture.cwd, 'map-codebase --raw');
+    // --raw is not a repo name, so onlyRepo stays null -> refresh mode
+    assert.equal(result.only_repo, null);
+    assert.equal(result.mode, 'refresh');
+  });
+});
+
+// ─── v2 Guard Tests ──────────────────────────────────────────────────────────
+
+describe('v2 guard: one project, no current_project (auto-select)', () => {
+  let fixture;
+  let result;
+
+  beforeEach(() => {
+    fixture = v2FixtureOneProject();
+    result = runInit(fixture.cwd, 'progress');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('guard action is auto_selected', () => {
+    assert.ok(result.guard);
+    assert.equal(result.guard.action, 'auto_selected');
+  });
+
+  it('guard includes the auto-selected project name', () => {
+    assert.equal(result.guard.project, 'test-project');
+  });
+
+  it('current_project is set to the auto-selected project', () => {
+    assert.equal(result.current_project, 'test-project');
+  });
+
+  it('project_root is set to the auto-selected project root', () => {
+    assert.equal(result.project_root, path.join('.planning', 'projects', 'test-project'));
+  });
+
+  it('dgs_mode is v2', () => {
+    assert.equal(result.dgs_mode, 'v2');
+  });
+});
+
+describe('v2 guard: zero projects (create guidance)', () => {
+  let fixture;
+  let result;
+
+  beforeEach(() => {
+    fixture = v2FixtureZeroProjects();
+    result = runInit(fixture.cwd, 'progress');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('guard action is create', () => {
+    assert.ok(result.guard);
+    assert.equal(result.guard.action, 'create');
+  });
+
+  it('guard message mentions /dgs:new-project', () => {
+    assert.ok(result.guard.message.includes('/dgs:new-project'));
+  });
+
+  it('project_root is null', () => {
+    assert.equal(result.project_root, null);
+  });
+
+  it('dgs_mode is v2', () => {
+    assert.equal(result.dgs_mode, 'v2');
+  });
+});
+
+describe('v2 guard: multiple projects (prompt)', () => {
+  let fixture;
+  let result;
+
+  beforeEach(() => {
+    fixture = v2FixtureMultipleProjects();
+    result = runInit(fixture.cwd, 'progress');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('guard action is prompt', () => {
+    assert.ok(result.guard);
+    assert.equal(result.guard.action, 'prompt');
+  });
+
+  it('guard includes project list', () => {
+    assert.ok(Array.isArray(result.guard.projects));
+    assert.equal(result.guard.projects.length, 2);
+    assert.ok(result.guard.projects.includes('alpha-project'));
+    assert.ok(result.guard.projects.includes('beta-project'));
+  });
+
+  it('project_root is null (no project selected)', () => {
+    assert.equal(result.project_root, null);
+  });
+
+  it('current_project is null', () => {
+    assert.equal(result.current_project, null);
+  });
+
+  it('dgs_mode is v2', () => {
+    assert.equal(result.dgs_mode, 'v2');
+  });
+});
+
+// ─── branch_name with {project} resolution ──────────────────────────────────
+
+describe('branch_name with {project} resolution', () => {
+  it('v1 execute-phase branch_name resolves {project} from current_project', () => {
+    const fixture = createFixture({
+      '.planning/config.json': JSON.stringify({ current_project: 'myapp', git: { branching_strategy: 'phase' } }),
+      '.planning/STATE.md': '# State',
+      '.planning/ROADMAP.md': '# Roadmap\n\n## Phases\n\n- [ ] **Phase 3: Auth** - Auth\n',
+      '.planning/REQUIREMENTS.md': '# Requirements',
+      '.planning/PROJECT.md': '# Project',
+      '.planning/phases/03-auth/03-01-PLAN.md': '---\nphase: 03-auth\nplan: 01\n---\n# Plan',
+    });
+    try {
+      const result = runInit(fixture.cwd, 'execute-phase 3');
+      assert.equal(result.branch_name, 'dgs/myapp/phase-03-auth');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('v2 execute-phase branch_name resolves {project} from current_project', () => {
+    const fixture = createFixture({
+      '.planning/config.json': JSON.stringify({ current_project: 'checkout', git: { branching_strategy: 'phase' } }),
+      '.planning/PROJECTS.md': '# Projects\n\n| Project | Status |\n|---------|--------|\n| checkout | Active |\n',
+      '.planning/REPOS.md': '# Repos\n\n| Name | Path |\n|------|------|\n',
+      '.planning/projects/checkout/STATE.md': '# State',
+      '.planning/projects/checkout/ROADMAP.md': '# Roadmap\n\n## Phases\n\n- [ ] **Phase 1: Init** - Init\n',
+      '.planning/projects/checkout/REQUIREMENTS.md': '# Requirements',
+      '.planning/projects/checkout/PROJECT.md': '# Project',
+      '.planning/projects/checkout/phases/01-init/01-01-PLAN.md': '---\nphase: 01-init\nplan: 01\n---\n# Plan',
+    });
+    try {
+      const result = runInit(fixture.cwd, 'execute-phase 1');
+      assert.equal(result.branch_name, 'dgs/checkout/phase-01-init');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('branch_name with custom template without {project} is unchanged', () => {
+    const fixture = createFixture({
+      '.planning/config.json': JSON.stringify({
+        current_project: 'myapp',
+        git: { branching_strategy: 'phase', phase_branch_template: 'feature/phase-{phase}-{slug}' }
+      }),
+      '.planning/STATE.md': '# State',
+      '.planning/ROADMAP.md': '# Roadmap\n\n## Phases\n\n- [ ] **Phase 3: Auth** - Auth\n',
+      '.planning/REQUIREMENTS.md': '# Requirements',
+      '.planning/PROJECT.md': '# Project',
+      '.planning/phases/03-auth/03-01-PLAN.md': '---\nphase: 03-auth\nplan: 01\n---\n# Plan',
+    });
+    try {
+      const result = runInit(fixture.cwd, 'execute-phase 3');
+      assert.equal(result.branch_name, 'feature/phase-03-auth');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+
+  it('branch_name errors when {project} in template but current_project is null', () => {
+    const fixture = createFixture({
+      '.planning/config.json': JSON.stringify({ git: { branching_strategy: 'phase' } }),
+      '.planning/STATE.md': '# State',
+      '.planning/ROADMAP.md': '# Roadmap\n\n## Phases\n\n- [ ] **Phase 3: Auth** - Auth\n',
+      '.planning/REQUIREMENTS.md': '# Requirements',
+      '.planning/PROJECT.md': '# Project',
+      '.planning/phases/03-auth/03-01-PLAN.md': '---\nphase: 03-auth\nplan: 01\n---\n# Plan',
+    });
+    try {
+      const result = runInit(fixture.cwd, 'execute-phase 3');
+      assert.equal(result.branch_name, 'current_project not set. Run /dgs:settings to configure.');
+    } finally {
+      fixture.cleanup();
+    }
+  });
+});
+
+// ─── Backward Compatibility ──────────────────────────────────────────────────
+
+describe('backward compatibility: v1 output is superset of old shape', () => {
+  let fixture;
+
+  beforeEach(() => {
+    fixture = v1Fixture();
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('plan-phase output includes all pre-v2 fields', () => {
+    const result = runInit(fixture.cwd, 'plan-phase 1');
+    // Pre-v2 fields that must still exist
+    assert.ok('researcher_model' in result);
+    assert.ok('planner_model' in result);
+    assert.ok('checker_model' in result);
+    assert.ok('research_enabled' in result);
+    assert.ok('plan_checker_enabled' in result);
+    assert.ok('phase_found' in result);
+    assert.ok('phase_dir' in result);
+    assert.ok('phase_number' in result);
+    assert.ok('planning_exists' in result);
+    assert.ok('roadmap_exists' in result);
+    assert.ok('state_path' in result);
+    assert.ok('roadmap_path' in result);
+    // New v2 fields that are additive
+    assert.ok('dgs_mode' in result);
+    assert.ok('current_project' in result);
+    assert.ok('project_root' in result);
+    assert.ok('guard' in result);
+  });
+
+  it('execute-phase output includes all pre-v2 fields', () => {
+    const result = runInit(fixture.cwd, 'execute-phase 1');
+    assert.ok('executor_model' in result);
+    assert.ok('verifier_model' in result);
+    assert.ok('phase_found' in result);
+    assert.ok('plans' in result);
+    assert.ok('summaries' in result);
+    assert.ok('state_exists' in result);
+    assert.ok('roadmap_exists' in result);
+    assert.ok('state_path' in result);
+    assert.ok('config_path' in result);
+    assert.ok('dgs_mode' in result);
+    assert.ok('current_project' in result);
+  });
+
+  it('progress output includes all pre-v2 fields', () => {
+    const result = runInit(fixture.cwd, 'progress');
+    assert.ok('phases' in result);
+    assert.ok('phase_count' in result);
+    assert.ok('completed_count' in result);
+    assert.ok('state_path' in result);
+    assert.ok('roadmap_path' in result);
+    assert.ok('config_path' in result);
+    assert.ok('dgs_mode' in result);
+  });
+});