@ktpartners/dgs-platform 2.8.0 → 3.0.4

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

@@ -0,0 +1,596 @@
+/**
+ * Tests for quick.cjs -- Quick workflow lifecycle
+ *
+ * Uses real git repos in temp directories, following the same pattern as worktrees.test.cjs.
+ * Functions that call output()/process.exit() are tested via subprocess (dgs-tools.cjs CLI).
+ * Pure functions (detectQuickMode, getActiveQuick, etc.) are tested directly with
+ * config.local.json manipulation.
+ */
+
+'use strict';
+
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { resetPaths, initPaths } = require('./paths.cjs');
+
+const DGS_TOOLS = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+
+// ─── Test Helpers ────────────────────────────────────────────────────────────
+
+const GIT_ENV = {
+  GIT_AUTHOR_NAME: 'Test',
+  GIT_AUTHOR_EMAIL: 'test@test.com',
+  GIT_COMMITTER_NAME: 'Test',
+  GIT_COMMITTER_EMAIL: 'test@test.com',
+};
+
+/**
+ * Create a minimal DGS environment for quick workflow tests.
+ */
+function createTestEnv() {
+  const tmpDir = fs.realpathSync(fs.mkdtempSync(path.join(require('os').tmpdir(), 'dgs-quick-')));
+  const planDir = path.join(tmpDir, 'planning');
+  const codeDir = path.join(tmpDir, 'code-repo');
+
+  // Create planning root (git repo)
+  fs.mkdirSync(planDir, { recursive: true });
+  execSync('git init -b main', { cwd: planDir, stdio: 'pipe', env: { ...process.env, ...GIT_ENV } });
+  execSync('git config user.email "test@test.com"', { cwd: planDir, stdio: 'pipe' });
+  execSync('git config user.name "Test"', { cwd: planDir, stdio: 'pipe' });
+
+  // Create code repo (git repo on main branch)
+  fs.mkdirSync(codeDir, { recursive: true });
+  execSync('git init -b main', { cwd: codeDir, stdio: 'pipe', env: { ...process.env, ...GIT_ENV } });
+  execSync('git config user.email "test@test.com"', { cwd: codeDir, stdio: 'pipe' });
+  execSync('git config user.name "Test"', { cwd: codeDir, stdio: 'pipe' });
+  fs.writeFileSync(path.join(codeDir, '.gitkeep'), '');
+  execSync('git add .', { cwd: codeDir, stdio: 'pipe' });
+  execSync('git commit -m "initial"', { cwd: codeDir, stdio: 'pipe', env: { ...process.env, ...GIT_ENV } });
+
+  // DGS config files
+  fs.writeFileSync(path.join(planDir, 'config.json'), JSON.stringify({
+    git: { base_branch: 'main' },
+  }, null, 2));
+
+  fs.writeFileSync(path.join(planDir, 'config.local.json'), JSON.stringify({
+    current_project: 'tp',
+  }, null, 2));
+
+  // v2 markers
+  fs.writeFileSync(path.join(planDir, 'PROJECTS.md'), '# Projects\n');
+  fs.writeFileSync(path.join(planDir, 'REPOS.md'),
+    '# Repos\n\n' +
+    '| Name | Path | GitHub URL | Description |\n' +
+    '|------|------|------------|-------------|\n' +
+    '| code-repo | ' + path.relative(planDir, codeDir) + ' |  | Test repo |\n'
+  );
+
+  // Project structure
+  fs.mkdirSync(path.join(planDir, 'projects', 'tp'), { recursive: true });
+  fs.writeFileSync(path.join(planDir, 'projects', 'tp', 'STATE.md'), '# State\nStatus: planning\n');
+
+  // Commit planning files
+  execSync('git add .', { cwd: planDir, stdio: 'pipe' });
+  execSync('git commit -m "setup"', { cwd: planDir, stdio: 'pipe', env: { ...process.env, ...GIT_ENV } });
+
+  initPaths(planDir);
+
+  return {
+    tmpDir,
+    planDir,
+    codeDir,
+    cleanup: function() {
+      resetPaths();
+      // Clean up sibling worktree directories
+      try {
+        const parent = path.dirname(codeDir);
+        const entries = fs.readdirSync(parent);
+        for (const e of entries) {
+          if (e.startsWith('code-repo--')) {
+            fs.rmSync(path.join(parent, e), { recursive: true, force: true });
+          }
+        }
+      } catch { /* ignore */ }
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    },
+  };
+}
+
+/**
+ * Read config.local.json from planning dir.
+ */
+function readLocalConfig(planDir) {
+  return JSON.parse(fs.readFileSync(path.join(planDir, 'config.local.json'), 'utf-8'));
+}
+
+/**
+ * Write config.local.json to planning dir.
+ */
+function writeLocalConfig(planDir, data) {
+  fs.writeFileSync(path.join(planDir, 'config.local.json'), JSON.stringify(data, null, 2) + '\n');
+}
+
+/**
+ * Run dgs-tools command and return parsed JSON output.
+ */
+function runCmd(cwd, args) {
+  const result = execSync(
+    'node ' + JSON.stringify(DGS_TOOLS) + ' ' + args,
+    { cwd, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8', env: { ...process.env, ...GIT_ENV } }
+  );
+  return JSON.parse(result.trim());
+}
+
+// ─── detectQuickMode ─────────────────────────────────────────────────────────
+
+describe('detectQuickMode', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('returns product mode when no active_context set', () => {
+    const { detectQuickMode } = require('./quick.cjs');
+    const result = detectQuickMode(env.planDir, false);
+    assert.equal(result.mode, 'product');
+  });
+
+  it('returns product mode when forceMain is true regardless of active milestone', () => {
+    // Set up an active milestone worktree entry
+    const config = readLocalConfig(env.planDir);
+    config.projects = { tp: { worktrees: { 'v1-0': { type: 'milestone', repos: {} } } } };
+    config.execution = { active_context: 'v1-0' };
+    writeLocalConfig(env.planDir, config);
+
+    const { detectQuickMode } = require('./quick.cjs');
+    const result = detectQuickMode(env.planDir, true);
+    assert.equal(result.mode, 'product');
+  });
+
+  it('returns milestone-context when active_context points to milestone worktree', () => {
+    const config = readLocalConfig(env.planDir);
+    config.projects = { tp: { worktrees: { 'v1-0': { type: 'milestone', repos: {} } } } };
+    config.execution = { active_context: 'v1-0' };
+    writeLocalConfig(env.planDir, config);
+
+    const { detectQuickMode } = require('./quick.cjs');
+    const result = detectQuickMode(env.planDir, false);
+    assert.equal(result.mode, 'milestone-context');
+    assert.equal(result.activeSlug, 'v1-0');
+    assert.equal(result.activeMilestone, 'v1-0');
+  });
+
+  it('returns product mode when active_context points to a quick worktree', () => {
+    // Create a real quick worktree directory so it's not auto-cleared
+    const wtPath = path.join(env.tmpDir, 'code-repo--tp-fix-bug');
+    fs.mkdirSync(wtPath, { recursive: true });
+
+    const config = readLocalConfig(env.planDir);
+    config.projects = { tp: { worktrees: { 'fix-bug': { type: 'quick', repos: { 'code-repo': wtPath } } } } };
+    config.execution = { active_context: 'fix-bug' };
+    writeLocalConfig(env.planDir, config);
+
+    const { detectQuickMode } = require('./quick.cjs');
+    const result = detectQuickMode(env.planDir, false);
+    assert.equal(result.mode, 'product');
+  });
+});
+
+// ─── getActiveQuick ──────────────────────────────────────────────────────────
+
+describe('getActiveQuick', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('returns null when no worktrees tracked', () => {
+    const { getActiveQuick } = require('./quick.cjs');
+    const result = getActiveQuick(env.planDir);
+    assert.equal(result, null);
+  });
+
+  it('returns null when only milestone worktrees exist', () => {
+    const config = readLocalConfig(env.planDir);
+    config.projects = { tp: { worktrees: { 'v1-0': { type: 'milestone', repos: {} } } } };
+    writeLocalConfig(env.planDir, config);
+
+    const { getActiveQuick } = require('./quick.cjs');
+    const result = getActiveQuick(env.planDir);
+    assert.equal(result, null);
+  });
+
+  it('returns the active quick entry when directory exists', () => {
+    // Create a real directory for the quick worktree
+    const wtPath = path.join(env.tmpDir, 'code-repo--tp-fix-bug');
+    fs.mkdirSync(wtPath, { recursive: true });
+
+    const config = readLocalConfig(env.planDir);
+    config.projects = { tp: { worktrees: { 'fix-bug': { type: 'quick', repos: { 'code-repo': wtPath } } } } };
+    writeLocalConfig(env.planDir, config);
+
+    const { getActiveQuick } = require('./quick.cjs');
+    const result = getActiveQuick(env.planDir);
+    assert.ok(result);
+    assert.equal(result.slug, 'fix-bug');
+    assert.equal(result.entry.type, 'quick');
+  });
+
+  it('auto-clears stale entries where directory is missing', () => {
+    const config = readLocalConfig(env.planDir);
+    config.projects = { tp: { worktrees: { 'stale-fix': { type: 'quick', repos: { 'code-repo': '/nonexistent/path' } } } } };
+    config.execution = { active_context: 'stale-fix' };
+    writeLocalConfig(env.planDir, config);
+
+    const { getActiveQuick } = require('./quick.cjs');
+    const result = getActiveQuick(env.planDir);
+    assert.equal(result, null);
+
+    // Verify the stale entry was removed from config
+    const updatedConfig = readLocalConfig(env.planDir);
+    const worktrees = updatedConfig.projects && updatedConfig.projects.tp
+      && updatedConfig.projects.tp.worktrees;
+    assert.ok(!worktrees || !worktrees['stale-fix'], 'Stale entry should be removed');
+
+    // Verify active_context was cleared
+    assert.ok(!updatedConfig.execution || !updatedConfig.execution.active_context,
+      'active_context should be cleared for stale quick');
+  });
+});
+
+// ─── startProductQuick ───────────────────────────────────────────────────────
+
+describe('startProductQuick', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('returns guard error when active product-level quick exists', () => {
+    // Create a real directory for the quick worktree
+    const wtPath = path.join(env.tmpDir, 'code-repo--tp-existing');
+    fs.mkdirSync(wtPath, { recursive: true });
+
+    const config = readLocalConfig(env.planDir);
+    config.projects = { tp: { worktrees: { 'existing': { type: 'quick', repos: { 'code-repo': wtPath } } } } };
+    writeLocalConfig(env.planDir, config);
+
+    const { startProductQuick } = require('./quick.cjs');
+    const result = startProductQuick(env.planDir, 'new task', null);
+    assert.equal(result.success, false);
+    assert.ok(result.error.includes('Quick worktree already active'));
+    assert.equal(result.activeSlug, 'existing');
+  });
+
+  it('creates quick worktree when no active quick exists', () => {
+    const { startProductQuick } = require('./quick.cjs');
+    const result = startProductQuick(env.planDir, 'fix token bug', null);
+    assert.equal(result.success, true);
+    assert.equal(result.slug, 'fix-token-bug');
+
+    // Verify active_context was set
+    const config = readLocalConfig(env.planDir);
+    assert.equal(config.execution.active_context, 'fix-token-bug');
+
+    // Verify worktree entry exists
+    const entry = config.projects.tp.worktrees['fix-token-bug'];
+    assert.ok(entry, 'Worktree entry should exist');
+    assert.equal(entry.type, 'quick');
+  });
+});
+
+// ─── quickComplete ───────────────────────────────────────────────────────────
+
+describe('quickComplete', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('returns error when no active quick', () => {
+    const { quickComplete } = require('./quick.cjs');
+    const result = quickComplete(env.planDir);
+    assert.equal(result.success, false);
+    assert.ok(result.error.includes('No active product-level quick'));
+  });
+});
+
+// ─── quickAbandon ────────────────────────────────────────────────────────────
+
+describe('quickAbandon', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('returns error when confirmed is false', () => {
+    const { quickAbandon } = require('./quick.cjs');
+    const result = quickAbandon(env.planDir, false);
+    assert.equal(result.success, false);
+    assert.ok(result.error.includes('Abandon not confirmed'));
+  });
+
+  it('returns error when no active quick', () => {
+    const { quickAbandon } = require('./quick.cjs');
+    const result = quickAbandon(env.planDir, true);
+    assert.equal(result.success, false);
+    assert.ok(result.error.includes('No active product-level quick'));
+  });
+});
+
+// ─── CLI routing ─────────────────────────────────────────────────────────────
+
+describe('CLI complete-quick routing', () => {
+  let env;
+  beforeEach(() => { env = createTestEnv(); });
+  afterEach(() => { env.cleanup(); });
+
+  it('abandon-quick --confirmed returns error when no active quick', () => {
+    try {
+      runCmd(env.planDir, 'abandon-quick --confirmed');
+      assert.fail('Should have thrown');
+    } catch (err) {
+      assert.ok(err.stderr.includes('No active product-level quick'));
+    }
+  });
+});
+
+// ─── cmdQuickFinalize ────────────────────────────────────────────────────────
+
+/**
+ * Create a minimal git repo with DGS config + quick task directory structure.
+ * Returns {repoDir, quickDir, taskDir, statePath} with task artifacts NOT yet written.
+ */
+function createFinalizeEnv(opts) {
+  opts = opts || {};
+  const commitDocs = opts.commitDocs !== false;
+  const tmpDir = fs.realpathSync(fs.mkdtempSync(path.join(require('os').tmpdir(), 'dgs-qf-')));
+  const repoDir = tmpDir; // single-repo layout — planning root == repo
+  const quickDir = path.join(repoDir, 'quick');
+  const quickId = opts.quickId || '260405-abc';
+  const taskDir = path.join(quickDir, quickId + '-test-task');
+  const statePath = path.join(repoDir, 'projects', 'tp', 'STATE.md');
+
+  execSync('git init -b main', { cwd: repoDir, stdio: 'pipe', env: { ...process.env, ...GIT_ENV } });
+  execSync('git config user.email "test@test.com"', { cwd: repoDir, stdio: 'pipe' });
+  execSync('git config user.name "Test"', { cwd: repoDir, stdio: 'pipe' });
+
+  fs.mkdirSync(quickDir, { recursive: true });
+  if (!opts.skipTaskDir) {
+    fs.mkdirSync(taskDir, { recursive: true });
+  }
+  fs.mkdirSync(path.dirname(statePath), { recursive: true });
+
+  // DGS config
+  fs.writeFileSync(
+    path.join(repoDir, 'config.json'),
+    JSON.stringify({ commit_docs: commitDocs }, null, 2)
+  );
+  // Pre-seed config.local.json with migration marker so migrateBranchingConfig
+  // doesn't write an untracked file during dispatcher startup (which would
+  // otherwise interfere with nothing-to-commit detection).
+  fs.writeFileSync(
+    path.join(repoDir, 'config.local.json'),
+    JSON.stringify({ branching_migration_done: true }, null, 2)
+  );
+  // Create an initial commit so HEAD exists
+  fs.writeFileSync(path.join(repoDir, '.gitkeep'), '');
+  execSync('git add .gitkeep config.json config.local.json', { cwd: repoDir, stdio: 'pipe' });
+  execSync('git commit -m "initial"', { cwd: repoDir, stdio: 'pipe', env: { ...process.env, ...GIT_ENV } });
+
+  return {
+    tmpDir, repoDir, quickDir, taskDir, statePath, quickId,
+    cleanup: function() { fs.rmSync(tmpDir, { recursive: true, force: true }); },
+  };
+}
+
+/**
+ * Run `dgs-tools quick finalize` as a subprocess and return { stdout, stderr, exitCode, parsed }.
+ * Does NOT throw on non-zero exit.
+ */
+function runFinalize(cwd, argsArr) {
+  const { spawnSync } = require('child_process');
+  const res = spawnSync(
+    'node',
+    [DGS_TOOLS, 'quick', 'finalize', ...argsArr],
+    { cwd, encoding: 'utf-8', env: { ...process.env, ...GIT_ENV } }
+  );
+  let parsed = null;
+  try { parsed = JSON.parse((res.stdout || '').trim()); } catch { /* not JSON */ }
+  return { stdout: res.stdout || '', stderr: res.stderr || '', exitCode: res.status, parsed };
+}
+
+/**
+ * Count commits on HEAD of a repo.
+ */
+function countCommits(repoDir) {
+  const out = execSync('git rev-list --count HEAD', { cwd: repoDir, encoding: 'utf-8' }).trim();
+  return parseInt(out, 10) || 0;
+}
+
+describe('cmdQuickFinalize', () => {
+  let env;
+  afterEach(() => { if (env) env.cleanup(); env = null; });
+
+  it('commits ALL artifacts when PLAN + SUMMARY + CONTEXT + VERIFICATION + STATE + HISTORY all exist', () => {
+    env = createFinalizeEnv();
+    fs.writeFileSync(path.join(env.taskDir, env.quickId + '-PLAN.md'), '# plan\n');
+    fs.writeFileSync(path.join(env.taskDir, env.quickId + '-SUMMARY.md'), '# summary\n');
+    fs.writeFileSync(path.join(env.taskDir, env.quickId + '-CONTEXT.md'), '# context\n');
+    fs.writeFileSync(path.join(env.taskDir, env.quickId + '-VERIFICATION.md'), '# verification\n');
+    fs.writeFileSync(path.join(env.quickDir, 'HISTORY.md'), '# history\n');
+    fs.writeFileSync(env.statePath, '# state\n');
+
+    const res = runFinalize(env.repoDir, [
+      env.quickId,
+      '--quick-dir', env.quickDir,
+      '--state-path', env.statePath,
+      '--description', 'test all artifacts',
+    ]);
+    assert.equal(res.exitCode, 0, 'stderr: ' + res.stderr);
+    assert.ok(res.parsed, 'expected parsed JSON, got: ' + res.stdout);
+    assert.equal(res.parsed.committed, true);
+    assert.equal(res.parsed.commit_reason, 'committed');
+    assert.equal(res.parsed.files_committed.length, 6, 'files: ' + JSON.stringify(res.parsed.files_committed));
+
+    // Verify commit message
+    const msg = execSync('git log -1 --format=%s', { cwd: env.repoDir, encoding: 'utf-8' }).trim();
+    assert.equal(msg, 'docs(quick-' + env.quickId + '): test all artifacts');
+  });
+
+  it('commits minimal artifacts when only PLAN + SUMMARY + STATE exist', () => {
+    env = createFinalizeEnv();
+    fs.writeFileSync(path.join(env.taskDir, env.quickId + '-PLAN.md'), '# plan\n');
+    fs.writeFileSync(path.join(env.taskDir, env.quickId + '-SUMMARY.md'), '# summary\n');
+    fs.writeFileSync(env.statePath, '# state\n');
+    // No CONTEXT, VERIFICATION, or HISTORY
+
+    const res = runFinalize(env.repoDir, [
+      env.quickId,
+      '--quick-dir', env.quickDir,
+      '--state-path', env.statePath,
+      '--description', 'minimal artifacts',
+    ]);
+    assert.equal(res.exitCode, 0, 'stderr: ' + res.stderr);
+    assert.ok(res.parsed);
+    assert.equal(res.parsed.committed, true);
+    assert.equal(res.parsed.commit_reason, 'committed');
+    assert.equal(res.parsed.files_committed.length, 3);
+  });
+
+  it('fast mode: commit message is `docs(quick-<id>): track fast task`', () => {
+    env = createFinalizeEnv({ skipTaskDir: true });
+    fs.writeFileSync(env.statePath, '# state\n');
+    fs.writeFileSync(path.join(env.quickDir, 'HISTORY.md'), '# history\n');
+
+    const res = runFinalize(env.repoDir, [
+      env.quickId,
+      '--quick-dir', env.quickDir,
+      '--state-path', env.statePath,
+      '--fast',
+    ]);
+    assert.equal(res.exitCode, 0, 'stderr: ' + res.stderr);
+    assert.ok(res.parsed);
+    assert.equal(res.parsed.committed, true);
+    // files_committed contains STATE + HISTORY only (no PLAN/SUMMARY in fast)
+    assert.equal(res.parsed.files_committed.length, 2);
+
+    const msg = execSync('git log -1 --format=%s', { cwd: env.repoDir, encoding: 'utf-8' }).trim();
+    assert.equal(msg, 'docs(quick-' + env.quickId + '): track fast task');
+  });
+
+  it('fast mode with HISTORY.md: HISTORY.md is in files_committed', () => {
+    env = createFinalizeEnv({ skipTaskDir: true });
+    fs.writeFileSync(env.statePath, '# state\n');
+    fs.writeFileSync(path.join(env.quickDir, 'HISTORY.md'), '# history row\n');
+
+    const res = runFinalize(env.repoDir, [
+      env.quickId,
+      '--quick-dir', env.quickDir,
+      '--state-path', env.statePath,
+      '--fast',
+    ]);
+    assert.equal(res.exitCode, 0, 'stderr: ' + res.stderr);
+    assert.ok(res.parsed);
+    assert.equal(res.parsed.committed, true);
+    const hasHistory = res.parsed.files_committed.some(f => f.endsWith('HISTORY.md'));
+    assert.ok(hasHistory, 'HISTORY.md should be in files_committed: ' + JSON.stringify(res.parsed.files_committed));
+  });
+
+  it('invalid quick_id (no matching task dir) exits with clear error', () => {
+    env = createFinalizeEnv({ skipTaskDir: true });
+    // task dir NOT created — non-fast mode should error
+    fs.writeFileSync(env.statePath, '# state\n');
+
+    const res = runFinalize(env.repoDir, [
+      'NONEXISTENT',
+      '--quick-dir', env.quickDir,
+      '--state-path', env.statePath,
+      '--description', 'some desc',
+    ]);
+    assert.notEqual(res.exitCode, 0);
+    assert.ok(
+      res.stderr.includes('task directory not found'),
+      'expected "task directory not found" in stderr, got: ' + res.stderr
+    );
+  });
+
+  it('missing --description in non-fast mode exits with clear error', () => {
+    env = createFinalizeEnv();
+
+    const res = runFinalize(env.repoDir, [
+      env.quickId,
+      '--quick-dir', env.quickDir,
+      '--state-path', env.statePath,
+    ]);
+    assert.notEqual(res.exitCode, 0);
+    assert.ok(
+      res.stderr.includes('description required') || res.stderr.includes('--description'),
+      'expected description error in stderr, got: ' + res.stderr
+    );
+  });
+
+  it('missing --quick-dir in non-fast mode exits with clear error', () => {
+    env = createFinalizeEnv();
+
+    const res = runFinalize(env.repoDir, [
+      env.quickId,
+      '--state-path', env.statePath,
+      '--description', 'desc here',
+    ]);
+    assert.notEqual(res.exitCode, 0);
+    assert.ok(
+      res.stderr.includes('quick-dir required') || res.stderr.includes('--quick-dir'),
+      'expected quick-dir error in stderr, got: ' + res.stderr
+    );
+  });
+
+  it('config.commit_docs=false skips commit (no git commit created)', () => {
+    env = createFinalizeEnv({ commitDocs: false });
+    fs.writeFileSync(path.join(env.taskDir, env.quickId + '-PLAN.md'), '# plan\n');
+    fs.writeFileSync(path.join(env.taskDir, env.quickId + '-SUMMARY.md'), '# summary\n');
+    fs.writeFileSync(env.statePath, '# state\n');
+
+    const commitsBefore = countCommits(env.repoDir);
+    const res = runFinalize(env.repoDir, [
+      env.quickId,
+      '--quick-dir', env.quickDir,
+      '--state-path', env.statePath,
+      '--description', 'skip mode',
+    ]);
+    assert.equal(res.exitCode, 0, 'stderr: ' + res.stderr);
+    assert.ok(res.parsed);
+    assert.equal(res.parsed.committed, false);
+    assert.equal(res.parsed.commit_reason, 'skipped_commit_docs_false');
+    assert.deepEqual(res.parsed.files_committed, []);
+    const commitsAfter = countCommits(env.repoDir);
+    assert.equal(commitsAfter, commitsBefore, 'no new commit should have been created');
+  });
+
+  it('nothing-to-commit: returns committed=false, commit_reason=nothing_to_commit', () => {
+    env = createFinalizeEnv();
+    fs.writeFileSync(path.join(env.taskDir, env.quickId + '-PLAN.md'), '# plan\n');
+    fs.writeFileSync(path.join(env.taskDir, env.quickId + '-SUMMARY.md'), '# summary\n');
+    fs.writeFileSync(env.statePath, '# state\n');
+
+    // First call: succeeds and commits
+    const first = runFinalize(env.repoDir, [
+      env.quickId,
+      '--quick-dir', env.quickDir,
+      '--state-path', env.statePath,
+      '--description', 'first call',
+    ]);
+    assert.equal(first.exitCode, 0, 'first call stderr: ' + first.stderr);
+    assert.equal(first.parsed.committed, true);
+
+    // Second call: same files, nothing new staged
+    const second = runFinalize(env.repoDir, [
+      env.quickId,
+      '--quick-dir', env.quickDir,
+      '--state-path', env.statePath,
+      '--description', 'second call',
+    ]);
+    assert.equal(second.exitCode, 0, 'second call stderr: ' + second.stderr);
+    assert.ok(second.parsed);
+    assert.equal(second.parsed.committed, false);
+    assert.equal(second.parsed.commit_reason, 'nothing_to_commit');
+  });
+});

package/deliver-great-systems/bin/lib/repos.cjs

@@ -63,6 +63,7 @@ function parseReposMd(cwd) {
       path: cells[2] || '',
       url: cells[3] || '',
       description: cells[4] || '',
+      setup: (cells[5] || '').trim(),
     });
   }
 
@@ -1106,6 +1107,7 @@ function cmdReposInitProduct(cwd, options, raw) {
     }
     fs.mkdirSync(path.join(getPlanningRoot(cwd), 'specs'), { recursive: true });
     fs.mkdirSync(path.join(getPlanningRoot(cwd), 'docs', 'product'), { recursive: true });
+    fs.mkdirSync(path.join(getPlanningRoot(cwd), 'quick'), { recursive: true });
     error('Product already initialized. Use /dgs:progress to see status.');
   }
 
@@ -1119,6 +1121,7 @@ function cmdReposInitProduct(cwd, options, raw) {
   }
   fs.mkdirSync(path.join(getPlanningRoot(cwd), 'specs'), { recursive: true });
   fs.mkdirSync(path.join(getPlanningRoot(cwd), 'docs', 'product'), { recursive: true });
+  fs.mkdirSync(path.join(getPlanningRoot(cwd), 'quick'), { recursive: true });
 
   // Add .gitkeep files to empty directories so they survive git commit
   const gitkeepPaths = [
@@ -1127,6 +1130,7 @@ function cmdReposInitProduct(cwd, options, raw) {
     path.join(getPlanningRoot(cwd), 'ideas', 'done', '.gitkeep'),
     path.join(getPlanningRoot(cwd), 'specs', '.gitkeep'),
     path.join(getPlanningRoot(cwd), 'docs', 'product', '.gitkeep'),
+    path.join(getPlanningRoot(cwd), 'quick', '.gitkeep'),
   ];
   for (const gk of gitkeepPaths) {
     if (!fs.existsSync(gk)) {
@@ -1150,6 +1154,25 @@ function cmdReposInitProduct(cwd, options, raw) {
   const siblingRepos = discoverSiblingRepos(cwd);
   const allRepos = [...discoveredRepos, ...siblingRepos];
 
+  // Bootstrap empty code repos so git worktree creation works later.
+  // git worktree add requires at least one commit (a HEAD to branch from).
+  const bootstrappedRepos = [];
+  for (const repo of allRepos) {
+    const repoPath = path.resolve(cwd, repo.path);
+    if (!fs.existsSync(path.join(repoPath, '.git'))) continue;
+    const logResult = execGit(repoPath, ['rev-parse', 'HEAD']);
+    if (logResult.exitCode !== 0) {
+      // Empty repo — no commits yet
+      const readmePath = path.join(repoPath, 'README.md');
+      if (!fs.existsSync(readmePath)) {
+        fs.writeFileSync(readmePath, `# ${repo.name}\n`, 'utf-8');
+      }
+      execGit(repoPath, ['add', 'README.md']);
+      execGit(repoPath, ['commit', '-m', 'chore: initial commit']);
+      bootstrappedRepos.push(repo.name);
+    }
+  }
+
   // Derive product name
   const productName = options.productName || path.basename(cwd);
 
@@ -1178,7 +1201,8 @@ function cmdReposInitProduct(cwd, options, raw) {
     ideas_dirs_created: true,
     specs_dir_created: true,
     docs_dir_created: true,
-    files_created: ['config.json', 'config.local.json', 'REPOS.md', 'PROJECTS.md', 'ideas/', 'specs/', 'docs/', '.gitignore', 'review-keys.json'],
+    bootstrapped_repos: bootstrappedRepos,
+    files_created: ['config.json', 'config.local.json', 'REPOS.md', 'PROJECTS.md', 'ideas/', 'specs/', 'docs/', 'quick/', '.gitignore', 'review-keys.json'],
   }, raw);
 }