@ktpartners/dgs-platform 2.9.0 → 3.3.0

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

@@ -0,0 +1,739 @@
+/**
+ * Quick -- Quick workflow lifecycle management
+ *
+ * Two flavors:
+ *   - Product-level quick: ephemeral worktree off main with quick/{slug} branch.
+ *     Full lifecycle: start, complete (rebase+merge+cleanup), abandon (discard).
+ *   - Milestone-context quick: work in existing milestone worktree, no new worktree.
+ *     No complete/abandon -- changes merge with the milestone.
+ *
+ * One active product-level quick at a time per product (planning root).
+ * Stale entries (directory missing) are auto-cleared.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execGit, output, error, loadConfig } = require('./core.cjs');
+const { getLocalConfigPath } = require('./config.cjs');
+const { getPlanningRoot } = require('./paths.cjs');
+const { cmdWorktreesCreate, cmdWorktreesRemove, rebaseAndMerge } = require('./worktrees.cjs');
+const { checkFourEyes } = require('./governance.cjs');
+const { requireGitIdentity, formatAuthorString } = require('./identity.cjs');
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Read config.local.json safely.
+ * @param {string} cwd
+ * @returns {object}
+ */
+function _readLocalConfig(cwd) {
+  const localPath = getLocalConfigPath(cwd);
+  try {
+    if (fs.existsSync(localPath)) {
+      return JSON.parse(fs.readFileSync(localPath, 'utf-8'));
+    }
+  } catch { /* ignore */ }
+  return {};
+}
+
+/**
+ * Write config.local.json atomically.
+ * @param {string} cwd
+ * @param {object} data
+ */
+function _writeLocalConfig(cwd, data) {
+  const localPath = getLocalConfigPath(cwd);
+  const dir = path.dirname(localPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  const tmpPath = localPath + '.tmp.' + process.pid;
+  fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+  fs.renameSync(tmpPath, localPath);
+}
+
+/**
+ * Generate a collision-resistant quick task ID: YYMMDD-xxx
+ * xxx = 2-second precision blocks since midnight, encoded as 3-char Base36.
+ * @param {Date} [date] - Date to use (defaults to now)
+ * @returns {string} e.g. '260414-v4y'
+ */
+function generateQuickId(date) {
+  const now = date || new Date();
+  const yy = String(now.getFullYear()).slice(-2);
+  const mm = String(now.getMonth() + 1).padStart(2, '0');
+  const dd = String(now.getDate()).padStart(2, '0');
+  const dateStr = yy + mm + dd;
+  const secondsSinceMidnight = now.getHours() * 3600 + now.getMinutes() * 60 + now.getSeconds();
+  const timeBlocks = Math.floor(secondsSinceMidnight / 2);
+  const timeEncoded = timeBlocks.toString(36).padStart(3, '0');
+  return dateStr + '-' + timeEncoded;
+}
+
+/**
+ * Sanitize a title into a valid slug for branch/worktree naming.
+ * @param {string} title
+ * @returns {string}
+ */
+function _sanitizeSlug(title) {
+  if (!title) return '';
+  return title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40)
+    .replace(/-+$/, '');
+}
+
+/**
+ * Clear a stale quick entry from config.local.json.
+ * Called when getActiveQuick detects a quick whose worktree directory is missing.
+ * @param {string} cwd
+ * @param {string} project
+ * @param {string} slug
+ * @param {object} localConfig - Already loaded config.local.json object
+ */
+function _clearStaleQuick(cwd, project, slug, localConfig) {
+  if (localConfig.projects && localConfig.projects[project]
+    && localConfig.projects[project].worktrees) {
+    delete localConfig.projects[project].worktrees[slug];
+  }
+  // Clear active_context if it points to this stale quick
+  if (localConfig.execution && localConfig.execution.active_context === slug) {
+    delete localConfig.execution.active_context;
+  }
+  _writeLocalConfig(cwd, localConfig);
+  process.stderr.write('Warning: Stale quick \'' + slug + '\' auto-cleared (worktree directory missing)\n');
+}
+
+// ─── Exported functions ───────────────────────────────────────────────────────
+
+// Stale-defence symmetry: this function probes entry.repos paths with
+// fs.existsSync the same way getActiveQuick (below) does for QUICK
+// entries. Don't "simplify" the on-disk check away — its absence is
+// exactly the bug fixed in 260507-pdp. Asymmetry: we do NOT auto-clear
+// stale milestone entries here; milestone state is heavier and may
+// carry inspectable context. The user clears manually via
+// `dgs-tools worktrees remove <slug>`.
+/**
+ * Detect whether a quick should be product-level or milestone-context.
+ *
+ * @param {string} cwd - Planning root
+ * @param {boolean} forceMain - True if --main flag was passed
+ * @returns {{ mode: 'product'|'milestone-context', activeSlug?: string, activeMilestone?: string }}
+ */
+function detectQuickMode(cwd, forceMain) {
+  if (forceMain) return { mode: 'product' };
+
+  const config = loadConfig(cwd);
+  const localConfig = _readLocalConfig(cwd);
+  const activeContext = localConfig.execution && localConfig.execution.active_context;
+
+  if (!activeContext) return { mode: 'product' };
+
+  // Check if active context is a milestone worktree
+  const project = config.current_project;
+  if (!project) return { mode: 'product' };
+
+  const worktrees = (localConfig.projects && localConfig.projects[project]
+    && localConfig.projects[project].worktrees) || {};
+  const entry = worktrees[activeContext];
+
+  if (entry && entry.type === 'milestone') {
+    const repos = entry.repos || {};
+    const paths = Object.values(repos);
+    const anyExists = paths.length > 0 && paths.some(function(p) { return fs.existsSync(p); });
+    if (anyExists) {
+      return { mode: 'milestone-context', activeSlug: activeContext, activeMilestone: activeContext };
+    }
+    // Stale milestone entry — no on-disk worktree. Fall through to product
+    // mode so quicks land where the user expects. Don't auto-clear: milestone
+    // state is heavier than quick state and may carry context worth
+    // inspecting; the user can run `dgs-tools worktrees remove <slug>`.
+  }
+
+  // If active context is a quick or unknown, treat as product-level
+  return { mode: 'product' };
+}
+
+/**
+ * Get the currently active product-level quick, if any.
+ *
+ * @param {string} cwd - Planning root
+ * @returns {{ slug: string, entry: object }|null}
+ */
+function getActiveQuick(cwd) {
+  const config = loadConfig(cwd);
+  const localConfig = _readLocalConfig(cwd);
+  const project = config.current_project;
+  if (!project) return null;
+
+  const worktrees = (localConfig.projects && localConfig.projects[project]
+    && localConfig.projects[project].worktrees) || {};
+
+  for (const [slug, entry] of Object.entries(worktrees)) {
+    if (entry.type === 'quick') {
+      // Verify directory still exists (stale detection)
+      const repos = entry.repos || {};
+      const paths = Object.values(repos);
+      const anyExists = paths.some(function(p) { return fs.existsSync(p); });
+      if (anyExists) {
+        return { slug: slug, entry: entry };
+      }
+      // Directory missing -- stale entry, auto-clear
+      _clearStaleQuick(cwd, project, slug, localConfig);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Start a product-level quick: guard check, create worktree, set context.
+ *
+ * @param {string} cwd - Planning root
+ * @param {string} title - Quick task title (used for slug and branch)
+ * @param {string|null} mode - 'full', 'debug', or null (plain)
+ * @returns {{ success: boolean, slug?: string, error?: string, activeSlug?: string }}
+ */
+function startProductQuick(cwd, title, mode) {
+  // Guard: one active product-level quick at a time
+  const active = getActiveQuick(cwd);
+  if (active) {
+    return {
+      success: false,
+      error: 'Quick worktree already active: \'' + active.slug + '\'. Complete it (`dgs:complete-quick`), abandon it (`dgs:abandon-quick`), or use `dgs:fast` for trivial fixes.',
+      activeSlug: active.slug,
+    };
+  }
+
+  const config = loadConfig(cwd);
+  const project = config.current_project;
+  if (!project) return { success: false, error: 'No current project set' };
+
+  // Generate quickId and sanitize title to slug with quickId prefix
+  const quickId = generateQuickId();
+  const descSlug = _sanitizeSlug(title);
+  if (!descSlug) return { success: false, error: 'Cannot create slug from title: ' + title };
+  const slug = quickId + '-' + descSlug;
+  // Match worktrees.cjs _sanitizeSlug: slice(0, 50) then strip trailing dashes.
+  // cmdWorktreesCreate re-sanitises whatever slug we pass, so we must pre-truncate
+  // here and use the canonical slug for the execSync arg, the read-back lookup,
+  // the active_context write, and the return value. Otherwise long descSlugs
+  // (40 chars) push the total past 50 and the read-back below misses, returning
+  // repos: {} and breaking the workflow's worktree-context injection (which
+  // causes the executor to commit to main of the registered repo instead of
+  // the quick/<slug> branch in the worktree). See quick task 260507-kq9.
+  const canonicalSlug = slug.slice(0, 50).replace(/-+$/, '');
+
+  // Create worktree via existing cmdWorktreesCreate
+  // Note: cmdWorktreesCreate calls output() which exits the process.
+  // We need to handle this differently -- call the underlying logic directly.
+  // Since cmdWorktreesCreate calls process.exit via output(), we invoke it
+  // through a subprocess to capture the result.
+  const { execSync } = require('child_process');
+  const dgsTools = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+  const root = getPlanningRoot(cwd);
+
+  try {
+    const modeArgs = mode ? ' --mode ' + mode : '';
+    const result = execSync(
+      'node ' + JSON.stringify(dgsTools) + ' worktrees create ' + JSON.stringify(canonicalSlug) + ' --type quick' + modeArgs,
+      { cwd: root, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8', timeout: 60000 }
+    );
+    // Parse output to verify creation
+    const parsed = JSON.parse(result.trim());
+    if (!parsed.created) {
+      return { success: false, error: 'Worktree creation returned unexpected result' };
+    }
+  } catch (err) {
+    const stderr = (err.stderr || '').toString().trim();
+    return { success: false, error: 'Failed to create quick worktree: ' + (stderr || err.message || String(err)) };
+  }
+
+  // Set mode in worktree config entry and set active_context
+  const localConfig = _readLocalConfig(cwd);
+  if (localConfig.projects && localConfig.projects[project]
+    && localConfig.projects[project].worktrees
+    && localConfig.projects[project].worktrees[canonicalSlug]) {
+    localConfig.projects[project].worktrees[canonicalSlug].mode = mode || null;
+  }
+
+  // Set active_context
+  if (!localConfig.execution) localConfig.execution = {};
+  localConfig.execution.active_context = canonicalSlug;
+
+  _writeLocalConfig(cwd, localConfig);
+
+  const finalConfig = _readLocalConfig(cwd);
+  const repos =
+    (finalConfig.projects &&
+      finalConfig.projects[project] &&
+      finalConfig.projects[project].worktrees &&
+      finalConfig.projects[project].worktrees[canonicalSlug] &&
+      finalConfig.projects[project].worktrees[canonicalSlug].repos) || {};
+  return { success: true, slug: canonicalSlug, repos: repos };
+}
+
+/**
+ * Complete the active product-level quick: rebase, merge, push, cleanup.
+ *
+ * @param {string} cwd - Planning root
+ * @returns {{ success: boolean, commitCount?: number, slug?: string, error?: string, manualInstructions?: string }}
+ */
+function quickComplete(cwd, options) {
+  options = options || {};
+  const active = getActiveQuick(cwd);
+  if (!active) {
+    return { success: false, error: 'No active product-level quick to complete. If working in a milestone context, changes are part of the milestone.' };
+  }
+
+  const { slug, entry } = active;
+  const repos = entry.repos || {};
+  const repoNames = Object.keys(repos);
+
+  if (repoNames.length === 0) {
+    return { success: false, error: 'Quick \'' + slug + '\' has no repos tracked' };
+  }
+
+  // Count commits on quick branch vs base_branch for summary
+  let totalCommits = 0;
+  const config = loadConfig(cwd);
+  const baseBranch = config.base_branch || 'main';
+
+  // ── Four-Eyes Gate (GATE-02) ───────────────────────────────────────────────
+  const planRoot = getPlanningRoot(cwd);
+  const rawConfig = (() => {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(planRoot, 'config.json'), 'utf-8'));
+    } catch { return {}; }
+  })();
+  const fourEyesMode = (rawConfig.workflow && rawConfig.workflow.four_eyes) || 'off';
+
+  if (fourEyesMode !== 'off') {
+    // Resolve current user identity
+    let currentUserStr = '';
+    try {
+      const identity = requireGitIdentity(cwd);
+      currentUserStr = formatAuthorString(identity);
+    } catch {
+      currentUserStr = '';
+    }
+
+    // Get contributors from quick task worktree commits
+    const quickContributors = [];
+    for (const repoName of repoNames) {
+      const worktreePath = repos[repoName];
+      const branchName = 'quick/' + slug;
+      try {
+        // Get unique commit authors from the quick branch
+        const logResult = execGit(worktreePath, ['log', '--format=%aN <%aE>', baseBranch + '..' + branchName]);
+        if (logResult.exitCode === 0 && logResult.stdout.trim()) {
+          const authors = logResult.stdout.trim().split('\n');
+          for (const author of authors) {
+            if (author.trim()) quickContributors.push(author.trim());
+          }
+        }
+      } catch { /* ignore — contributor detection is best-effort */ }
+    }
+
+    // Deduplicate contributors
+    const seen = new Map();
+    for (const c of quickContributors) {
+      const key = c.toLowerCase();
+      if (!seen.has(key)) seen.set(key, c);
+    }
+    const uniqueContribs = [...seen.values()];
+
+    // Run four-eyes check
+    const feResult = checkFourEyes(uniqueContribs, currentUserStr, fourEyesMode);
+
+    // Display contributor list (SHR-02 — contextual: "this task")
+    const contribNames = uniqueContribs.length > 0
+      ? uniqueContribs.join(', ')
+      : '(none detected)';
+
+    if (feResult.passed) {
+      process.stderr.write('Contributors: ' + contribNames + ' \u2014 \u2714 Four-eyes satisfied\n');
+    } else {
+      process.stderr.write('Contributors: ' + contribNames + '\n');
+
+      let displayName = currentUserStr;
+      try {
+        const identity = requireGitIdentity(cwd);
+        displayName = identity.name;
+      } catch { /* use full string */ }
+
+      if (fourEyesMode === 'warn') {
+        // Warn: display warning, proceed
+        process.stderr.write('\u26A0 You (' + displayName + ') contributed to this task. Completing anyway (warn mode).\n');
+      } else if (fourEyesMode === 'enforce') {
+        if (options.force) {
+          // Force: display override, proceed
+          process.stderr.write('\u26A0 Forced: you (' + displayName + ') are the only contributor. Override logged.\n');
+        } else {
+          // Block: return error
+          return {
+            success: false,
+            error: '\u2718 Blocked: you (' + displayName + ') are the only contributor. Use --force to override.',
+          };
+        }
+      }
+    }
+  }
+  // Off mode: no check, no output (GATE-03)
+
+  // Rebase and merge each repo
+  for (const repoName of repoNames) {
+    const worktreePath = repos[repoName];
+    const branchName = 'quick/' + slug;
+
+    // Count commits before merge
+    const countResult = execGit(worktreePath, ['rev-list', '--count', baseBranch + '..' + branchName]);
+    if (countResult.exitCode === 0) {
+      totalCommits += parseInt(countResult.stdout.trim(), 10) || 0;
+    }
+
+    const result = rebaseAndMerge(cwd, repoName, slug, { push: true });
+    if (!result.success) {
+      return {
+        success: false,
+        slug: slug,
+        error: result.error,
+        manualInstructions: result.manualInstructions,
+      };
+    }
+  }
+
+  // Cleanup: remove worktree and branch via subprocess
+  const { execSync } = require('child_process');
+  const dgsTools = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+  const root = getPlanningRoot(cwd);
+
+  try {
+    execSync(
+      'node ' + JSON.stringify(dgsTools) + ' worktrees remove ' + JSON.stringify(slug),
+      { cwd: root, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8', timeout: 60000 }
+    );
+  } catch (err) {
+    process.stderr.write('Warning: Worktree cleanup failed: ' + ((err.stderr || '').toString().trim() || err.message || String(err)) + '\n');
+  }
+
+  // Clear active_context and worktree entry (belt-and-suspenders -- remove should handle this)
+  const localConfig = _readLocalConfig(cwd);
+  if (localConfig.execution && localConfig.execution.active_context === slug) {
+    delete localConfig.execution.active_context;
+  }
+  const project = config.current_project;
+  if (project && localConfig.projects && localConfig.projects[project]
+    && localConfig.projects[project].worktrees) {
+    delete localConfig.projects[project].worktrees[slug];
+  }
+  _writeLocalConfig(cwd, localConfig);
+
+  return {
+    success: true,
+    slug: slug,
+    commitCount: totalCommits,
+  };
+}
+
+/**
+ * Abandon the active product-level quick: remove worktree without merging.
+ *
+ * @param {string} cwd - Planning root
+ * @param {boolean} confirmed - Must be true to proceed (workflows handle confirmation UI)
+ * @returns {{ success: boolean, slug?: string, error?: string }}
+ */
+function quickAbandon(cwd, confirmed) {
+  if (!confirmed) {
+    return { success: false, error: 'Abandon not confirmed. Pass confirmed=true to proceed.' };
+  }
+
+  const active = getActiveQuick(cwd);
+  if (!active) {
+    return { success: false, error: 'No active product-level quick to abandon. If working in a milestone context, use complete-milestone instead.' };
+  }
+
+  const { slug } = active;
+
+  // Remove worktree and branch (without merging) via subprocess
+  const { execSync } = require('child_process');
+  const dgsTools = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+  const root = getPlanningRoot(cwd);
+
+  try {
+    execSync(
+      'node ' + JSON.stringify(dgsTools) + ' worktrees remove ' + JSON.stringify(slug),
+      { cwd: root, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8', timeout: 60000 }
+    );
+  } catch (err) {
+    process.stderr.write('Warning: Worktree removal failed: ' + ((err.stderr || '').toString().trim() || err.message || String(err)) + '\n');
+  }
+
+  // Clear active_context and worktree entry
+  const localConfig = _readLocalConfig(cwd);
+  const config = loadConfig(cwd);
+  if (localConfig.execution && localConfig.execution.active_context === slug) {
+    delete localConfig.execution.active_context;
+  }
+  const project = config.current_project;
+  if (project && localConfig.projects && localConfig.projects[project]
+    && localConfig.projects[project].worktrees) {
+    delete localConfig.projects[project].worktrees[slug];
+  }
+  _writeLocalConfig(cwd, localConfig);
+
+  return { success: true, slug: slug };
+}
+
+// ─── CLI command wrappers ─────────────────────────────────────────────────────
+
+/**
+ * CLI handler for `dgs-tools complete-quick` (also `quick-complete` for backward compat).
+ * @param {string} cwd
+ */
+function cmdQuickComplete(cwd, args) {
+  const force = args && args.includes('--force');
+  const result = quickComplete(cwd, { force });
+  if (!result.success) {
+    if (result.manualInstructions) {
+      process.stderr.write(result.manualInstructions + '\n');
+    }
+    error(result.error);
+    return;
+  }
+  output({
+    completed: true,
+    slug: result.slug,
+    commits: result.commitCount,
+    message: 'Quick \'' + result.slug + '\' merged to main (' + result.commitCount + ' commits). Worktree cleaned up. Pushed to origin.',
+  });
+}
+
+/**
+ * CLI handler for `dgs-tools abandon-quick` (also `quick-abandon` for backward compat).
+ * @param {string} cwd
+ * @param {string[]} args
+ */
+function cmdQuickAbandon(cwd, args) {
+  const confirmed = args && args.includes('--confirmed');
+  const result = quickAbandon(cwd, confirmed);
+  if (!result.success) {
+    error(result.error);
+    return;
+  }
+  output({
+    abandoned: true,
+    slug: result.slug,
+    message: 'Quick \'' + result.slug + '\' abandoned. Worktree removed.',
+  });
+}
+
+/**
+ * CLI: `dgs-tools quick finalize <quick_id> [flags]`.
+ *
+ * Stages and commits all quick-task artifacts atomically in a single git commit:
+ *   - {quickDir}/{quickId}-{slug}/{quickId}-PLAN.md         (required in non-fast mode)
+ *   - {quickDir}/{quickId}-{slug}/{quickId}-SUMMARY.md      (required in non-fast mode)
+ *   - {quickDir}/{quickId}-{slug}/{quickId}-CONTEXT.md      (optional)
+ *   - {quickDir}/{quickId}-{slug}/{quickId}-VERIFICATION.md (optional)
+ *   - {quickDir}/HISTORY.md                                 (optional)
+ *   - {statePath}                                           (optional)
+ *
+ * In --fast mode the task directory does NOT exist; only STATE.md and optional
+ * HISTORY.md are committed. Commit message: `docs(quick-${quickId}): track fast task`.
+ *
+ * Respects config.commit_docs (skip commit if false). Does NOT call cmdCommit
+ * (which process.exits via output()); uses execGit directly, mirroring the
+ * inline pattern used by cmdPhaseFinalize (phase.cjs ~line 947).
+ *
+ * @param {string} cwd - Planning root (used for config + git cwd unless options.repoCwd)
+ * @param {string} quickId - Quick task id (e.g., '260405-u6b')
+ * @param {object} options - { description, quickDir, statePath, push, repoCwd, fast }
+ * @param {boolean} raw - true to emit raw JSON, false for pretty output
+ */
+// Collect the list of still-dirty paths in `gitCwd` after a commit. Purely
+// informational — populates `result.dirty_after` so callers can detect
+// verify-step side effects that leaked outside the staged file set. Never
+// throws. Duplicated from commands.cjs/phase.cjs instead of extracted because
+// the three call sites use slightly different cwd variables (gitCwd vs
+// gitCwdReal vs cwd) and a shared helper would obscure that.
+function collectDirtyAfter(gitCwd) {
+  const porcelain = execGit(gitCwd, ['status', '--porcelain']);
+  if (porcelain.exitCode !== 0) return [];
+  return (porcelain.stdout || '')
+    .split('\n')
+    .map(l => l.trim())
+    .filter(Boolean)
+    .map(l => l.replace(/^..\s+/, ''));
+}
+
+function cmdQuickFinalize(cwd, quickId, options, raw) {
+  options = options || {};
+
+  if (!quickId) {
+    error('quick_id required for quick finalize');
+    return;
+  }
+  if (!options.quickDir) {
+    error('--quick-dir required');
+    return;
+  }
+  if (!options.fast && !options.description) {
+    error('--description required (unless --fast)');
+    return;
+  }
+
+  const result = {
+    committed: false,
+    hash: null,
+    files_committed: [],
+    commit_reason: 'unknown',
+  };
+
+  const gitCwd = options.repoCwd || cwd;
+  // Resolve to real path so path.relative works when gitCwd and file paths
+  // cross symlink boundaries (e.g., /tmp vs /private/tmp on macOS).
+  let gitCwdReal = gitCwd;
+  try { gitCwdReal = fs.realpathSync(gitCwd); } catch { /* fallback to gitCwd */ }
+  const toRel = (absPath) => {
+    let p = absPath;
+    try { p = fs.realpathSync(absPath); } catch { /* use original */ }
+    return path.relative(gitCwdReal, p);
+  };
+  const filesToStage = [];
+
+  // In non-fast mode, locate the task directory and enumerate artifacts
+  if (!options.fast) {
+    if (!fs.existsSync(options.quickDir)) {
+      error('task directory not found for quick_id: ' + quickId + ' (quick-dir missing: ' + options.quickDir + ')');
+      return;
+    }
+    let taskDirName = null;
+    try {
+      const entries = fs.readdirSync(options.quickDir);
+      const prefix = quickId + '-';
+      for (const e of entries) {
+        if (e === prefix.replace(/-$/, '')) { continue; }
+        if (e.indexOf(prefix) === 0) {
+          const full = path.join(options.quickDir, e);
+          try {
+            if (fs.statSync(full).isDirectory()) {
+              taskDirName = e;
+              break;
+            }
+          } catch { /* ignore */ }
+        }
+      }
+    } catch { /* ignore */ }
+
+    if (!taskDirName) {
+      error('task directory not found for quick_id: ' + quickId);
+      return;
+    }
+
+    const taskDir = path.join(options.quickDir, taskDirName);
+    // Sweep all quick-task artifacts in taskDir, accepting both the flat
+    // ({quickId}-NAME.md) and numbered ({quickId}-NN-NAME.md) shapes. The
+    // numbered shape is what the dgs-planner template renders for quick
+    // tasks (see agents/dgs-planner.md). False-positive risk is negligible
+    // because quickId is a 6-char base36 timestamp + 3-char suffix.
+    const escapedId = quickId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const artifactRe = new RegExp(
+      '^' + escapedId + '(-\\d+)?-(PLAN|SUMMARY|CONTEXT|VERIFICATION|CODEREVIEW|DEBUG-LOG|RESEARCH)\\.md$'
+    );
+    let taskEntries = [];
+    try { taskEntries = fs.readdirSync(taskDir); } catch { /* taskDir guard above already handled missing dir */ }
+    for (const entry of taskEntries) {
+      if (artifactRe.test(entry)) {
+        filesToStage.push(toRel(path.join(taskDir, entry)));
+      }
+    }
+  }
+
+  // STATE.md (optional — may not exist in some flows)
+  if (options.statePath && fs.existsSync(options.statePath)) {
+    filesToStage.push(toRel(options.statePath));
+  }
+
+  // HISTORY.md at quickDir root (optional — created by archival)
+  const historyPath = path.join(options.quickDir, 'HISTORY.md');
+  if (fs.existsSync(historyPath)) {
+    filesToStage.push(toRel(historyPath));
+  }
+
+  // Honor config.commit_docs — file writes already happened, just skip commit.
+  const config = loadConfig(cwd);
+  if (!config.commit_docs) {
+    result.committed = false;
+    result.commit_reason = 'skipped_commit_docs_false';
+    result.files_committed = [];
+    output(result, raw);
+    return;
+  }
+
+  // Stage + commit atomically (inline execGit — cmdCommit calls output/exit).
+  for (const f of filesToStage) {
+    execGit(gitCwdReal, ['add', f]);
+  }
+  const message = options.fast
+    ? 'docs(quick-' + quickId + '): track fast task'
+    : 'docs(quick-' + quickId + '): ' + options.description;
+  const commitResult = execGit(gitCwdReal, ['commit', '-m', message]);
+  if (commitResult.exitCode !== 0) {
+    const nothing =
+      (commitResult.stdout || '').includes('nothing to commit') ||
+      (commitResult.stderr || '').includes('nothing to commit') ||
+      (commitResult.stdout || '').includes('no changes added') ||
+      (commitResult.stderr || '').includes('no changes added');
+    result.committed = false;
+    result.commit_reason = nothing ? 'nothing_to_commit' : 'commit_failed';
+    if (!nothing) result.commit_error = commitResult.stderr;
+    result.files_committed = [];
+    result.dirty_after = collectDirtyAfter(gitCwdReal);
+    output(result, raw);
+    return;
+  }
+  const hashResult = execGit(gitCwdReal, ['rev-parse', '--short', 'HEAD']);
+  result.committed = true;
+  result.hash = hashResult.exitCode === 0 ? hashResult.stdout : null;
+  result.commit_reason = 'committed';
+  result.files_committed = filesToStage;
+  result.dirty_after = collectDirtyAfter(gitCwdReal);
+
+  // Optional push (same semantics as cmdPhaseFinalize)
+  if (options.push) {
+    const syncPush = config.sync_push || 'off';
+    if (syncPush === 'auto') {
+      try {
+        const { pushAll } = require('./sync.cjs');
+        const pushRes = pushAll(gitCwdReal, { force: true });
+        result.pushed = pushRes.ok;
+        result.push_result = pushRes;
+      } catch (err) {
+        result.pushed = false;
+        result.push_result = { ok: false, error: err.message };
+      }
+    } else if (syncPush === 'prompt') {
+      result.needs_push = true;
+    }
+  }
+
+  output(result, raw);
+}
+
+module.exports = {
+  generateQuickId,
+  detectQuickMode,
+  getActiveQuick,
+  startProductQuick,
+  quickComplete,
+  quickAbandon,
+  cmdQuickComplete,
+  cmdQuickAbandon,
+  cmdQuickFinalize,
+};