@ktpartners/dgs-platform 2.9.0 → 3.3.0

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

@@ -550,16 +550,13 @@ function cmdValidateHealth(cwd, options, raw) {
     return;
   }
 
-  // ─── Check 2: PROJECT.md exists and has required sections ─────────────────
+  // ─── Check 2: PROJECT.md exists and has a heading ────────────────────────
   if (!fs.existsSync(projectPath)) {
     addIssue('error', 'E002', 'PROJECT.md not found', 'Run /dgs:new-project to create');
   } else {
     const content = fs.readFileSync(projectPath, 'utf-8');
-    const requiredSections = ['## What This Is', '## Core Value', '## Requirements'];
-    for (const section of requiredSections) {
-      if (!content.includes(section)) {
-        addIssue('warning', 'W001', `PROJECT.md missing section: ${section}`, 'Add section manually');
-      }
+    if (!/^#\s+\S/m.test(content)) {
+      addIssue('warning', 'W001', 'PROJECT.md missing top-level heading', 'Add a # Title line');
     }
   }
 
@@ -708,6 +705,201 @@ function cmdValidateHealth(cwd, options, raw) {
     }
   }
 
+  // ─── Check 10: Uncommitted tracking files in completed phases ─────────────
+  // Surface the condition `phase finalize` was designed to prevent: a completed
+  // phase whose ROADMAP.md / STATE.md / REQUIREMENTS.md / VERIFICATION.md are
+  // modified in the working tree but not committed (e.g., Claude dropped the
+  // commit step between updating trackers and invoking `commit`).
+  try {
+    const { execGit } = require('./core.cjs');
+    const isGit = execGit(cwd, ['rev-parse', '--is-inside-work-tree']);
+    if (isGit.exitCode === 0 && isGit.stdout.trim() === 'true') {
+      // git resolves symlinks when reporting paths; normalize both sides against
+      // the real git root so relative paths compare correctly on macOS
+      // (/var/folders → /private/var/folders).
+      const gitRootRes = execGit(cwd, ['rev-parse', '--show-toplevel']);
+      const gitRoot = gitRootRes.exitCode === 0 ? gitRootRes.stdout.trim() : cwd;
+      const statusRes = execGit(cwd, ['status', '--porcelain']);
+      if (statusRes.exitCode === 0) {
+        // `git status --porcelain` emits "XY path" lines (X=index, Y=worktree,
+        // column 3 is a separator space, path starts at column 4). Note:
+        // execGit.stdout is already .trim()'d so lines may have lost a leading
+        // space when X=' ' (worktree-only changes). Extract the path from
+        // whatever follows the first whitespace group.
+        const dirtyPaths = statusRes.stdout
+          .split('\n')
+          .filter(Boolean)
+          .map(l => {
+            // Match "XY<space>path" OR "<space>Y<space>path" (leading space may be trimmed).
+            // A path after 2 status chars + 1 space begins at index 3 of the original,
+            // but lines like " M file" got left-trimmed to "M file" (only one status char).
+            // Normalize: skip the leading non-space + exactly one space.
+            const m = l.match(/^\S{1,2}\s(.+)$/);
+            return m ? m[1].trim() : l.trim();
+          });
+
+        // Identify completed phases from ROADMAP.md checkboxes
+        const completedPhases = new Set();
+        if (fs.existsSync(roadmapPath)) {
+          const rm = fs.readFileSync(roadmapPath, 'utf-8');
+          const re = /-\s*\[x\]\s*.*Phase\s+(\d+[A-Z]?(?:\.\d+)*)/gi;
+          let m;
+          while ((m = re.exec(rm)) !== null) completedPhases.add(m[1]);
+        }
+
+        // Tracking files at the planning root — compute relative to gitRoot
+        const trackingRoot = ['ROADMAP.md', 'STATE.md', 'REQUIREMENTS.md']
+          .map(f => path.relative(gitRoot, path.join(planningDir, f)));
+
+        // VERIFICATION.md files inside completed phase dirs
+        const trackingVerif = [];
+        if (completedPhases.size > 0) {
+          try {
+            const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+            for (const e of entries) {
+              if (!e.isDirectory()) continue;
+              const dm = e.name.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
+              if (!dm) continue;
+              const phaseNum = dm[1];
+              const unpadded = String(parseInt(phaseNum, 10));
+              if (!completedPhases.has(phaseNum) && !completedPhases.has(unpadded)) continue;
+              const phaseFiles = fs.readdirSync(path.join(phasesDir, e.name));
+              for (const f of phaseFiles) {
+                if (/-VERIFICATION\.md$/i.test(f)) {
+                  trackingVerif.push(path.relative(gitRoot, path.join(phasesDir, e.name, f)));
+                }
+              }
+            }
+          } catch { /* ignore */ }
+        }
+
+        const allTracking = [...trackingRoot, ...trackingVerif];
+        const dirtyTracking = dirtyPaths.filter(p => allTracking.includes(p));
+        if (dirtyTracking.length > 0) {
+          addIssue('warning', 'W009',
+            `Uncommitted tracking files for completed phase(s): ${dirtyTracking.join(', ')}`,
+            'Run `dgs-tools phase finalize <phase>` for the relevant phase, or commit manually'
+          );
+        }
+      }
+    }
+  } catch { /* non-git or git error — skip silently */ }
+
+  // ─── Check 11: Untracked scaffolding (.gitkeep) — REL-12 ────────────────
+  // Walks planning root for `.gitkeep` files in standard scaffold locations
+  // (specs/, docs/product/, quick/, projects/*/{phases,quick,debug,research}/)
+  // and warns if any exist on disk but aren't tracked in git. User-facing analog
+  // of REL-09 (init-product .gitkeep commit) — REL-09 prevented the leak,
+  // REL-12 catches any reintroduction immediately on the next health-check run.
+  try {
+    const { execGit } = require('./core.cjs');
+    const isGitWT = (() => {
+      try {
+        const res = execGit(cwd, ['rev-parse', '--is-inside-work-tree']);
+        return res && res.exitCode === 0 && (res.stdout || '').trim() === 'true';
+      } catch { return false; }
+    })();
+
+    if (isGitWT) {
+      const candidates = [];
+
+      // Direct scaffold locations under planning root
+      const directDirs = ['specs', 'docs/product', 'quick'];
+      for (const d of directDirs) {
+        const p = path.join(planningDir, d, '.gitkeep');
+        if (fs.existsSync(p)) candidates.push(path.join(d, '.gitkeep'));
+      }
+
+      // Per-project scaffold locations: projects/*/{phases,quick,debug,research}/.gitkeep
+      const projectsDir = path.join(planningDir, 'projects');
+      if (fs.existsSync(projectsDir)) {
+        try {
+          const projects = fs.readdirSync(projectsDir, { withFileTypes: true });
+          for (const proj of projects) {
+            if (!proj.isDirectory()) continue;
+            for (const sub of ['phases', 'quick', 'debug', 'research']) {
+              const p = path.join(planningDir, 'projects', proj.name, sub, '.gitkeep');
+              if (fs.existsSync(p)) {
+                candidates.push(path.join('projects', proj.name, sub, '.gitkeep'));
+              }
+            }
+          }
+        } catch { /* ignore */ }
+      }
+
+      // For each candidate, check whether it's tracked in git via
+      // `git ls-files <rel>` — empty stdout means untracked.
+      const untracked = [];
+      for (const rel of candidates) {
+        const lsResult = execGit(cwd, ['ls-files', '--', rel]);
+        const tracked = lsResult && lsResult.exitCode === 0 && (lsResult.stdout || '').trim().length > 0;
+        if (!tracked) untracked.push(rel);
+      }
+
+      if (untracked.length > 0) {
+        addIssue(
+          'warning',
+          'untracked-scaffolding',
+          `Found ${untracked.length} untracked .gitkeep file(s) in standard scaffold locations: ${untracked.join(', ')}`,
+          `Run 'git add ${untracked.join(' ')} && git commit -m "docs: track scaffolding files"' to commit them; closes idea #29 (init-product .gitkeep leak) on the next health-check run.`,
+          false
+        );
+      }
+    }
+  } catch { /* non-git or git error — skip silently per existing convention */ }
+
+  // ─── Check 12: untracked-phase-artifacts (REL-11, Phase 156) ───────────────
+  // Walk every phase directory under projects/<project>/phases/ (or
+  // top-level phases/ in v1) and report any uncommitted PLAN.md /
+  // CONTEXT.md / RESEARCH.md / UAT.md / VERIFICATION.md files. This is
+  // the loud-fail safety net for REL-01 / REL-02 — if either of those
+  // commit-step contracts ever regresses, this health check surfaces
+  // the dangling artifact on the next /dgs:health run.
+  try {
+    const untracked = [];
+    if (fs.existsSync(phasesDir)) {
+      const ARTIFACT_RE = /^[0-9].*-(PLAN|CONTEXT|RESEARCH|UAT|VERIFICATION)\.md$/;
+      const phaseEntries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      for (const entry of phaseEntries) {
+        if (!entry.isDirectory()) continue;
+        const phaseDirAbs = path.join(phasesDir, entry.name);
+        let files;
+        try { files = fs.readdirSync(phaseDirAbs); } catch { continue; }
+        for (const f of files) {
+          if (!ARTIFACT_RE.test(f)) continue;
+          const absPath = path.join(phaseDirAbs, f);
+          const relPath = path.relative(planningDir, absPath);
+          // `git ls-files -- <relPath>` returns the path if tracked,
+          // empty string if untracked. Run with cwd = planningDir so
+          // the relative path resolves correctly.
+          const lsResult = execGit(planningDir, ['ls-files', '--', relPath]);
+          const tracked = lsResult.exitCode === 0 && (lsResult.stdout || '').trim().length > 0;
+          if (!tracked) untracked.push(relPath);
+        }
+      }
+    }
+    if (untracked.length > 0) {
+      const remediation =
+        `Run 'node $TOOLS commit "docs: catch up untracked phase artifacts" --files ${untracked.join(' ')}' ` +
+        `or run /dgs:health --repair`;
+      addIssue(
+        'warning',
+        'W010',
+        `untracked-phase-artifacts: ${untracked.length} uncommitted phase artifact(s) — ${untracked.join(', ')}`,
+        remediation,
+        false
+      );
+    }
+  } catch (err) {
+    addIssue(
+      'warning',
+      'W011',
+      `untracked-phase-artifacts check failed: ${err.message}`,
+      'Investigate verify.cjs walker',
+      false
+    );
+  }
+
   // ─── Perform repairs if requested ─────────────────────────────────────────
   const repairActions = [];
   if (options.repair && repairs.length > 0) {
@@ -720,7 +912,6 @@ function cmdValidateHealth(cwd, options, raw) {
               model_profile: 'balanced',
               commit_docs: true,
               search_gitignored: false,
-              branching_strategy: 'none',
               research: true,
               plan_checker: true,
               verifier: true,

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

@@ -0,0 +1,82 @@
+// deliver-great-systems/bin/lib/verify.test.cjs
+// REL-12 untracked-scaffolding health check — initially RED. Turns GREEN after plan 04
+// adds Check 11 to bin/lib/verify.cjs::cmdValidateHealth.
+
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { execSync } = require('node:child_process');
+
+function setupREL12Fixture({ trackedKeeps, untrackedKeeps }) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'rel12-'));
+  execSync('git init -q', { cwd: root });
+  execSync('git config user.email test@test', { cwd: root });
+  execSync('git config user.name test', { cwd: root });
+  fs.writeFileSync(path.join(root, 'PROJECT.md'),
+    '# Test\n## What This Is\n## Core Value\n## Requirements\n');
+  fs.writeFileSync(path.join(root, 'ROADMAP.md'), '# Roadmap\n');
+  fs.writeFileSync(path.join(root, 'STATE.md'), '# State\n');
+  fs.mkdirSync(path.join(root, 'phases'), { recursive: true });
+  // Create + track requested .gitkeep paths
+  for (const p of trackedKeeps) {
+    fs.mkdirSync(path.join(root, path.dirname(p)), { recursive: true });
+    fs.writeFileSync(path.join(root, p), '');
+    execSync(`git add "${p}"`, { cwd: root });
+  }
+  // Always commit at least PROJECT.md so HEAD exists even when no keeps are tracked
+  execSync('git add PROJECT.md ROADMAP.md STATE.md', { cwd: root });
+  execSync('git commit -q -m "init"', { cwd: root });
+  // Create untracked .gitkeep paths (not added to git)
+  for (const p of untrackedKeeps) {
+    fs.mkdirSync(path.join(root, path.dirname(p)), { recursive: true });
+    fs.writeFileSync(path.join(root, p), '');
+  }
+  return root;
+}
+
+function captureHealthOutput(root) {
+  // cmdValidateHealth calls output() which process.exit(0)s — run in a child
+  // process and capture stdout JSON. Pattern matches health-untracked-phase.test.cjs.
+  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(), `rel12-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, warnings: [] }; }
+  } catch (err) {
+    const out = err.stdout && err.stdout.toString();
+    try { return JSON.parse(out); } catch { return { stdout: out, warnings: [] }; }
+  } finally {
+    try { fs.unlinkSync(shimPath); } catch { /* ignore */ }
+  }
+}
+
+test('REL-12: cmdValidateHealth flags untracked .gitkeep in standard scaffold locations (untracked-scaffolding)', () => {
+  const root = setupREL12Fixture({
+    trackedKeeps: ['specs/.gitkeep'],
+    untrackedKeeps: ['docs/product/.gitkeep', 'quick/.gitkeep'],
+  });
+  const result = captureHealthOutput(root);
+  const scaffoldingWarnings = (result.warnings || []).filter(w => w.code === 'untracked-scaffolding');
+  assert.strictEqual(scaffoldingWarnings.length, 1, 'exactly one untracked-scaffolding warning expected');
+  assert.match(scaffoldingWarnings[0].message, /docs\/product\/\.gitkeep/);
+  assert.match(scaffoldingWarnings[0].message, /quick\/\.gitkeep/);
+});
+
+test('REL-12: cmdValidateHealth does NOT flag tracked .gitkeep files', () => {
+  const root = setupREL12Fixture({
+    trackedKeeps: ['specs/.gitkeep', 'docs/product/.gitkeep', 'quick/.gitkeep'],
+    untrackedKeeps: [],
+  });
+  const result = captureHealthOutput(root);
+  const scaffoldingWarnings = (result.warnings || []).filter(w => w.code === 'untracked-scaffolding');
+  assert.strictEqual(scaffoldingWarnings.length, 0, 'no untracked-scaffolding warning when all keeps tracked');
+});
+
+// REL-12 sentinel — flag this block as a Wave-0 RED scaffold for plan 04.

package/deliver-great-systems/bin/lib/wave-0-template-rename.test.cjs

@@ -0,0 +1,40 @@
+// deliver-great-systems/bin/lib/wave-0-template-rename.test.cjs
+// REL-03 convergence test scaffold — initially RED. Turns GREEN after plan 02
+// lands the planner-prompt edits and the VALIDATION.md template rename.
+
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const repoRoot = path.resolve(__dirname, '../../..');
+const planner = path.join(repoRoot, 'agents/dgs-planner.md');
+const template = path.join(repoRoot, 'deliver-great-systems/templates/VALIDATION.md');
+
+test('REL-03: VALIDATION template uses heading "Wave 0 Task Requirements"', () => {
+  const content = fs.readFileSync(template, 'utf-8');
+  assert.match(content, /## Wave 0 Task Requirements/, 'template must use new heading');
+});
+
+test('REL-03: VALIDATION template no longer uses "Wave 0 Requirements" as a section heading', () => {
+  const content = fs.readFileSync(template, 'utf-8');
+  // The OLD heading must NOT exist as a section heading (paragraph mentions are OK)
+  assert.doesNotMatch(content, /^## Wave 0 Requirements\s*$/m, 'old heading must be gone');
+});
+
+test('REL-03: planner prompt unambiguously states "Plans are numbered starting at 01"', () => {
+  const content = fs.readFileSync(planner, 'utf-8');
+  assert.match(content, /Plans are numbered starting at 01/, 'planner must state plan-numbering rule');
+});
+
+test('REL-03: planner prompt explicitly forbids plan: 00 and wave: 0', () => {
+  const content = fs.readFileSync(planner, 'utf-8');
+  assert.match(content, /Never create a plan with `plan: 00` or `wave: 0`/, 'planner must forbid plan: 00 / wave: 0');
+});
+
+test('REL-03: planner prompt mentions Wave 0 lives as Task 0 inside plan 01', () => {
+  const content = fs.readFileSync(planner, 'utf-8');
+  assert.match(content, /Wave 0 work lives as Task 0 inside plan 01/, 'planner must locate Wave 0 inside plan 01');
+});
+
+// REL-03 sentinel — flag this file as a Wave-0 RED scaffold for plan 02.