@ktpartners/dgs-platform 2.9.0 → 3.3.0

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

@@ -0,0 +1,730 @@
+/**
+ * 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 wtPath = path.join(env.tmpDir, 'code-repo--tp-v1-0');
+    fs.mkdirSync(wtPath, { recursive: true });
+
+    const config = readLocalConfig(env.planDir);
+    config.projects = { tp: { worktrees: { 'v1-0': { type: 'milestone', repos: { 'code-repo': wtPath } } } } };
+    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 milestone entry has no repos (stale)', () => {
+    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, 'product');
+  });
+
+  it('returns product mode when milestone entry repos point to non-existent path (stale)', () => {
+    // Regression test for 260507-pdp: a stale milestone entry left over from
+    // an interrupted /dgs:complete-milestone (or aborted `worktrees remove`)
+    // silently re-routed every subsequent /dgs:quick to milestone-context.
+    // Pre-fix this returned 'milestone-context' — post-fix it falls through.
+    const config = readLocalConfig(env.planDir);
+    config.projects = { tp: { worktrees: { 'v1-0': { type: 'milestone', repos: { 'code-repo': '/nonexistent/path/v1-0' } } } } };
+    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, 'product');
+  });
+
+  it('does NOT auto-clear stale milestone entries from config', () => {
+    // Asymmetric to getActiveQuick by design: milestone state is heavier than
+    // quick state and may carry context worth inspecting; user clears manually
+    // via `dgs-tools worktrees remove <slug>`.
+    const config = readLocalConfig(env.planDir);
+    config.projects = { tp: { worktrees: { 'v1-0': { type: 'milestone', repos: { 'code-repo': '/nonexistent/path/v1-0' } } } } };
+    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, 'product');
+
+    // Re-read config and assert the milestone entry is STILL present
+    const updatedConfig = readLocalConfig(env.planDir);
+    const entry = updatedConfig.projects && updatedConfig.projects.tp
+      && updatedConfig.projects.tp.worktrees
+      && updatedConfig.projects.tp.worktrees['v1-0'];
+    assert.ok(entry, 'Stale milestone entry should NOT be auto-cleared');
+    assert.equal(entry.type, 'milestone');
+    assert.equal(updatedConfig.execution.active_context, 'v1-0',
+      'active_context should also still point to the stale milestone');
+  });
+
+  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);
+    // Slug now includes quickId prefix: YYMMDD-xxx-fix-token-bug
+    assert.ok(/^\d{6}-[a-z0-9]{3}-fix-token-bug$/.test(result.slug),
+      'Slug should have quickId prefix: ' + result.slug);
+
+    // Verify active_context was set
+    const config = readLocalConfig(env.planDir);
+    assert.equal(config.execution.active_context, result.slug);
+
+    // Verify worktree entry exists
+    const entry = config.projects.tp.worktrees[result.slug];
+    assert.ok(entry, 'Worktree entry should exist');
+    assert.equal(entry.type, 'quick');
+  });
+
+  it('returns canonical slug that matches worktrees[] lookup key for long descriptions (regression: slug truncation)', () => {
+    // Regression for 260507-kq9: a title whose descSlug fills the 40-char cap
+    // produces a 51-char raw slug (10-char quickId + '-' + 40-char descSlug).
+    // cmdWorktreesCreate re-sanitises with a 50-char cap, so the worktrees[]
+    // entry is keyed under the 50-char canonical slug. Pre-fix, startProductQuick
+    // read back at the 51-char key → undefined → returned `repos: {}`.
+    // The workflow then injected no <worktree_context> and the executor
+    // committed to main of the registered repo instead of the quick branch.
+    const { startProductQuick } = require('./quick.cjs');
+    const longTitle = 'fix slug truncation mismatch causing empty repos and main commits';
+    const result = startProductQuick(env.planDir, longTitle, null);
+
+    assert.equal(result.success, true,
+      'startProductQuick should succeed; got error: ' + (result.error || '<none>'));
+    assert.ok(result.slug.length <= 50,
+      'Returned slug must respect canonical 50-char cap; got ' + result.slug.length + ' chars: ' + result.slug);
+    assert.ok(Object.keys(result.repos).length > 0,
+      'Returned repos must be populated (regression: was {} when slug exceeded 50 chars). repos: ' + JSON.stringify(result.repos));
+
+    // The slug-as-returned must equal the slug-as-keyed in config.local.json.
+    const config = readLocalConfig(env.planDir);
+    assert.equal(config.execution.active_context, result.slug,
+      'active_context should equal returned slug; active_context=' + config.execution.active_context + ' slug=' + result.slug);
+    const entry = config.projects.tp.worktrees[result.slug];
+    assert.ok(entry,
+      'worktrees[result.slug] must exist; available keys: ' +
+      JSON.stringify(Object.keys(config.projects.tp.worktrees || {})));
+    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');
+  });
+
+  it('commits both flat PLAN.md and numbered {quickId}-01-SUMMARY.md (regression: idea #18)', () => {
+    env = createFinalizeEnv();
+    // Planner writes flat PLAN, executor writes numbered SUMMARY (the 260410-ckl shape)
+    fs.writeFileSync(path.join(env.taskDir, env.quickId + '-PLAN.md'), '# plan\n');
+    fs.writeFileSync(path.join(env.taskDir, env.quickId + '-01-SUMMARY.md'), '# summary\n');
+    fs.writeFileSync(env.statePath, '# state\n');
+
+    const res = runFinalize(env.repoDir, [
+      env.quickId,
+      '--quick-dir', env.quickDir,
+      '--state-path', env.statePath,
+      '--description', 'idea-18 regression',
+    ]);
+    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');
+    // 3 files: flat PLAN + numbered SUMMARY + STATE
+    assert.equal(res.parsed.files_committed.length, 3, 'files: ' + JSON.stringify(res.parsed.files_committed));
+
+    // Both file basenames must appear in the actual commit
+    const committedFiles = execSync(
+      'git log -1 --name-only --format=',
+      { cwd: env.repoDir, encoding: 'utf-8' }
+    ).trim().split('\n').filter(Boolean);
+    const hasFlat = committedFiles.some(f => f.endsWith(env.quickId + '-PLAN.md'));
+    const hasNumberedSummary = committedFiles.some(f => f.endsWith(env.quickId + '-01-SUMMARY.md'));
+    assert.ok(hasFlat, 'flat PLAN.md should be in commit, got: ' + JSON.stringify(committedFiles));
+    assert.ok(hasNumberedSummary, 'numbered SUMMARY should be in commit, got: ' + JSON.stringify(committedFiles));
+  });
+
+  it('commits fully numbered shape ({quickId}-01-PLAN.md + {quickId}-01-SUMMARY.md)', () => {
+    env = createFinalizeEnv();
+    fs.writeFileSync(path.join(env.taskDir, env.quickId + '-01-PLAN.md'), '# plan\n');
+    fs.writeFileSync(path.join(env.taskDir, env.quickId + '-01-SUMMARY.md'), '# summary\n');
+    fs.writeFileSync(env.statePath, '# state\n');
+
+    const res = runFinalize(env.repoDir, [
+      env.quickId,
+      '--quick-dir', env.quickDir,
+      '--state-path', env.statePath,
+      '--description', 'fully numbered shape',
+    ]);
+    assert.equal(res.exitCode, 0, 'stderr: ' + res.stderr);
+    assert.ok(res.parsed);
+    assert.equal(res.parsed.committed, true);
+    assert.equal(res.parsed.files_committed.length, 3);
+  });
+});