@ktpartners/dgs-platform 3.0.4 → 3.3.0

package/deliver-great-systems/bin/lib/health-untracked-phase.test.cjs

@@ -0,0 +1,269 @@
+/**
+ * RED test scaffold for REL-11 (Phase 156 plan 04).
+ *
+ * The cmdValidateHealth extension is implemented in plan 04; running
+ * this file before plan 04 lands MUST produce 6 failed tests with
+ * 'not yet implemented — REL-11' style messages.
+ *
+ * Behaviour under test:
+ *   - untracked PLAN.md detection: warning entry references the file
+ *   - untracked CONTEXT.md, RESEARCH.md, UAT.md, VERIFICATION.md: a
+ *     warning entry that lists all four file paths
+ *   - clean phase dir: zero warnings about untracked-phase-artifacts
+ *   - multiple phase dirs: walks all phases under projects/<project>/phases/
+ *   - non-artifact files (README.md, .DS_Store): not reported
+ *   - fix message references a remediation command (dgs-tools commit
+ *     OR /dgs:health --repair)
+ *
+ * Conventions:
+ *   - Uses node:test runner + node:assert (matches state-transition-gate.test.cjs)
+ *   - Each test creates and tears down its own temp planning root via os.tmpdir()
+ *   - Until plan 04 lands, every test fails with 'not yet implemented'
+ *     so the file is RED in a controlled way (no parse errors).
+ */
+
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const NOT_IMPL = 'untracked-phase-artifacts check not yet implemented — REL-11';
+
+// ─── Helpers ──────────────────────────────────────────────────────────────
+
+function tryRequireVerify() {
+  try {
+    return require('./verify.cjs');
+  } catch (err) {
+    return null;
+  }
+}
+
+function makePlanningRoot() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'health-rel11-test-'));
+  execSync('git init --quiet', { cwd: dir });
+  execSync('git config user.email test@example.com', { cwd: dir });
+  execSync('git config user.name "Test User"', { cwd: dir });
+  // Minimum required scaffolding so existing checks don't error out
+  fs.mkdirSync(path.join(dir, 'phases'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'PROJECT.md'), '# project\n## What This Is\n## Core Value\n## Requirements\n');
+  fs.writeFileSync(path.join(dir, 'ROADMAP.md'), '# roadmap\n');
+  fs.writeFileSync(path.join(dir, 'STATE.md'), '# state\n');
+  fs.writeFileSync(path.join(dir, 'config.json'), JSON.stringify({ commit_docs: true }, null, 2));
+  // Initial commit so HEAD exists
+  execSync('git add -A', { cwd: dir });
+  execSync('git commit --quiet -m "seed"', { cwd: dir });
+  return dir;
+}
+
+function cleanupRoot(dir) {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+}
+
+function writeAndOptionallyTrack(root, rel, content, track) {
+  const abs = path.join(root, rel);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, content);
+  if (track) {
+    execSync(`git add "${rel}"`, { cwd: root });
+    execSync(`git commit --quiet -m "track ${rel}"`, { cwd: root });
+  }
+}
+
+function callValidateHealth(root) {
+  const verify = tryRequireVerify();
+  if (!verify || typeof verify.cmdValidateHealth !== 'function') return null;
+  // Capture the result by stubbing output() through raw mode. Since
+  // cmdValidateHealth calls output() which calls process.exit, we run
+  // it in a child process and capture stdout JSON.
+  //
+  // We write the shim to a tmp file rather than passing via -e, because
+  // shell-escaping a path that may contain spaces or quotes plus the
+  // raw arg is fragile. A tmp .cjs file is unambiguous.
+  const verifyPath = path.resolve(__dirname, 'verify.cjs');
+  const shim = [
+    `const v = require(${JSON.stringify(verifyPath)});`,
+    `v.cmdValidateHealth(${JSON.stringify(root)}, { raw: true }, true);`,
+  ].join('\n');
+  const shimPath = path.join(os.tmpdir(), `rel11-shim-${process.pid}-${Date.now()}.cjs`);
+  fs.writeFileSync(shimPath, shim);
+  try {
+    const stdout = execSync(`node ${JSON.stringify(shimPath)}`, { encoding: 'utf-8' });
+    try { return JSON.parse(stdout); } catch { return { stdout }; }
+  } catch (err) {
+    return { error: err.message, stdout: err.stdout && err.stdout.toString() };
+  } finally {
+    try { fs.unlinkSync(shimPath); } catch { /* ignore */ }
+  }
+}
+
+// ─── Test 1: untracked PLAN.md detection ──────────────────────────────────
+
+test('REL-11 untracked PLAN.md detection: returns untracked-phase-artifacts entry listing the file', () => {
+  const verify = tryRequireVerify();
+  if (!verify || typeof verify.cmdValidateHealth !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makePlanningRoot();
+  try {
+    // tracked CONTEXT.md, untracked PLAN.md
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-CONTEXT.md', '# ctx\n', true);
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-01-PLAN.md', '# plan\n', false);
+    const result = callValidateHealth(root);
+    if (!result || !Array.isArray(result.warnings)) {
+      assert.fail(NOT_IMPL);
+      return;
+    }
+    const hit = result.warnings.find(w =>
+      (w.message || '').includes('untracked-phase-artifacts') &&
+      (w.message || '').includes('100-01-PLAN.md')
+    );
+    assert.ok(hit, 'expected an untracked-phase-artifacts warning referencing 100-01-PLAN.md');
+  } finally {
+    cleanupRoot(root);
+  }
+});
+
+// ─── Test 2: untracked CONTEXT/RESEARCH/UAT/VERIFICATION ─────────────────
+
+test('REL-11 untracked CONTEXT.md, RESEARCH.md, UAT.md, VERIFICATION.md detection (one of each)', () => {
+  const verify = tryRequireVerify();
+  if (!verify || typeof verify.cmdValidateHealth !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makePlanningRoot();
+  try {
+    // All four artifacts untracked
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-CONTEXT.md', 'a\n', false);
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-RESEARCH.md', 'b\n', false);
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-UAT.md', 'c\n', false);
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-VERIFICATION.md', 'd\n', false);
+    const result = callValidateHealth(root);
+    if (!result || !Array.isArray(result.warnings)) {
+      assert.fail(NOT_IMPL);
+      return;
+    }
+    const hit = result.warnings.find(w => (w.message || '').includes('untracked-phase-artifacts'));
+    assert.ok(hit, 'expected an untracked-phase-artifacts warning');
+    for (const f of ['100-CONTEXT.md', '100-RESEARCH.md', '100-UAT.md', '100-VERIFICATION.md']) {
+      assert.ok((hit.message || '').includes(f), `warning message must include ${f}`);
+    }
+  } finally {
+    cleanupRoot(root);
+  }
+});
+
+// ─── Test 3: clean phase dir → no warning ─────────────────────────────────
+
+test('REL-11 clean phase dir: all artifacts tracked yields no untracked-phase-artifacts entry', () => {
+  const verify = tryRequireVerify();
+  if (!verify || typeof verify.cmdValidateHealth !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makePlanningRoot();
+  try {
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-CONTEXT.md', 'a\n', true);
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-01-PLAN.md', 'b\n', true);
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-RESEARCH.md', 'c\n', true);
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-UAT.md', 'd\n', true);
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-VERIFICATION.md', 'e\n', true);
+    const result = callValidateHealth(root);
+    if (!result || !Array.isArray(result.warnings)) {
+      assert.fail(NOT_IMPL);
+      return;
+    }
+    const hit = result.warnings.find(w => (w.message || '').includes('untracked-phase-artifacts'));
+    assert.strictEqual(hit, undefined, 'no untracked-phase-artifacts warning expected when all tracked');
+  } finally {
+    cleanupRoot(root);
+  }
+});
+
+// ─── Test 4: multiple phase dirs ──────────────────────────────────────────
+
+test('REL-11 multiple phase dirs: walks all phases under projects/<current>/phases/', () => {
+  const verify = tryRequireVerify();
+  if (!verify || typeof verify.cmdValidateHealth !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makePlanningRoot();
+  try {
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-01-PLAN.md', 'a\n', false);
+    writeAndOptionallyTrack(root, 'phases/101-bar/101-CONTEXT.md', 'b\n', false);
+    writeAndOptionallyTrack(root, 'phases/102-baz/102-VERIFICATION.md', 'c\n', false);
+    const result = callValidateHealth(root);
+    if (!result || !Array.isArray(result.warnings)) {
+      assert.fail(NOT_IMPL);
+      return;
+    }
+    const hit = result.warnings.find(w => (w.message || '').includes('untracked-phase-artifacts'));
+    assert.ok(hit, 'expected an untracked-phase-artifacts warning');
+    assert.ok((hit.message || '').includes('100-01-PLAN.md'));
+    assert.ok((hit.message || '').includes('101-CONTEXT.md'));
+    assert.ok((hit.message || '').includes('102-VERIFICATION.md'));
+  } finally {
+    cleanupRoot(root);
+  }
+});
+
+// ─── Test 5: non-artifact files not reported ──────────────────────────────
+
+test('REL-11 non-artifact files (e.g., a .DS_Store or some-other.md inside phases/100/) are NOT reported', () => {
+  const verify = tryRequireVerify();
+  if (!verify || typeof verify.cmdValidateHealth !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makePlanningRoot();
+  try {
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-CONTEXT.md', 'a\n', true);
+    writeAndOptionallyTrack(root, 'phases/100-foo/README.md', 'r\n', false);
+    writeAndOptionallyTrack(root, 'phases/100-foo/.DS_Store', 'x\n', false);
+    const result = callValidateHealth(root);
+    if (!result || !Array.isArray(result.warnings)) {
+      assert.fail(NOT_IMPL);
+      return;
+    }
+    const hit = result.warnings.find(w => (w.message || '').includes('untracked-phase-artifacts'));
+    if (hit) {
+      assert.ok(!(hit.message || '').includes('README.md'), 'README.md must NOT be reported');
+      assert.ok(!(hit.message || '').includes('.DS_Store'), '.DS_Store must NOT be reported');
+    }
+    // If no untracked-phase-artifacts warning at all, that's also acceptable
+    // (only PLAN/CONTEXT/RESEARCH/UAT/VERIFICATION are checked).
+  } finally {
+    cleanupRoot(root);
+  }
+});
+
+// ─── Test 6: fix message references a remediation command ────────────────
+
+test('REL-11 fix message includes a remediation command', () => {
+  const verify = tryRequireVerify();
+  if (!verify || typeof verify.cmdValidateHealth !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makePlanningRoot();
+  try {
+    writeAndOptionallyTrack(root, 'phases/100-foo/100-01-PLAN.md', 'a\n', false);
+    const result = callValidateHealth(root);
+    if (!result || !Array.isArray(result.warnings)) {
+      assert.fail(NOT_IMPL);
+      return;
+    }
+    const hit = result.warnings.find(w => (w.message || '').includes('untracked-phase-artifacts'));
+    assert.ok(hit, 'expected an untracked-phase-artifacts warning');
+    const fix = hit.fix || '';
+    const refs = fix.includes('dgs-tools commit') || fix.includes('/dgs:health --repair');
+    assert.ok(refs, `fix message should reference 'dgs-tools commit' OR '/dgs:health --repair' (got: ${fix})`);
+  } finally {
+    cleanupRoot(root);
+  }
+});

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

@@ -10,7 +10,7 @@ const { requireGitIdentity, formatAuthorString } = require('./identity.cjs');
 const { getPlanningRoot, PROJECTS_DIR } = require('./paths.cjs');
 const { parseReposMd, validateReposMdEager } = require('./repos.cjs');
 const { getCadence, pullAll } = require('./sync.cjs');
-const { detectQuickMode } = require('./quick.cjs');
+const { detectQuickMode, generateQuickId, getActiveQuick } = require('./quick.cjs');
 const { listProjectsReadonly } = require('./projects.cjs');
 
 /**
@@ -384,12 +384,28 @@ function cmdInitPlanPhase(cwd, phase, raw) {
   output(result, raw);
 }
 
-function cmdInitNewProject(cwd, raw) {
+function cmdInitNewProject(cwd, slugArg, raw) {
   const config = loadConfig(cwd);
   const ctx = resolveProjectContext(cwd);
   const planRootRel = path.relative(cwd, getPlanningRoot(cwd)) || '.';
   const milestone = getMilestoneInfo(cwd);
 
+  // Resolve slug override (optional positional arg from CLI).
+  // When supplied AND we're on a v2 install, override the per-slug paths
+  // so `init new-project <slug>` reflects whether THAT slug exists,
+  // independent of the currently active project. v1 mode silently falls
+  // back to ctx.root behaviour because v1 has no projects/<slug>/ layout.
+  let effectiveRoot = ctx.root;
+  let slugOverride = null;
+  if (slugArg && typeof slugArg === 'string' && slugArg.trim()) {
+    const candidate = generateSlugInternal(slugArg.trim());
+    if (candidate && isV2Install(cwd)) {
+      slugOverride = candidate;
+      effectiveRoot = path.join(planRootRel, 'projects', slugOverride);
+    }
+  }
+  const rootForPaths = effectiveRoot;
+
   // Detect Brave Search API key availability
   const homedir = require('os').homedir();
   const braveKeyFile = path.join(homedir, '.dgs', 'brave_api_key');
@@ -426,8 +442,8 @@ function cmdInitNewProject(cwd, raw) {
     cadence_pull: getCadence('new-project').pull,
     cadence_push: getCadence('new-project').push,
 
-    // Existing state (project-qualified)
-    project_exists: ctx.root ? pathExistsInternal(cwd, path.join(ctx.root, 'PROJECT.md')) : pathExistsInternal(cwd, path.join(planRootRel, 'PROJECT.md')),
+    // Existing state (project-qualified, slug-override aware)
+    project_exists: rootForPaths ? pathExistsInternal(cwd, path.join(rootForPaths, 'PROJECT.md')) : pathExistsInternal(cwd, path.join(planRootRel, 'PROJECT.md')),
     has_codebase_map: pathExistsInternal(cwd, path.join(planRootRel, 'codebase')),
     planning_exists: pathExistsInternal(cwd, planRootRel),
 
@@ -446,12 +462,12 @@ function cmdInitNewProject(cwd, raw) {
     // Enhanced search
     brave_search_available: hasBraveSearch,
 
-    // File paths (project-qualified)
-    project_path: ctx.root ? path.join(ctx.root, 'PROJECT.md') : path.join(planRootRel, 'PROJECT.md'),
-    state_path: ctx.root ? path.join(ctx.root, 'STATE.md') : path.join(planRootRel, 'STATE.md'),
-    roadmap_path: ctx.root ? path.join(ctx.root, 'ROADMAP.md') : path.join(planRootRel, 'ROADMAP.md'),
-    requirements_path: ctx.root ? path.join(ctx.root, 'REQUIREMENTS.md') : path.join(planRootRel, 'REQUIREMENTS.md'),
-    research_dir: ctx.root ? path.join(ctx.root, 'research') : path.join(planRootRel, 'research'),
+    // File paths (project-qualified, slug-override aware)
+    project_path: rootForPaths ? path.join(rootForPaths, 'PROJECT.md') : path.join(planRootRel, 'PROJECT.md'),
+    state_path: rootForPaths ? path.join(rootForPaths, 'STATE.md') : path.join(planRootRel, 'STATE.md'),
+    roadmap_path: rootForPaths ? path.join(rootForPaths, 'ROADMAP.md') : path.join(planRootRel, 'ROADMAP.md'),
+    requirements_path: rootForPaths ? path.join(rootForPaths, 'REQUIREMENTS.md') : path.join(planRootRel, 'REQUIREMENTS.md'),
+    research_dir: rootForPaths ? path.join(rootForPaths, 'research') : path.join(planRootRel, 'research'),
 
     // Milestone info (product-level, shared across projects)
     milestone_version: milestone.version,
@@ -460,7 +476,13 @@ function cmdInitNewProject(cwd, raw) {
     // v2 context
     dgs_mode: ctx.dgs_mode,
     current_project: ctx.current_project,
-    project_root: ctx.root,
+    // project_root reflects override when a slug arg is supplied (so the
+    // workflow can write directly to the requested project's folder), otherwise
+    // it still reports the active project root.
+    project_root: rootForPaths,
+    // requested_slug: the normalized slug arg (or null when no slug arg / v1 fallback).
+    // The workflow uses this to distinguish "active project" from "requested project".
+    requested_slug: slugOverride,
     guard: ctx.guard,
     v2_hint: ctx.v2_hint || null,
   };
@@ -503,6 +525,10 @@ function cmdInitNewMilestone(cwd, raw) {
     roadmap_path: ctx.root ? path.join(ctx.root, 'ROADMAP.md') : path.join(planRootRel, 'ROADMAP.md'),
     state_path: ctx.root ? path.join(ctx.root, 'STATE.md') : path.join(planRootRel, 'STATE.md'),
 
+    // Product-level MILESTONES.md (authoritative for global version/phase continuity across projects)
+    product_milestones_path: path.join(planRootRel, 'MILESTONES.md'),
+    product_milestones_exists: pathExistsInternal(cwd, path.join(planRootRel, 'MILESTONES.md')),
+
     // Author
     author: resolveAuthorSafe(cwd),
 
@@ -527,30 +553,33 @@ function cmdInitQuick(cwd, description, raw) {
   // Parse --main flag out of description string
   const forceMain = /\s*--main\s*/.test(description || '');
   const cleanDescription = (description || '').replace(/\s*--main\s*/g, ' ').trim() || null;
-  const slug = cleanDescription ? generateSlugInternal(cleanDescription)?.substring(0, 40).replace(/-+$/, '') : null;
+
+  // Hoist getActiveQuick lookup so both `slug` and `quickId` derive from
+  // the same canonical source (the worktree slug stored in config.local.json).
+  // The worktree slug has already been truncated to 50 chars by worktrees.cjs;
+  // re-sanitising the description here would produce a divergent (51-char)
+  // descSlug, leaving an orphan directory on disk after every quick task.
+  // See: bug 260428-k7f.
+  const activeQuick = getActiveQuick(cwd);
+  const hasActiveQuickSlug = activeQuick && /^\d{6}-[a-z0-9]{3}-/.test(activeQuick.slug);
+
+  const slug = hasActiveQuickSlug
+    ? activeQuick.slug.slice(11)  // strip "{quickId}-" prefix (10 chars + 1 dash)
+    : (cleanDescription ? generateSlugInternal(cleanDescription)?.substring(0, 40).replace(/-+$/, '') : null);
 
   // Detect quick mode: product-level vs milestone-context
   const quickMode = detectQuickMode(cwd, forceMain);
 
-  // Generate collision-resistant quick task ID: YYMMDD-xxx
-  // xxx = 2-second precision blocks since midnight, encoded as 3-char Base36 (lowercase)
-  // Range: 000 (00:00:00) to xbz (23:59:58), guaranteed 3 chars for any time of day.
-  // Provides ~2s uniqueness window per user — practically collision-free across a team.
-  // Branch path resolution by quickMode: product-level quicks (including --main
-  // override) land at the planning root; milestone-context quicks stay under the
-  // active project. This keeps product-level work out of project state.
+  // Quick task ID: YYMMDD-xxx. For product-level quicks with an active worktree,
+  // extract the quickId from the worktree slug (startProductQuick embeds it as the
+  // prefix). For fast mode and milestone-context, generate a fresh one.
   const isProductMode = quickMode.mode === 'product';
   const quickBase = isProductMode
     ? path.join(planRootRel, 'quick')
     : (ctx.root ? path.join(ctx.root, 'quick') : path.join(planRootRel, 'quick'));
-  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');
-  const quickId = dateStr + '-' + timeEncoded;
+  const quickId = hasActiveQuickSlug
+    ? activeQuick.slug.slice(0, 10)
+    : generateQuickId(now);
 
   // Auto-create product-level STATE.md on demand (matches project STATE.md
   // auto-creation behavior elsewhere). Keep skeleton minimal — the /dgs:quick