@ktpartners/dgs-platform 3.0.4 → 3.3.0

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

@@ -678,7 +678,10 @@ function buildStateFrontmatter(bodyContent, cwd) {
     normalizedStatus = 'discussing';
   } else if (statusLower.includes('verif')) {
     normalizedStatus = 'verifying';
-  } else if (statusLower.includes('complete') || statusLower.includes('done')) {
+  } else if (statusLower === 'completed' || statusLower === 'done' || statusLower === 'project completed') {
+    // Only exact matches trigger 'completed' — "Phase X execution complete" or
+    // "Milestone shipped" should NOT mark the project as completed.
+    // Project completion is a manual action via /dgs:complete-project.
     normalizedStatus = 'completed';
   } else if (statusLower.includes('ready to execute')) {
     normalizedStatus = 'executing';
@@ -919,8 +922,9 @@ function markMilestoneComplete(cwd) {
   const today = new Date().toISOString().split('T')[0];
   const now = new Date().toISOString();
 
-  // Update frontmatter fields
-  fm.status = 'complete';
+  // Update frontmatter fields — milestone complete, NOT project complete
+  // Project completion is a separate manual action via /dgs:complete-project
+  fm.status = 'milestone_shipped';
   if (!fm.progress) fm.progress = {};
   fm.progress.percent = 100;
   fm.last_updated = now;

package/deliver-great-systems/bin/lib/summary-frontmatter.cjs

@@ -0,0 +1,54 @@
+// deliver-great-systems/bin/lib/summary-frontmatter.cjs
+// REL-07: canonical SUMMARY-frontmatter writer.
+// Reads PLAN.md frontmatter `requirements:` field and writes a SUMMARY.md
+// frontmatter that ALWAYS populates the canonical YAML key (CANONICAL_KEY)
+// with those exact values.
+//
+// Canonical key: requirements_completed (underscore — pinned by 157-Q2-FINDINGS.md).
+
+const fs = require('node:fs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+
+const CANONICAL_KEY = 'requirements_completed';
+
+function writeSummaryFrontmatter({ planPath, summaryPath, extra = {} }) {
+  if (!fs.existsSync(planPath)) {
+    throw new Error(`writeSummaryFrontmatter: plan not found at ${planPath}`);
+  }
+  const planContent = fs.readFileSync(planPath, 'utf-8');
+  const planFm = extractFrontmatter(planContent);
+  const requirements = Array.isArray(planFm.requirements) ? planFm.requirements : [];
+
+  // Build SUMMARY frontmatter with the canonical key populated verbatim.
+  const fm = {
+    phase: extra.phase || planFm.phase || 'unknown',
+    plan: extra.plan || planFm.plan || '01',
+    subsystem: extra.subsystem || 'unspecified',
+    tags: extra.tags || [],
+    duration: extra.duration || '0min',
+    completed: extra.completed || new Date().toISOString().slice(0, 10),
+    [CANONICAL_KEY]: requirements,
+    ...(extra.executed_by ? { executed_by: extra.executed_by } : {}),
+  };
+
+  // Serialise to YAML frontmatter. Minimal stable serialiser to avoid
+  // introducing a new dependency.
+  const lines = ['---'];
+  for (const [key, value] of Object.entries(fm)) {
+    if (Array.isArray(value)) {
+      if (value.length === 0) {
+        lines.push(`${key}: []`);
+      } else {
+        lines.push(`${key}: [${value.join(', ')}]`);
+      }
+    } else {
+      lines.push(`${key}: ${value}`);
+    }
+  }
+  lines.push('---', '', `# Phase ${fm.phase} Plan ${fm.plan}: Summary`, '');
+
+  fs.writeFileSync(summaryPath, lines.join('\n'));
+  return { summaryPath, canonicalKey: CANONICAL_KEY, requirementsCopied: requirements.length };
+}
+
+module.exports = { writeSummaryFrontmatter, CANONICAL_KEY };

package/deliver-great-systems/bin/lib/summary-frontmatter.test.cjs

@@ -0,0 +1,78 @@
+// deliver-great-systems/bin/lib/summary-frontmatter.test.cjs
+// REL-07 regression test scaffold — initially RED. Turns GREEN after plan 02
+// pins the canonical YAML key and updates writer/template/agent/workflow/reader.
+
+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 { extractFrontmatter } = require('./frontmatter.cjs');
+
+// CANONICAL_KEY: pinned by 157-Q2-FINDINGS.md (underscore variant).
+// Plan 01 leaves the placeholder; plan 02 confirms the writer/template/etc. agree.
+const CANONICAL_KEY = 'requirements_completed';
+
+test('REL-07: SUMMARY writer copies PLAN requirements verbatim into canonical key', () => {
+  // RED: this assertion fails because no canonical writer module exists yet.
+  let writer;
+  try {
+    writer = require('./summary-frontmatter.cjs');
+  } catch (err) {
+    assert.fail('REL-07 writer module not yet implemented: bin/lib/summary-frontmatter.cjs (plan 02 task)');
+  }
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'rel07-'));
+  const planPath = path.join(tmpDir, 'test-PLAN.md');
+  const summaryPath = path.join(tmpDir, 'test-SUMMARY.md');
+  fs.writeFileSync(planPath, '---\nphase: test\nplan: 01\nrequirements:\n  - TEST-01\n  - TEST-02\n---\n');
+
+  writer.writeSummaryFrontmatter({ planPath, summaryPath });
+
+  const summary = fs.readFileSync(summaryPath, 'utf-8');
+  const fm = extractFrontmatter(summary);
+  assert.deepStrictEqual(fm[CANONICAL_KEY], ['TEST-01', 'TEST-02']);
+});
+
+test('REL-07: SUMMARY writer leaves canonical key empty when PLAN requirements is empty', () => {
+  let writer;
+  try {
+    writer = require('./summary-frontmatter.cjs');
+  } catch (err) {
+    assert.fail('REL-07 writer module not yet implemented: bin/lib/summary-frontmatter.cjs (plan 02 task)');
+  }
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'rel07-empty-'));
+  const planPath = path.join(tmpDir, 'test-PLAN.md');
+  const summaryPath = path.join(tmpDir, 'test-SUMMARY.md');
+  fs.writeFileSync(planPath, '---\nphase: test\nplan: 01\nrequirements: []\n---\n');
+
+  writer.writeSummaryFrontmatter({ planPath, summaryPath });
+
+  const summary = fs.readFileSync(summaryPath, 'utf-8');
+  const fm = extractFrontmatter(summary);
+  assert.deepStrictEqual(fm[CANONICAL_KEY] || [], []);
+});
+
+test('REL-07: canonical YAML key is consistent across template, agent prompt, workflow, reader, schema', () => {
+  // Convergence assertion. RED until plan 02 lands all five edits.
+  // __dirname = .../deliver-great-systems/bin/lib
+  // bin/lib/.. = .../deliver-great-systems/bin
+  // bin/.. = .../deliver-great-systems
+  // deliver-great-systems/.. = repo root (which contains the top-level agents/ and the nested deliver-great-systems/)
+  const repoRoot = path.resolve(__dirname, '../../..');
+  const sources = {
+    template: fs.readFileSync(path.join(repoRoot, 'deliver-great-systems/templates/summary.md'), 'utf-8'),
+    agent: fs.readFileSync(path.join(repoRoot, 'agents/dgs-executor.md'), 'utf-8'),
+    workflow: fs.readFileSync(path.join(repoRoot, 'deliver-great-systems/workflows/execute-plan.md'), 'utf-8'),
+    reader: fs.readFileSync(path.join(repoRoot, 'deliver-great-systems/bin/lib/commands.cjs'), 'utf-8'),
+    schema: fs.readFileSync(path.join(repoRoot, 'deliver-great-systems/bin/lib/frontmatter.cjs'), 'utf-8'),
+  };
+
+  // Each file must reference the CANONICAL_KEY at least once.
+  for (const [name, content] of Object.entries(sources)) {
+    assert.ok(content.includes(CANONICAL_KEY), `${name} must reference canonical key ${CANONICAL_KEY}`);
+  }
+});
+
+// REL-07 sentinel — flag this file as a Wave-0 RED scaffold for plan 02.

package/deliver-great-systems/bin/lib/sweep-scope.test.cjs

@@ -0,0 +1,263 @@
+/**
+ * RED test scaffold for REL-02 (Phase 156 plan 03).
+ *
+ * The `computePhaseSweep` helper is implemented in plan 03; running this
+ * file before plan 03 lands MUST produce 6 failed tests with
+ * 'not yet implemented — REL-02' style messages.
+ *
+ * Behaviour under test:
+ *   - union: commit list = git-discovered phase-dir paths UNION
+ *     executor-reported modified_files (deduplicated)
+ *   - underreport defence: empty modified_files still commits the
+ *     git-discovered phase-dir paths
+ *   - scope filter — sibling phase: dirty file in a different phase
+ *     dir is NOT included
+ *   - scope filter — out-of-scope dirs: dirty files in ideas/, specs/,
+ *     and project root are NOT included
+ *   - reported-path escape: a modified_files entry pointing outside the
+ *     phase dir is filtered out (or surfaced via dropped_out_of_scope)
+ *   - idempotency: running the helper twice on the same fixture returns
+ *     identical results
+ *
+ * Conventions:
+ *   - Uses node:test runner + node:assert (matches state-transition-gate.test.cjs)
+ *   - Each test creates and tears down its own temp git repo via os.tmpdir()
+ *   - Until plan 03 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 = 'computePhaseSweep not yet implemented — REL-02';
+
+// ─── Helpers ──────────────────────────────────────────────────────────────
+
+function tryRequireCommands() {
+  try {
+    // Reset the planning-root cache between tests so each
+    // makeTempPlanningRoot() sees a fresh root; getPlanningRoot caches
+    // per-process and would otherwise pin the first temp dir for the
+    // whole test run.
+    try { require('./paths.cjs').resetPaths(); } catch { /* ignore */ }
+    return require('./commands.cjs');
+  } catch (err) {
+    return null;
+  }
+}
+
+function makeTempPlanningRoot() {
+  // Resolve real path to handle symlink wrap on macOS (/tmp -> /private/tmp).
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'sweep-scope-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 });
+  // Seed an initial commit so HEAD exists
+  fs.writeFileSync(path.join(dir, 'README.md'), '# seed\n');
+  execSync('git add README.md', { 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 writeFile(root, rel, content) {
+  const abs = path.join(root, rel);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, content);
+}
+
+// ─── Test 1: union ────────────────────────────────────────────────────────
+
+test('REL-02 union: commit list = git-discovered phase-dir paths UNION executor-reported modified_files', () => {
+  const cmds = tryRequireCommands();
+  if (!cmds || typeof cmds.computePhaseSweep !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makeTempPlanningRoot();
+  try {
+    const phasesDir = 'phases';
+    const phaseDir = '156-test';
+    // git-dirty: A and B exist in the phase dir, untracked
+    writeFile(root, `${phasesDir}/${phaseDir}/A.md`, 'a\n');
+    writeFile(root, `${phasesDir}/${phaseDir}/B.md`, 'b\n');
+    // C is reported by the executor but does not exist on disk yet
+    writeFile(root, `${phasesDir}/${phaseDir}/C.md`, 'c\n');
+    const result = cmds.computePhaseSweep(root, {
+      phasesDir,
+      phaseDir,
+      modifiedFiles: [
+        `${phasesDir}/${phaseDir}/B.md`,
+        `${phasesDir}/${phaseDir}/C.md`,
+      ],
+    }, true);
+    const swept = (result && result.swept) || [];
+    const expected = [
+      `${phasesDir}/${phaseDir}/A.md`,
+      `${phasesDir}/${phaseDir}/B.md`,
+      `${phasesDir}/${phaseDir}/C.md`,
+    ].sort();
+    assert.deepStrictEqual(swept.slice().sort(), expected, 'union must equal A,B,C');
+  } finally {
+    cleanupRoot(root);
+  }
+});
+
+// ─── Test 2: underreport defence ──────────────────────────────────────────
+
+test('REL-02 underreport: executor returns empty modified_files but git-discovered phase-dir paths still committed', () => {
+  const cmds = tryRequireCommands();
+  if (!cmds || typeof cmds.computePhaseSweep !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makeTempPlanningRoot();
+  try {
+    const phasesDir = 'phases';
+    const phaseDir = '156-test';
+    writeFile(root, `${phasesDir}/${phaseDir}/A.md`, 'a\n');
+    writeFile(root, `${phasesDir}/${phaseDir}/B.md`, 'b\n');
+    const result = cmds.computePhaseSweep(root, {
+      phasesDir,
+      phaseDir,
+      modifiedFiles: [],
+    }, true);
+    const swept = (result && result.swept) || [];
+    assert.strictEqual(swept.length, 2, 'expected 2 git-dirty files');
+    assert.ok(swept.includes(`${phasesDir}/${phaseDir}/A.md`));
+    assert.ok(swept.includes(`${phasesDir}/${phaseDir}/B.md`));
+  } finally {
+    cleanupRoot(root);
+  }
+});
+
+// ─── Test 3: scope filter — sibling phase ─────────────────────────────────
+
+test('REL-02 scope filter: dirty file in sibling phase dir is NOT included', () => {
+  const cmds = tryRequireCommands();
+  if (!cmds || typeof cmds.computePhaseSweep !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makeTempPlanningRoot();
+  try {
+    const phasesDir = 'phases';
+    const phaseDir = '156-test';
+    const sibling = '155-other';
+    writeFile(root, `${phasesDir}/${phaseDir}/A.md`, 'a\n');
+    writeFile(root, `${phasesDir}/${sibling}/X.md`, 'x\n');
+    const result = cmds.computePhaseSweep(root, {
+      phasesDir,
+      phaseDir,
+      modifiedFiles: [],
+    }, true);
+    const swept = (result && result.swept) || [];
+    assert.strictEqual(swept.length, 1);
+    assert.ok(swept.includes(`${phasesDir}/${phaseDir}/A.md`));
+    assert.ok(!swept.some(p => p.includes(sibling)),
+      'sibling phase paths must NOT appear in swept');
+  } finally {
+    cleanupRoot(root);
+  }
+});
+
+// ─── Test 4: scope filter — ideas / specs / project root ──────────────────
+
+test('REL-02 scope filter: dirty file in ideas/, specs/, project root is NOT included', () => {
+  const cmds = tryRequireCommands();
+  if (!cmds || typeof cmds.computePhaseSweep !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makeTempPlanningRoot();
+  try {
+    const phasesDir = 'phases';
+    const phaseDir = '156-test';
+    writeFile(root, `${phasesDir}/${phaseDir}/A.md`, 'a\n');
+    writeFile(root, 'ideas/foo.md', 'idea\n');
+    writeFile(root, 'specs/bar.md', 'spec\n');
+    writeFile(root, 'NOTES.md', 'top-level\n');
+    const result = cmds.computePhaseSweep(root, {
+      phasesDir,
+      phaseDir,
+      modifiedFiles: [],
+    }, true);
+    const swept = (result && result.swept) || [];
+    assert.strictEqual(swept.length, 1, 'only the in-scope phase file should be swept');
+    assert.ok(swept.includes(`${phasesDir}/${phaseDir}/A.md`));
+    for (const out of ['ideas/foo.md', 'specs/bar.md', 'NOTES.md']) {
+      assert.ok(!swept.includes(out), `${out} must NOT be swept`);
+    }
+  } finally {
+    cleanupRoot(root);
+  }
+});
+
+// ─── Test 5: reported-path escape ─────────────────────────────────────────
+
+test('REL-02 reported-path escape: a modified_files entry that points outside the phase dir is filtered out', () => {
+  const cmds = tryRequireCommands();
+  if (!cmds || typeof cmds.computePhaseSweep !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makeTempPlanningRoot();
+  try {
+    const phasesDir = 'phases';
+    const phaseDir = '156-test';
+    const sibling = '155-other';
+    writeFile(root, `${phasesDir}/${phaseDir}/A.md`, 'a\n');
+    writeFile(root, `${phasesDir}/${sibling}/X.md`, 'x\n');
+    const result = cmds.computePhaseSweep(root, {
+      phasesDir,
+      phaseDir,
+      modifiedFiles: [
+        `${phasesDir}/${phaseDir}/A.md`,
+        `${phasesDir}/${sibling}/X.md`, // escape attempt
+      ],
+    }, true);
+    const swept = (result && result.swept) || [];
+    assert.strictEqual(swept.length, 1, 'only the in-scope path should be swept');
+    assert.ok(!swept.includes(`${phasesDir}/${sibling}/X.md`),
+      'sibling phase path must be filtered out of swept');
+    // Implementations may or may not surface a dropped_out_of_scope array;
+    // the contract is only that the dropped path is NOT in `swept`.
+  } finally {
+    cleanupRoot(root);
+  }
+});
+
+// ─── Test 6: idempotency ──────────────────────────────────────────────────
+
+test('REL-02 idempotency: running the sweep twice on the same fixture returns the same set', () => {
+  const cmds = tryRequireCommands();
+  if (!cmds || typeof cmds.computePhaseSweep !== 'function') {
+    assert.fail(NOT_IMPL);
+    return;
+  }
+  const root = makeTempPlanningRoot();
+  try {
+    const phasesDir = 'phases';
+    const phaseDir = '156-test';
+    writeFile(root, `${phasesDir}/${phaseDir}/A.md`, 'a\n');
+    writeFile(root, `${phasesDir}/${phaseDir}/B.md`, 'b\n');
+    const opts = {
+      phasesDir,
+      phaseDir,
+      modifiedFiles: [`${phasesDir}/${phaseDir}/B.md`],
+    };
+    const r1 = cmds.computePhaseSweep(root, opts, true);
+    const r2 = cmds.computePhaseSweep(root, opts, true);
+    assert.deepStrictEqual((r1 && r1.swept) || [], (r2 && r2.swept) || [],
+      'two identical calls must return identical swept sets');
+  } finally {
+    cleanupRoot(root);
+  }
+});

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');
     }
   }
 
@@ -788,6 +785,121 @@ function cmdValidateHealth(cwd, options, raw) {
     }
   } 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) {

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.