@ktpartners/dgs-platform 3.3.1 → 3.4.2

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

@@ -11,6 +11,7 @@ const fs = require('fs');
 const path = require('path');
 const { safeReadFile, output, error } = require('./core.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
+const { enumerateIdeaDocsDirs } = require('./docs.cjs');
 
 // ─── Fuzzy Matching Engine ──────────────────────────────────────────────────
 
@@ -330,22 +331,10 @@ function scanDocs(cwd) {
   const productDocsDir = path.join(planRoot, 'docs');
   scanDocsDir(productDocsDir, 'product', path.join(planRootRel, 'docs'));
 
-  // Idea-scoped docs
-  const ideaStates = ['pending', 'done', 'rejected'];
-  for (const state of ideaStates) {
-    const stateDir = path.join(planRoot, 'ideas', state);
-    let ideaDirs;
-    try {
-      ideaDirs = fs.readdirSync(stateDir, { withFileTypes: true })
-        .filter(e => e.isDirectory())
-        .map(e => e.name);
-    } catch {
-      continue;
-    }
-    for (const ideaSlug of ideaDirs) {
-      const docsDir = path.join(stateDir, ideaSlug, 'docs');
-      scanDocsDir(docsDir, `idea:${ideaSlug}`, path.join(planRootRel, 'ideas', state, ideaSlug, 'docs'));
-    }
+  // Idea-scoped docs — flat-aware via the shared enumerator (legacy dirs included)
+  for (const { ideaSlug, docsDir } of enumerateIdeaDocsDirs(cwd)) {
+    const rel = path.relative(cwd, docsDir);
+    scanDocsDir(docsDir, `idea:${ideaSlug}`, rel);
   }
 
   // Spec-scoped docs

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

@@ -5,7 +5,7 @@
 const fs = require('fs');
 const path = require('path');
 const { loadConfig, getMilestoneInfo, getMilestonePhaseFilter, output, error, getProjectRoot } = require('./core.cjs');
-const { extractFrontmatter, reconstructFrontmatter } = require('./frontmatter.cjs');
+const { extractFrontmatter, reconstructFrontmatter, spliceFrontmatter } = require('./frontmatter.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
 
 // Escape special regex characters in a string
@@ -961,6 +961,151 @@ function cmdMarkMilestoneComplete(cwd, raw) {
   output(result, raw);
 }
 
+// ─── Ad-hoc milestone marker (Phase 159, ADH-04 primary) ─────────────────────
+
+/**
+ * Read the `adhoc` frontmatter marker from STATE.md.
+ *
+ * The marker is the primary, committed source of truth for whether the active
+ * milestone is an ad-hoc container. Degrades to `false` when STATE.md or the
+ * field is absent. (extractFrontmatter yields the string "true" for a bare
+ * boolean, so both the boolean and string form are accepted.)
+ *
+ * @param {string} cwd - Planning root directory
+ * @returns {boolean}
+ */
+function stateReadAdhoc(cwd) {
+  const statePath = resolveStatePath(cwd);
+  if (!fs.existsSync(statePath)) return false;
+  const content = fs.readFileSync(statePath, 'utf-8');
+  const fm = extractFrontmatter(content);
+  return fm.adhoc === true || fm.adhoc === 'true';
+}
+
+/**
+ * Set (or clear) the `adhoc` frontmatter marker on STATE.md.
+ *
+ * Writes `adhoc: true` when `value` is truthy. When falsy, the key is deleted
+ * so normal (non-adhoc) milestones keep clean frontmatter. Body content is
+ * preserved via spliceFrontmatter (reconstruct-and-splice).
+ *
+ * @param {string} cwd - Planning root directory
+ * @param {boolean} value
+ * @returns {{ success: boolean, adhoc: boolean }}
+ */
+function stateSetAdhoc(cwd, value) {
+  const statePath = resolveStatePath(cwd);
+  if (!fs.existsSync(statePath)) {
+    error('STATE.md not found');
+  }
+  const content = fs.readFileSync(statePath, 'utf-8');
+  const fm = extractFrontmatter(content);
+  if (value) {
+    fm.adhoc = true;
+  } else {
+    delete fm.adhoc;
+  }
+  const newContent = spliceFrontmatter(content, fm);
+  fs.writeFileSync(statePath, newContent, 'utf-8');
+  return { success: true, adhoc: !!value };
+}
+
+function cmdStateReadAdhoc(cwd, raw) {
+  const adhoc = stateReadAdhoc(cwd);
+  output({ adhoc }, raw, String(adhoc));
+}
+
+function cmdStateSetAdhoc(cwd, args, raw) {
+  // Default to setting true; accept an explicit false/0/no to clear.
+  const arg = args && args.length > 0 ? String(args[0]).toLowerCase() : 'true';
+  const value = !(arg === 'false' || arg === '0' || arg === 'no');
+  const result = stateSetAdhoc(cwd, value);
+  output(result, raw, String(result.adhoc));
+}
+
+// ─── Ad-hoc relaxed-completion readiness (Phase 161, ADH-10/11/13) ────────────
+
+/**
+ * Count well-formed data rows in the active STATE.md "Quick Tasks Completed"
+ * table. Mirrors the section regex used by _archiveSingleStateFile. A row counts
+ * only when its id cell AND its commit cell are both non-empty; header,
+ * separator, and malformed/partial rows are skipped. Handles both the 5-col
+ * (no Status) and 6-col (with Status) layouts — the Commit column is the 4th
+ * data column (cells[4]) in both.
+ *
+ * @param {string} statePath - Resolved STATE.md path
+ * @returns {number}
+ */
+function _countCompletedQuickRows(statePath) {
+  if (!fs.existsSync(statePath)) return 0;
+  const content = fs.readFileSync(statePath, 'utf-8');
+  const m = content.match(/(###\s*Quick Tasks Completed\s*\n)([\s\S]*?)(?=\n###?\s|\n##[^#]|$)/i);
+  if (!m) return 0;
+  let count = 0;
+  for (const line of m[2].split('\n')) {
+    if (!line.startsWith('|')) continue;
+    if (/^\|[\s-|]+$/.test(line)) continue; // separator
+    if (line.includes('Description')) continue; // header
+    const cells = line.split('|').map((c) => c.trim());
+    // cells[0] is the empty pre-pipe cell; cells[1] = id, cells[4] = Commit.
+    if (cells[1] && cells[4]) count += 1;
+  }
+  return count;
+}
+
+/**
+ * Count phases with disk_status === 'complete' for the active milestone.
+ * Runs `roadmap analyze --raw` as a subprocess (cmdRoadmapAnalyze is
+ * process-exiting) and reads `.completed_phases`. Defaults to 0 on any
+ * exec/parse failure — a quicks-only ad-hoc milestone may have no phases dir.
+ *
+ * @param {string} cwd - Planning root directory
+ * @returns {number}
+ */
+function _countCompletedPhases(cwd) {
+  try {
+    const { execSync } = require('child_process');
+    const toolsPath = path.resolve(__dirname, '..', 'dgs-tools.cjs');
+    const out = execSync(
+      'node ' + JSON.stringify(toolsPath) + ' roadmap analyze --raw',
+      { cwd, stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf-8' }
+    );
+    const parsed = JSON.parse(out.trim());
+    return Number(parsed.completed_phases) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Compute relaxed-completion readiness for the active milestone.
+ *
+ * - adhoc: the committed STATE.md marker (false when absent — ADH-11 fall-through
+ *   to the strict completion gate).
+ * - completedQuickRows / completedPhases: the two minimum-bar signals (ADH-10).
+ *   A planned-but-incomplete phase and a malformed quick row are NOT counted.
+ * - ready: true iff at least one merged unit of work exists.
+ * - reason: 'ok' when ready, else 'no_merged_work' (drives the ADH-13 refusal).
+ *
+ * @param {string} cwd - Planning root directory
+ * @returns {{ adhoc: boolean, completedQuickRows: number, completedPhases: number, ready: boolean, reason: string }}
+ */
+function stateAdhocReadiness(cwd) {
+  const adhoc = stateReadAdhoc(cwd);
+  const completedQuickRows = _countCompletedQuickRows(resolveStatePath(cwd));
+  const completedPhases = _countCompletedPhases(cwd);
+  const ready = completedQuickRows >= 1 || completedPhases >= 1;
+  return { adhoc, completedQuickRows, completedPhases, ready, reason: ready ? 'ok' : 'no_merged_work' };
+}
+
+function cmdStateAdhocReadiness(cwd, raw) {
+  const r = stateAdhocReadiness(cwd);
+  // The predicate is a machine contract consumed by complete-milestone.md and
+  // the test suite, which `JSON.parse` the --raw output. Emit compact JSON for
+  // --raw and pretty JSON otherwise (never a lossy human string).
+  output(r, raw, JSON.stringify(r));
+}
+
 module.exports = {
   stateExtractField,
   stateReplaceField,
@@ -982,4 +1127,10 @@ module.exports = {
   cmdStateArchiveQuickTasks,
   markMilestoneComplete,
   cmdMarkMilestoneComplete,
+  stateReadAdhoc,
+  stateSetAdhoc,
+  cmdStateReadAdhoc,
+  cmdStateSetAdhoc,
+  stateAdhocReadiness,
+  cmdStateAdhocReadiness,
 };

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

@@ -17,7 +17,7 @@ const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
 const { execSync } = require('child_process');
-const { execGit, output, error, loadConfig } = require('./core.cjs');
+const { execGit, output, error, loadConfig, generateSlugInternal } = require('./core.cjs');
 const { getLocalConfigPath } = require('./config.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
 const { parseReposMd } = require('./repos.cjs');
@@ -152,6 +152,78 @@ function _sanitizeSlug(input) {
     .replace(/-+$/, '');
 }
 
+/**
+ * Compose a structural milestone slug: `[<project>-]<version>-<name-slug>`.
+ *
+ * This replaces the legacy bare-name slug formula (`generateSlugInternal(name)
+ * || 'milestone'`) which collapsed a placeholder/blank milestone name to the
+ * bare `milestone` branch, causing cross-milestone branch-name collisions.
+ *
+ * The bare `'milestone'` slug is returned ONLY as the absolute last resort —
+ * when BOTH version and name are empty. A non-empty version always guarantees
+ * uniqueness, so a blank name yields the version segment alone (NOT 'milestone').
+ *
+ * @param {object} opts
+ * @param {string} [opts.version] - Milestone version (e.g. 'v25.0'); dots -> dashes.
+ * @param {string} [opts.name] - Milestone name (e.g. 'Ad-hoc Container').
+ * @param {string} [opts.project] - Project name (used only when multiProject).
+ * @param {boolean} [opts.multiProject] - Prefix with project when >1 active project.
+ * @returns {string} Sanitized slug, <=50 chars.
+ */
+function composeMilestoneSlug(opts) {
+  opts = opts || {};
+  // Version dots -> dashes, then sanitized (so 'v25.0' -> 'v25-0'). May be ''.
+  const sanitizedVersion = _sanitizeSlug(String(opts.version || '').replace(/\./g, '-'));
+  const nameSlug = _sanitizeSlug(opts.name || '');
+  const projectSlug = (opts.multiProject && opts.project) ? _sanitizeSlug(opts.project) : null;
+
+  const segments = [projectSlug, sanitizedVersion || null, nameSlug || null].filter(Boolean);
+  const joined = segments.join('-');
+
+  // Deterministic last-resort: ONLY when there is genuinely nothing else
+  // (both version AND name empty). Never applied to a non-empty version.
+  if (!joined) return 'milestone';
+
+  // Final pass guarantees a clean, <=50-char slug.
+  return _sanitizeSlug(joined);
+}
+
+/**
+ * Resolve the runtime milestone slug for a project, preferring a stamped
+ * worktree entry and legacy-falling-back to the OLD bare-name slug so that
+ * in-flight milestones created before the structural-slug upgrade are never
+ * orphaned.
+ *
+ * Resolution order:
+ *   1. NEW composed slug has a worktree entry -> use it.
+ *   2. Else OLD bare-name slug has a worktree entry -> use it (legacy fallback).
+ *   3. Else (fresh, not yet created) -> use the NEW composed slug, so creation
+ *      stamps the new formula.
+ *
+ * @param {string} cwd
+ * @param {string} project
+ * @param {object} opts - { version, name, multiProject }
+ * @returns {string}
+ */
+function resolveMilestoneSlug(cwd, project, opts) {
+  opts = opts || {};
+  const newSlug = composeMilestoneSlug({
+    version: opts.version,
+    name: opts.name,
+    project: project,
+    multiProject: opts.multiProject,
+  });
+
+  if (_getWorktreeState(cwd, project, newSlug)) return newSlug;
+
+  // Legacy fallback: the OLD bare-name formula, sanitized identically to how
+  // historical keys were derived.
+  const oldSlug = _sanitizeSlug(generateSlugInternal(opts.name || '') || '');
+  if (oldSlug && _getWorktreeState(cwd, project, oldSlug)) return oldSlug;
+
+  return newSlug;
+}
+
 /**
  * Detect collision and disambiguate path if needed.
  * @param {string} targetPath
@@ -269,6 +341,13 @@ function cmdWorktreesCreate(cwd, args) {
   const repoIdx = args.indexOf('--repo');
   const repoFilter = repoIdx !== -1 ? args[repoIdx + 1] : null;
 
+  // Ad-hoc milestone container markers (Phase 159, ADH-04 mirror + ADH-06).
+  // Additive: only stamped on the entry when present, so non-adhoc worktree
+  // entries stay clean. Wired together by the new-milestone --adhoc branch.
+  const isAdhoc = args.includes('--adhoc');
+  const baseRefIdx = args.indexOf('--base-ref');
+  const adhocBaseRef = baseRefIdx !== -1 ? args[baseRefIdx + 1] : null;
+
   // Load config
   const config = loadConfig(cwd);
   const project = config.current_project;
@@ -350,6 +429,16 @@ function cmdWorktreesCreate(cwd, args) {
       mode: mode,
       setup_complete: setupComplete,
       milestone_version: milestoneVersion,
+      // Stamp the structural-slug formula on milestone entries so the runtime
+      // resolver (resolveMilestoneSlug) prefers the stamped key over recomputing
+      // from the name. Only present on milestone-type entries; quick entries
+      // stay clean.
+      ...(type === 'milestone' ? { milestone_slug: slug, slug_formula: 'v2' } : {}),
+      // Ad-hoc markers (Phase 159): re-passed each repo iteration so they
+      // survive the multi-repo merge in _setWorktreeState (which only
+      // special-cases `repos`). Idempotent and only present when set.
+      ...(isAdhoc ? { adhoc: true } : {}),
+      ...(adhocBaseRef ? { adhoc_base_ref: adhocBaseRef } : {}),
       repos: { [repo.name]: worktreePath },
     });
 
@@ -724,12 +813,24 @@ function rebaseAndMerge(cwd, repoName, slug, options) {
     }
   }
 
+  // Step 6: Delete the owned remote milestone branch (SUCCESS path only).
+  // This reclaims the milestone/<slug> name on origin so a future milestone
+  // cannot collide with a lingering squatting branch. A delete failure (e.g.
+  // no remote branch, offline) is a NON-FATAL warning and never changes the
+  // completion result. Never runs on a conflicted/failed merge.
+  const delRemote = execGit(mainCheckout, ['push', 'origin', '--delete', branchName]);
+  const remoteBranchDeleted = delRemote.exitCode === 0;
+  if (!remoteBranchDeleted) {
+    process.stderr.write('Warning: failed to delete remote ' + branchName + ': ' + delRemote.stderr + '\n');
+  }
+
   return {
     success: true,
     merged: true,
     skipped: rebaseSkipped,
     conflicted: false,
     pushed: pushed,
+    remoteBranchDeleted: remoteBranchDeleted,
   };
 }
 
@@ -779,6 +880,83 @@ function checkWorktreeHealth(cwd, slug) {
   return { healthy: issues.length === 0, issues: issues };
 }
 
+/**
+ * Pre-flight check for a remote milestone-branch collision.
+ *
+ * For each repo in REPOS.md, fetch origin (best-effort), then check whether
+ * `refs/remotes/origin/milestone/<slug>` exists with commits NOT reachable from
+ * base_branch (i.e. unmerged work squatting the milestone name). Used by the
+ * run-job pre-flight guard to REFUSE starting a job that would collide.
+ *
+ * Never throws — degrades to `{ collision:false, ... }` on any git error.
+ *
+ * @param {string} cwd - Planning root
+ * @param {string} slug - Milestone slug
+ * @returns {{ collision: boolean, branch: string, repos: Array<{name:string, exists:boolean, unmergedCount:number}>, message: string }}
+ */
+function checkRemoteCollision(cwd, slug) {
+  const branch = 'milestone/' + slug;
+  const empty = { collision: false, branch: branch, repos: [], message: '' };
+
+  let config;
+  try {
+    config = loadConfig(cwd);
+  } catch {
+    return empty;
+  }
+  const baseBranch = (config && config.base_branch) || 'main';
+
+  let parsed;
+  try {
+    parsed = parseReposMd(cwd);
+  } catch {
+    return empty;
+  }
+  const repos = (parsed && parsed.repos) ? parsed.repos : [];
+
+  const repoResults = [];
+  const collidingRepos = [];
+
+  for (const repo of repos) {
+    let mainCheckout;
+    try {
+      mainCheckout = _findMainCheckoutPath(cwd, repo.name);
+    } catch {
+      mainCheckout = null;
+    }
+    if (!mainCheckout || !fs.existsSync(mainCheckout)) {
+      repoResults.push({ name: repo.name, exists: false, unmergedCount: 0 });
+      continue;
+    }
+
+    // Best-effort fetch — ignore failure (offline, no remote, etc.).
+    execGit(mainCheckout, ['fetch', 'origin']);
+
+    const remoteRef = 'refs/remotes/origin/' + branch;
+    const verify = execGit(mainCheckout, ['rev-parse', '--verify', '--quiet', remoteRef]);
+    const exists = verify.exitCode === 0 && !!(verify.stdout || '').trim();
+    if (!exists) {
+      repoResults.push({ name: repo.name, exists: false, unmergedCount: 0 });
+      continue;
+    }
+
+    // Count commits on the remote milestone branch not reachable from base_branch.
+    const countRes = execGit(mainCheckout, ['rev-list', '--count', baseBranch + '..origin/' + branch]);
+    const unmergedCount = countRes.exitCode === 0 ? parseInt((countRes.stdout || '0').trim(), 10) || 0 : 0;
+    repoResults.push({ name: repo.name, exists: true, unmergedCount: unmergedCount });
+    if (unmergedCount > 0) collidingRepos.push(repo.name);
+  }
+
+  const collision = collidingRepos.length > 0;
+  const message = collision
+    ? 'Remote branch ' + branch + ' already exists with unmerged commits in: ' +
+      collidingRepos.join(', ') + '. Merge or delete it before starting this job ' +
+      '(e.g. git push origin --delete ' + branch + '), then re-run.'
+    : '';
+
+  return { collision: collision, branch: branch, repos: repoResults, message: message };
+}
+
 module.exports = {
   cmdWorktreesCreate,
   cmdWorktreesRemove,
@@ -787,4 +965,7 @@ module.exports = {
   cmdWorktreesPrune,
   rebaseAndMerge,
   checkWorktreeHealth,
+  composeMilestoneSlug,
+  resolveMilestoneSlug,
+  checkRemoteCollision,
 };