gsd-antigravity-kit 2.0.1 → 2.1.0

package/.agent/skills/gsd/bin/lib/commands.cjs

@@ -313,11 +313,19 @@ function cmdCommit(cwd, message, files, raw, amend, noVerify) {
   }
 
   // Stage files
-  const filesToStage = files && files.length > 0 ? files : ['.planning/'];
+  const explicitFiles = files && files.length > 0;
+  const filesToStage = explicitFiles ? files : ['.planning/'];
   for (const file of filesToStage) {
   const fullPath = path.join(cwd, file);
   if (!fs.existsSync(fullPath)) {
-    // File was deleted/moved — stage the deletion
+    if (explicitFiles) {
+    // Caller passed an explicit --files list: missing files are skipped.
+    // Staging a deletion here would silently remove tracked planning files
+    // (e.g. STATE.md, ROADMAP.md) when they are temporarily absent (#2014).
+    continue;
+    }
+    // Default mode (staging all of .planning/): stage the deletion so
+    // removed planning files are not left dangling in the index.
     execGit(cwd, ['rm', '--cached', '--ignore-unmatch', file]);
   } else {
     execGit(cwd, ['add', file]);
@@ -823,8 +831,9 @@ function cmdStats(cwd, format, raw) {
   const headingPattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
   let match;
   while ((match = headingPattern.exec(roadmapContent)) !== null) {
-    phasesByNumber.set(match[1], {
-    number: match[1],
+    const key = normalizePhaseName(match[1]);
+    phasesByNumber.set(key, {
+    number: key,
     name: match[2].replace(/\(INSERTED\)/i, '').trim(),
     plans: 0,
     summaries: 0,
@@ -854,9 +863,10 @@ function cmdStats(cwd, format, raw) {
 
     const status = determinePhaseStatus(plans, summaries, path.join(phasesDir, dir), 'Not Started');
 
-    const existing = phasesByNumber.get(phaseNum);
-    phasesByNumber.set(phaseNum, {
-    number: phaseNum,
+    const normalizedNum = normalizePhaseName(phaseNum);
+    const existing = phasesByNumber.get(normalizedNum);
+    phasesByNumber.set(normalizedNum, {
+    number: normalizedNum,
     name: existing?.name || phaseName,
     plans: (existing?.plans || 0) + plans,
     summaries: (existing?.summaries || 0) + summaries,

package/.agent/skills/gsd/bin/lib/config.cjs

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { output, error, planningRoot, CONFIG_DEFAULTS } = require('./core.cjs');
+const { output, error, planningDir, withPlanningLock, CONFIG_DEFAULTS, atomicWriteFileSync } = require('./core.cjs');
 const {
   VALID_PROFILES,
   getAgentToModelMapForProfile,
@@ -15,19 +15,28 @@ const VALID_CONFIG_KEYS = new Set([
   'mode', 'granularity', 'parallelization', 'commit_docs', 'model_profile',
   'search_gitignored', 'brave_search', 'firecrawl', 'exa_search',
   'workflow.research', 'workflow.plan_check', 'workflow.verifier',
-  'workflow.nyquist_validation', 'workflow.ui_phase', 'workflow.ui_safety_gate',
+  'workflow.nyquist_validation', 'workflow.ai_integration_phase', 'workflow.ui_phase', 'workflow.ui_safety_gate',
   'workflow.auto_advance', 'workflow.node_repair', 'workflow.node_repair_budget',
+  'workflow.tdd_mode',
   'workflow.text_mode',
   'workflow.research_before_questions',
   'workflow.discuss_mode',
   'workflow.skip_discuss',
+  'workflow.auto_prune_state',
   'workflow._auto_chain_active',
   'workflow.use_worktrees',
   'workflow.code_review',
   'workflow.code_review_depth',
+  'workflow.code_review_command',
+  'workflow.pattern_mapper',
+  'workflow.plan_bounce',
+  'workflow.plan_bounce_script',
+  'workflow.plan_bounce_passes',
   'git.branching_strategy', 'git.base_branch', 'git.phase_branch_template', 'git.milestone_branch_template', 'git.quick_branch_template',
   'planning.commit_docs', 'planning.search_gitignored',
+  'workflow.cross_ai_execution', 'workflow.cross_ai_command', 'workflow.cross_ai_timeout',
   'workflow.subagent_timeout',
+  'workflow.inline_plan_threshold',
   'hooks.context_warnings',
   'features.thinking_partner',
   'context',
@@ -36,6 +45,10 @@ const VALID_CONFIG_KEYS = new Set([
   'project_code', 'phase_naming',
   'manager.flags.discuss', 'manager.flags.plan', 'manager.flags.execute',
   'response_language',
+  'intel.enabled',
+  'graphify.enabled',
+  'graphify.build_timeout',
+  'antigravity_md_path',
 ]);
 
 /**
@@ -47,6 +60,8 @@ function isValidConfigKey(keyPath) {
   if (VALID_CONFIG_KEYS.has(keyPath)) return true;
   // Allow agent_skills.<agent-type> with any agent type string
   if (/^agent_skills\.[a-zA-Z0-9_-]+$/.test(keyPath)) return true;
+  // Allow review.models.<cli-name> for per-CLI model selection in /gsd-review
+  if (/^review\.models\.[a-zA-Z0-9_-]+$/.test(keyPath)) return true;
   // Allow features.<feature_name> — dynamic namespace for feature flags.
   // Intentionally open-ended so new flags (e.g., features.global_learnings) work
   // without updating VALID_CONFIG_KEYS each time.
@@ -61,9 +76,11 @@ const CONFIG_KEY_SUGGESTIONS = {
   'hooks.research_questions': 'workflow.research_before_questions',
   'workflow.research_questions': 'workflow.research_before_questions',
   'workflow.codereview': 'workflow.code_review',
+  'workflow.review_command': 'workflow.code_review_command',
   'workflow.review': 'workflow.code_review',
   'workflow.code_review_level': 'workflow.code_review_depth',
   'workflow.review_depth': 'workflow.code_review_depth',
+  'review.model': 'review.models.<cli-name>',
 };
 
 function validateKnownConfigKeyPath(keyPath) {
@@ -143,12 +160,20 @@ function buildNewProjectConfig(userChoices) {
     node_repair_budget: 2,
     ui_phase: true,
     ui_safety_gate: true,
+    ai_integration_phase: true,
+    tdd_mode: false,
     text_mode: false,
     research_before_questions: false,
     discuss_mode: 'discuss',
     skip_discuss: false,
     code_review: true,
     code_review_depth: 'standard',
+    code_review_command: null,
+    pattern_mapper: true,
+    plan_bounce: false,
+    plan_bounce_script: null,
+    plan_bounce_passes: 2,
+    auto_prune_state: false,
   },
   hooks: {
     context_warnings: true,
@@ -156,6 +181,7 @@ function buildNewProjectConfig(userChoices) {
   project_code: null,
   phase_naming: 'sequential',
   agent_skills: {},
+  antigravity_md_path: './ANTIGRAVITY.md',
   };
 
   // Three-level deep merge: hardcoded <- userDefaults <- choices
@@ -196,7 +222,7 @@ function buildNewProjectConfig(userChoices) {
  * Idempotent: if config.json already exists, returns { created: false }.
  */
 function cmdConfigNewProject(cwd, choicesJson, raw) {
-  const planningBase = planningRoot(cwd);
+  const planningBase = planningDir(cwd);
   const configPath = path.join(planningBase, 'config.json');
 
   // Idempotent: don't overwrite existing config
@@ -227,7 +253,7 @@ function cmdConfigNewProject(cwd, choicesJson, raw) {
   const config = buildNewProjectConfig(userChoices);
 
   try {
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+  atomicWriteFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
   output({ created: true, path: '.planning/config.json' }, raw, 'created');
   } catch (err) {
   error('Failed to write config.json: ' + err.message);
@@ -241,7 +267,7 @@ function cmdConfigNewProject(cwd, choicesJson, raw) {
  * the happy path. But note that `error()` will still `exit(1)` out of the process.
  */
 function ensureConfigFile(cwd) {
-  const planningBase = planningRoot(cwd);
+  const planningBase = planningDir(cwd);
   const configPath = path.join(planningBase, 'config.json');
 
   // Ensure .planning directory exists
@@ -261,7 +287,7 @@ function ensureConfigFile(cwd) {
   const config = buildNewProjectConfig({});
 
   try {
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+  atomicWriteFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
   return { created: true, path: '.planning/config.json' };
   } catch (err) {
   error('Failed to create config.json: ' + err.message);
@@ -291,38 +317,40 @@ function cmdConfigEnsureSection(cwd, raw) {
  * the happy path. But note that `error()` will still `exit(1)` out of the process.
  */
 function setConfigValue(cwd, keyPath, parsedValue) {
-  const configPath = path.join(planningRoot(cwd), 'config.json');
+  const configPath = path.join(planningDir(cwd), 'config.json');
 
+  return withPlanningLock(cwd, () => {
   // Load existing config or start with empty object
   let config = {};
   try {
-  if (fs.existsSync(configPath)) {
+    if (fs.existsSync(configPath)) {
     config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
-  }
+    }
   } catch (err) {
-  error('Failed to read config.json: ' + err.message);
+    error('Failed to read config.json: ' + err.message);
   }
 
   // Set nested value using dot notation (e.g., "workflow.research")
   const keys = keyPath.split('.');
   let current = config;
   for (let i = 0; i < keys.length - 1; i++) {
-  const key = keys[i];
-  if (current[key] === undefined || typeof current[key] !== 'object') {
+    const key = keys[i];
+    if (current[key] === undefined || typeof current[key] !== 'object') {
     current[key] = {};
-  }
-  current = current[key];
+    }
+    current = current[key];
   }
   const previousValue = current[keys[keys.length - 1]]; // Capture previous value before overwriting
   current[keys[keys.length - 1]] = parsedValue;
 
   // Write back
   try {
-  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
-  return { updated: true, key: keyPath, value: parsedValue, previousValue };
+    atomicWriteFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+    return { updated: true, key: keyPath, value: parsedValue, previousValue };
   } catch (err) {
-  error('Failed to write config.json: ' + err.message);
+    error('Failed to write config.json: ' + err.message);
   }
+  });
 }
 
 /**
@@ -361,17 +389,21 @@ function cmdConfigSet(cwd, keyPath, value, raw) {
   output(setConfigValueResult, raw, `${keyPath}=${parsedValue}`);
 }
 
-function cmdConfigGet(cwd, keyPath, raw) {
-  const configPath = path.join(planningRoot(cwd), 'config.json');
+function cmdConfigGet(cwd, keyPath, raw, defaultValue) {
+  const configPath = path.join(planningDir(cwd), 'config.json');
+  const hasDefault = defaultValue !== undefined;
 
   if (!keyPath) {
-  error('Usage: config-get <key.path>');
+  error('Usage: config-get <key.path> [--default <value>]');
   }
 
   let config = {};
   try {
   if (fs.existsSync(configPath)) {
     config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+  } else if (hasDefault) {
+    output(defaultValue, raw, String(defaultValue));
+    return;
   } else {
     error('No config.json found at ' + configPath);
   }
@@ -385,12 +417,14 @@ function cmdConfigGet(cwd, keyPath, raw) {
   let current = config;
   for (const key of keys) {
   if (current === undefined || current === null || typeof current !== 'object') {
+    if (hasDefault) { output(defaultValue, raw, String(defaultValue)); return; }
     error(`Key not found: ${keyPath}`);
   }
   current = current[key];
   }
 
   if (current === undefined) {
+  if (hasDefault) { output(defaultValue, raw, String(defaultValue)); return; }
   error(`Key not found: ${keyPath}`);
   }
 
@@ -461,6 +495,17 @@ function getCmdConfigSetModelProfileResultMessage(
   return paragraphs.join('\n\n');
 }
 
+/**
+ * Print the resolved config.json path (workstream-aware). Used by settings.md
+ * so the workflow writes/reads the correct file when a workstream is active (#2282).
+ */
+function cmdConfigPath(cwd) {
+  // Always emit as plain text — a file path is used via shell substitution,
+  // never consumed as JSON. Passing raw=true forces plain-text output.
+  const configPath = path.join(planningDir(cwd), 'config.json');
+  output(configPath, true, configPath);
+}
+
 module.exports = {
   VALID_CONFIG_KEYS,
   cmdConfigEnsureSection,
@@ -468,4 +513,5 @@ module.exports = {
   cmdConfigGet,
   cmdConfigSetModelProfile,
   cmdConfigNewProject,
+  cmdConfigPath,
 };

package/.agent/skills/gsd/bin/lib/core.cjs

@@ -27,6 +27,16 @@ const WORKSTREAM_SESSION_ENV_KEYS = [
 let cachedControllingTtyToken = null;
 let didProbeControllingTtyToken = false;
 
+// Track all .planning/.lock files held by this process so they can be removed
+// on exit. process.on('exit') fires even on process.exit(1), unlike try/finally
+// which is skipped when error() calls process.exit(1) inside a locked region (#1916).
+const _heldPlanningLocks = new Set();
+process.on('exit', () => {
+  for (const lockPath of _heldPlanningLocks) {
+  try { fs.unlinkSync(lockPath); } catch { /* already gone */ }
+  }
+});
+
 // ─── Path helpers ────────────────────────────────────────────────────────────
 
 /** Normalize a relative path to always use forward slashes (cross-platform). */
@@ -149,14 +159,25 @@ function findProjectRoot(startDir) {
  * @param {number} opts.maxAgeMs - max age in ms before removal (default: 5 min)
  * @param {boolean} opts.dirsOnly - if true, only remove directories (default: false)
  */
+/**
+ * Dedicated GSD temp directory: path.join(os.tmpdir(), 'gsd').
+ * Created on first use. Keeps GSD temp files isolated from the system
+ * temp directory so reap scans only GSD files (#1975).
+ */
+const GSD_TEMP_DIR = path.join(require('os').tmpdir(), 'gsd');
+
+function ensureGsdTempDir() {
+  fs.mkdirSync(GSD_TEMP_DIR, { recursive: true });
+}
+
 function reapStaleTempFiles(prefix = 'gsd-', { maxAgeMs = 5 * 60 * 1000, dirsOnly = false } = {}) {
   try {
-  const tmpDir = require('os').tmpdir();
+  ensureGsdTempDir();
   const now = Date.now();
-  const entries = fs.readdirSync(tmpDir);
+  const entries = fs.readdirSync(GSD_TEMP_DIR);
   for (const entry of entries) {
     if (!entry.startsWith(prefix)) continue;
-    const fullPath = path.join(tmpDir, entry);
+    const fullPath = path.join(GSD_TEMP_DIR, entry);
     try {
     const stat = fs.statSync(fullPath);
     if (now - stat.mtimeMs > maxAgeMs) {
@@ -185,7 +206,8 @@ function output(result, raw, rawValue) {
   // Write to tmpfile and output the path prefixed with @file: so callers can detect it.
   if (json.length > 50000) {
     reapStaleTempFiles();
-    const tmpPath = path.join(require('os').tmpdir(), `gsd-${Date.now()}.json`);
+    ensureGsdTempDir();
+    const tmpPath = path.join(GSD_TEMP_DIR, `gsd-${Date.now()}.json`);
     fs.writeFileSync(tmpPath, json, 'utf-8');
     data = '@file:' + tmpPath;
   } else {
@@ -284,6 +306,7 @@ const CONFIG_DEFAULTS = {
   plan_checker: true,
   verifier: true,
   nyquist_validation: true,
+  ai_integration_phase: true,
   parallelization: true,
   brave_search: false,
   firecrawl: false,
@@ -357,7 +380,7 @@ function loadConfig(cwd) {
     // Section containers that hold nested sub-keys
     'git', 'workflow', 'planning', 'hooks', 'features',
     // Internal keys loadConfig reads but config-set doesn't expose
-    'model_overrides', 'agent_skills', 'context_window', 'resolve_model_ids',
+    'model_overrides', 'agent_skills', 'context_window', 'resolve_model_ids', 'antigravity_md_path',
     // Deprecated keys (still accepted for migration, not in config-set)
     'depth', 'multiRepo',
   ]);
@@ -407,7 +430,11 @@ function loadConfig(cwd) {
     brave_search: get('brave_search') ?? defaults.brave_search,
     firecrawl: get('firecrawl') ?? defaults.firecrawl,
     exa_search: get('exa_search') ?? defaults.exa_search,
+    tdd_mode: get('tdd_mode', { section: 'workflow', field: 'tdd_mode' }) ?? false,
     text_mode: get('text_mode', { section: 'workflow', field: 'text_mode' }) ?? defaults.text_mode,
+    auto_advance: get('auto_advance', { section: 'workflow', field: 'auto_advance' }) ?? false,
+    _auto_chain_active: get('_auto_chain_active', { section: 'workflow', field: '_auto_chain_active' }) ?? false,
+    mode: get('mode') ?? 'interactive',
     sub_repos: get('sub_repos', { section: 'planning', field: 'sub_repos' }) ?? defaults.sub_repos,
     resolve_model_ids: get('resolve_model_ids') ?? defaults.resolve_model_ids,
     context_window: get('context_window') ?? defaults.context_window,
@@ -418,6 +445,7 @@ function loadConfig(cwd) {
     agent_skills: parsed.agent_skills || {},
     manager: parsed.manager || {},
     response_language: get('response_language') || null,
+    antigravity_md_path: get('antigravity_md_path') || null,
   };
   } catch {
   // Fall back to ~/.gsd/defaults.json only for truly pre-project contexts (#1683)
@@ -455,7 +483,11 @@ function loadConfig(cwd) {
 
 // ─── Git utilities ────────────────────────────────────────────────────────────
 
+const _gitIgnoredCache = new Map();
+
 function isGitIgnored(cwd, targetPath) {
+  const key = cwd + '::' + targetPath;
+  if (_gitIgnoredCache.has(key)) return _gitIgnoredCache.get(key);
   try {
   // --no-index checks .gitignore rules regardless of whether the file is tracked.
   // Without it, git check-ignore returns "not ignored" for tracked files even when
@@ -467,8 +499,10 @@ function isGitIgnored(cwd, targetPath) {
     cwd,
     stdio: 'pipe',
   });
+  _gitIgnoredCache.set(key, true);
   return true;
   } catch {
+  _gitIgnoredCache.set(key, false);
   return false;
   }
 }
@@ -630,6 +664,98 @@ function resolveWorktreeRoot(cwd) {
   return cwd;
 }
 
+/**
+ * Parse `git worktree list --porcelain` output into an array of
+ * { path, branch } objects.  Entries with a detached HEAD (no branch line)
+ * are skipped because we cannot safely reason about their merge status.
+ *
+ * @param {string} porcelain - raw output from git worktree list --porcelain
+ * @returns {{ path: string, branch: string }[]}
+ */
+function parseWorktreePorcelain(porcelain) {
+  const entries = [];
+  let current = null;
+  for (const line of porcelain.split('\n')) {
+  if (line.startsWith('worktree ')) {
+    current = { path: line.slice('worktree '.length).trim(), branch: null };
+  } else if (line.startsWith('branch refs/heads/') && current) {
+    current.branch = line.slice('branch refs/heads/'.length).trim();
+  } else if (line === '' && current) {
+    if (current.branch) entries.push(current);
+    current = null;
+  }
+  }
+  // flush last entry if file doesn't end with blank line
+  if (current && current.branch) entries.push(current);
+  return entries;
+}
+
+/**
+ * Remove linked git worktrees whose branch has already been merged into the
+ * current HEAD of the main worktree.  Also runs `git worktree prune` to clear
+ * any stale references left by manually-deleted worktree directories.
+ *
+ * Safe guards:
+ *  - Never removes the main worktree (first entry in --porcelain output).
+ *  - Never removes the worktree at process.cwd().
+ *  - Never removes a worktree whose branch has unmerged commits.
+ *  - Skips detached-HEAD worktrees (no branch name).
+ *
+ * @param {string} repoRoot - absolute path to the main (or any) worktree of
+ *   the repository; used as `cwd` for git commands.
+ * @returns {string[]} list of worktree paths that were removed
+ */
+function pruneOrphanedWorktrees(repoRoot) {
+  const pruned = [];
+  const cwd = process.cwd();
+
+  try {
+  // 1. Get all worktrees in porcelain format
+  const listResult = execGit(repoRoot, ['worktree', 'list', '--porcelain']);
+  if (listResult.exitCode !== 0) return pruned;
+
+  const worktrees = parseWorktreePorcelain(listResult.stdout);
+  if (worktrees.length === 0) {
+    execGit(repoRoot, ['worktree', 'prune']);
+    return pruned;
+  }
+
+  // 2. First entry is the main worktree — never touch it
+  const mainWorktreePath = worktrees[0].path;
+
+  // 3. Check each non-main worktree
+  for (let i = 1; i < worktrees.length; i++) {
+    const { path: wtPath, branch } = worktrees[i];
+
+    // Never remove the worktree for the current process directory
+    if (wtPath === cwd || cwd.startsWith(wtPath + path.sep)) continue;
+
+    // Check if the branch is fully merged into HEAD (main)
+    // git merge-base --is-ancestor <branch> HEAD exits 0 when merged
+    const ancestorCheck = execGit(repoRoot, [
+    'merge-base', '--is-ancestor', branch, 'HEAD',
+    ]);
+
+    if (ancestorCheck.exitCode !== 0) {
+    // Not yet merged — leave it alone
+    continue;
+    }
+
+    // Remove the worktree and delete the branch
+    const removeResult = execGit(repoRoot, ['worktree', 'remove', '--force', wtPath]);
+    if (removeResult.exitCode === 0) {
+    execGit(repoRoot, ['branch', '-D', branch]);
+    pruned.push(wtPath);
+    }
+  }
+  } catch { /* never crash the caller */ }
+
+  // 4. Always run prune to clear stale references (e.g. manually-deleted dirs)
+  execGit(repoRoot, ['worktree', 'prune']);
+
+  return pruned;
+}
+
 /**
  * Acquire a file-based lock for .planning/ writes.
  * Prevents concurrent worktrees from corrupting shared planning files.
@@ -653,10 +779,15 @@ function withPlanningLock(cwd, fn) {
     acquired: new Date().toISOString(),
     }), { flag: 'wx' });
 
+    // Register for exit-time cleanup so process.exit(1) inside a locked region
+    // cannot leave a stale lock file (#1916).
+    _heldPlanningLocks.add(lockPath);
+
     // Lock acquired — run the function
     try {
     return fn();
     } finally {
+    _heldPlanningLocks.delete(lockPath);
     try { fs.unlinkSync(lockPath); } catch { /* already released */ }
     }
   } catch (err) {
@@ -725,19 +856,23 @@ function planningRoot(cwd) {
 }
 
 /**
- * Get common .planning file paths, workstream-aware.
- * Scoped paths (state, roadmap, phases, requirements) resolve to the active workstream.
- * Shared paths (project, config) always resolve to the root .planning/.
+ * Get common .planning file paths, project-and-workstream-aware.
+ *
+ * All paths route through planningDir(cwd, ws), which honors the GSD_PROJECT
+ * env var and active workstream. This matches loadConfig() above (line 256),
+ * which has always read config.json via planningDir(cwd). Previously project
+ * and config were resolved against the unrouted .planning/ root, which broke
+ * `gsd-tools config-get` in multi-project layouts (the CRUD writers and the
+ * reader pointed at different files).
  */
 function planningPaths(cwd, ws) {
   const base = planningDir(cwd, ws);
-  const root = path.join(cwd, '.planning');
   return {
   planning: base,
   state: path.join(base, 'STATE.md'),
   roadmap: path.join(base, 'ROADMAP.md'),
-  project: path.join(root, 'PROJECT.md'),
-  config: path.join(root, 'config.json'),
+  project: path.join(base, 'PROJECT.md'),
+  config: path.join(base, 'config.json'),
   phases: path.join(base, 'phases'),
   requirements: path.join(base, 'REQUIREMENTS.md'),
   };
@@ -934,7 +1069,10 @@ function normalizePhaseName(phase) {
   const match = stripped.match(/^(\d+)([A-Z])?((?:\.\d+)*)/i);
   if (match) {
   const padded = match[1].padStart(2, '0');
-  const letter = match[2] ? match[2].toUpperCase() : '';
+  // Preserve original case of letter suffix (#1962).
+  // Uppercasing causes directory/roadmap mismatches on case-sensitive filesystems
+  // (e.g., "16c" in ROADMAP.md → directory "16C-name" → progress can't match).
+  const letter = match[2] || '';
   const decimal = match[3] || '';
   return padded + letter + decimal;
   }
@@ -1540,6 +1678,64 @@ function readSubdirectories(dirPath, sort = false) {
   }
 }
 
+// ─── Atomic file writes ───────────────────────────────────────────────────────
+
+/**
+ * Write a file atomically using write-to-temp-then-rename.
+ *
+ * On POSIX systems, `fs.renameSync` is atomic when the source and destination
+ * are on the same filesystem. This prevents a process killed mid-write from
+ * leaving a truncated file that is unparseable on next read.
+ *
+ * The temp file is placed alongside the target so it is guaranteed to be on
+ * the same filesystem (required for rename atomicity). The PID is embedded in
+ * the temp file name so concurrent writers use distinct paths.
+ *
+ * If `renameSync` fails (e.g. cross-device move), the function falls back to a
+ * direct `writeFileSync` so callers always get a best-effort write.
+ *
+ * @param {string} filePath  Absolute path to write.
+ * @param {string|Buffer} content  File content.
+ * @param {string} [encoding='utf-8']  Encoding passed to writeFileSync.
+ */
+function atomicWriteFileSync(filePath, content, encoding = 'utf-8') {
+  const tmpPath = filePath + '.tmp.' + process.pid;
+  try {
+  fs.writeFileSync(tmpPath, content, encoding);
+  fs.renameSync(tmpPath, filePath);
+  } catch (renameErr) {
+  // Clean up the temp file if rename failed, then fall back to direct write.
+  try { fs.unlinkSync(tmpPath); } catch { /* already gone or never created */ }
+  fs.writeFileSync(filePath, content, encoding);
+  }
+}
+
+/**
+ * Format a Date as a fuzzy relative time string (e.g. "5 minutes ago").
+ * @param {Date} date
+ * @returns {string}
+ */
+function timeAgo(date) {
+  const seconds = Math.floor((Date.now() - date.getTime()) / 1000);
+  if (seconds < 5) return 'just now';
+  if (seconds < 60) return `${seconds} seconds ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes === 1) return '1 minute ago';
+  if (minutes < 60) return `${minutes} minutes ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours === 1) return '1 hour ago';
+  if (hours < 24) return `${hours} hours ago`;
+  const days = Math.floor(hours / 24);
+  if (days === 1) return '1 day ago';
+  if (days < 30) return `${days} days ago`;
+  const months = Math.floor(days / 30);
+  if (months === 1) return '1 month ago';
+  if (months < 12) return `${months} months ago`;
+  const years = Math.floor(days / 365);
+  if (years === 1) return '1 year ago';
+  return `${years} years ago`;
+}
+
 module.exports = {
   parseIncludeFlag,
   discoverPhaseArtifacts,
@@ -1576,6 +1772,7 @@ module.exports = {
   findProjectRoot,
   detectSubRepos,
   reapStaleTempFiles,
+  GSD_TEMP_DIR,
   MODEL_ALIAS_MAP,
   CONFIG_DEFAULTS,
   planningDir,
@@ -1589,4 +1786,7 @@ module.exports = {
   readSubdirectories,
   getAgentsDir,
   checkAgentsInstalled,
+  atomicWriteFileSync,
+  timeAgo,
+  pruneOrphanedWorktrees,
 };