@ktpartners/dgs-platform 2.9.0 → 3.3.0

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

@@ -4,7 +4,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegex, normalizePhaseName, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, toPosixPath, output, error, getProjectRoot } = require('./core.cjs');
+const { escapeRegex, normalizePhaseName, comparePhaseNum, findPhaseInternal, getArchivedPhaseDirs, generateSlugInternal, getMilestonePhaseFilter, toPosixPath, output, error, getProjectRoot, loadConfig, execGit } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { writeStateMd } = require('./state.cjs');
 
@@ -381,6 +381,17 @@ function cmdPhaseAdd(cwd, description, raw) {
     updatedContent = content + phaseEntry;
   }
 
+  // Update milestone summary range (e.g., "Phases 124-128" -> "Phases 124-129")
+  const rangePattern = /Phases\s+(\d+)-(\d+)\s*\(in progress\)/;
+  const rangeMatch = updatedContent.match(rangePattern);
+  if (rangeMatch) {
+    const rangeEnd = parseInt(rangeMatch[2], 10);
+    if (newPhaseNum > rangeEnd) {
+      updatedContent = updatedContent.replace(rangePattern,
+        `Phases ${rangeMatch[1]}-${newPhaseNum} (in progress)`);
+    }
+  }
+
   fs.writeFileSync(roadmapPath, updatedContent, 'utf-8');
 
   const relPhasesDir = path.relative(cwd, phasesDir);
@@ -732,7 +743,16 @@ function cmdPhaseRemove(cwd, targetPhase, options, raw) {
   output(result, raw);
 }
 
-function cmdPhaseComplete(cwd, phaseNum, raw) {
+/**
+ * Internal helper: executes the phase-complete logic (ROADMAP/STATE/REQUIREMENTS
+ * updates + next-phase lookup) WITHOUT emitting output/exit.
+ *
+ * Returns { result, roadmapPath, statePath, requirementsPath, phaseDir }.
+ * The `result` object matches what cmdPhaseComplete emits. Paths are absolute.
+ * `requirementsPath` is returned even when the file doesn't exist (caller decides).
+ * `phaseDir` is the absolute path to the phase directory on disk.
+ */
+function phaseCompleteInternal(cwd, phaseNum) {
   if (!phaseNum) {
     error('phase number required for phase complete');
   }
@@ -740,6 +760,7 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
   const projRoot = resolveProjectRoot(cwd);
   const roadmapPath = path.join(cwd, projRoot, 'ROADMAP.md');
   const statePath = path.join(cwd, projRoot, 'STATE.md');
+  const requirementsPath = path.join(cwd, projRoot, 'REQUIREMENTS.md');
   const phasesDir = resolvePhasesDir(cwd);
   const normalized = normalizePhaseName(phaseNum);
   const today = new Date().toISOString().split('T')[0];
@@ -750,6 +771,11 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     error(`Phase ${phaseNum} not found`);
   }
 
+  // Absolute phase directory (phaseInfo.directory is relative to cwd)
+  const phaseDir = phaseInfo.directory
+    ? path.join(cwd, phaseInfo.directory)
+    : null;
+
   const planCount = phaseInfo.plans.length;
   const summaryCount = phaseInfo.summaries.length;
 
@@ -791,8 +817,9 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     const reqPath = path.join(cwd, projRoot, 'REQUIREMENTS.md');
     if (fs.existsSync(reqPath)) {
       // Extract Requirements line from roadmap for this phase
+      // Match both **Requirements:** (colon inside bold) and **Requirements**: (colon outside bold)
       const reqMatch = roadmapContent.match(
-        new RegExp(`Phase\\s+${escapeRegex(phaseNum)}[\\s\\S]*?\\*\\*Requirements:\\*\\*\\s*([^\\n]+)`, 'i')
+        new RegExp(`Phase\\s+${escapeRegex(phaseNum)}[\\s\\S]*?\\*\\*Requirements(?::\\*\\*|\\*\\*:)\\s*([^\\n]+)`, 'i')
       );
 
       if (reqMatch) {
@@ -896,6 +923,120 @@ function cmdPhaseComplete(cwd, phaseNum, raw) {
     state_updated: fs.existsSync(statePath),
   };
 
+  return { result, roadmapPath, statePath, requirementsPath, phaseDir };
+}
+
+/**
+ * CLI: `phase complete <phase>`. Thin wrapper over phaseCompleteInternal that
+ * emits the result and exits. External behavior unchanged from prior versions.
+ */
+function cmdPhaseComplete(cwd, phaseNum, raw) {
+  const { result } = phaseCompleteInternal(cwd, phaseNum);
+  output(result, raw);
+}
+
+/**
+ * CLI: `phase finalize <phase> [--push]`.
+ *
+ * Runs phaseCompleteInternal (ROADMAP/STATE/REQUIREMENTS updates) AND commits
+ * the modified tracking files + any `*-VERIFICATION.md` files in the phase dir
+ * in a single atomic call. Respects config.commit_docs (skip commit if false;
+ * still writes files). Handles --push for sync_push=auto|prompt modes.
+ *
+ * Does NOT call cmdCommit (which exits). Uses execGit directly.
+ */
+// Collect the list of still-dirty paths in `gitCwd` after a commit. Purely
+// informational — populates `result.dirty_after`. Duplicated from
+// commands.cjs/quick.cjs instead of extracted because the three call sites
+// use slightly different cwd variables and a shared module would obscure that.
+function collectDirtyAfter(gitCwd) {
+  const porcelain = execGit(gitCwd, ['status', '--porcelain']);
+  if (porcelain.exitCode !== 0) return [];
+  return (porcelain.stdout || '')
+    .split('\n')
+    .map(l => l.trim())
+    .filter(Boolean)
+    .map(l => l.replace(/^..\s+/, ''));
+}
+
+function cmdPhaseFinalize(cwd, phaseNum, options, raw) {
+  if (!phaseNum) {
+    error('phase number required for phase finalize');
+  }
+
+  const { result, roadmapPath, statePath, requirementsPath, phaseDir } =
+    phaseCompleteInternal(cwd, phaseNum);
+
+  // Gather tracking files that exist on disk (skip missing files gracefully)
+  const filesToStage = [];
+  for (const p of [roadmapPath, statePath, requirementsPath]) {
+    if (p && fs.existsSync(p)) {
+      filesToStage.push(path.relative(cwd, p));
+    }
+  }
+  // Include every *-VERIFICATION.md in the phase directory
+  if (phaseDir && fs.existsSync(phaseDir)) {
+    try {
+      const entries = fs.readdirSync(phaseDir).filter(f => /-VERIFICATION\.md$/i.test(f));
+      for (const f of entries) {
+        filesToStage.push(path.relative(cwd, path.join(phaseDir, f)));
+      }
+    } catch { /* ignore */ }
+  }
+
+  // Honor config.commit_docs — file writes already happened, just skip commit.
+  const config = loadConfig(cwd);
+  if (!config.commit_docs) {
+    result.committed = false;
+    result.commit_reason = 'skipped_commit_docs_false';
+    result.files_committed = [];
+    output(result, raw);
+    return;
+  }
+
+  // Stage + commit atomically (cmdCommit calls output/exit — inline instead).
+  for (const f of filesToStage) {
+    execGit(cwd, ['add', f]);
+  }
+  const message = `docs(phase-${phaseNum}): complete phase execution`;
+  const commitResult = execGit(cwd, ['commit', '-m', message]);
+  if (commitResult.exitCode !== 0) {
+    const nothing =
+      commitResult.stdout.includes('nothing to commit') ||
+      commitResult.stderr.includes('nothing to commit');
+    result.committed = false;
+    result.commit_reason = nothing ? 'nothing_to_commit' : 'commit_failed';
+    if (!nothing) result.commit_error = commitResult.stderr;
+    result.files_committed = [];
+    result.dirty_after = collectDirtyAfter(cwd);
+    output(result, raw);
+    return;
+  }
+  const hashResult = execGit(cwd, ['rev-parse', '--short', 'HEAD']);
+  result.committed = true;
+  result.hash = hashResult.exitCode === 0 ? hashResult.stdout : null;
+  result.commit_reason = 'committed';
+  result.files_committed = filesToStage;
+  result.dirty_after = collectDirtyAfter(cwd);
+
+  // Optional push (same semantics as cmdCommit)
+  if (options && options.push) {
+    const syncPush = config.sync_push || 'off';
+    if (syncPush === 'auto') {
+      try {
+        const { pushAll } = require('./sync.cjs');
+        const pushRes = pushAll(cwd, { force: true });
+        result.pushed = pushRes.ok;
+        result.push_result = pushRes;
+      } catch (err) {
+        result.pushed = false;
+        result.push_result = { ok: false, error: err.message };
+      }
+    } else if (syncPush === 'prompt') {
+      result.needs_push = true;
+    }
+  }
+
   output(result, raw);
 }
 
@@ -908,4 +1049,6 @@ module.exports = {
   cmdPhaseInsert,
   cmdPhaseRemove,
   cmdPhaseComplete,
+  cmdPhaseFinalize,
+  phaseCompleteInternal,
 };

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

@@ -0,0 +1,420 @@
+/**
+ * Tests for phase.cjs::cmdPhaseFinalize and commands.cjs::cmdPlanFinalize.
+ *
+ * Atomic "update tracking files + commit" behavior in a real temp git repo.
+ * Uses Node.js built-in test runner (node:test) and assert (node:assert).
+ */
+
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const { createTempProject } = require('./test-helpers.cjs');
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Capture stdout output from CLI commands that call output() (process.stdout.write
+ * + process.exit). Mocks both so multiple CLI invocations can run in sequence.
+ * Returns { stdout, exitCode, json }.
+ */
+function captureStdout(fn) {
+  const chunks = [];
+  const origWrite = process.stdout.write.bind(process.stdout);
+  const origExit = process.exit;
+  let exitCode = null;
+  process.stdout.write = (data) => { chunks.push(String(data)); return true; };
+  process.exit = (code) => {
+    exitCode = code == null ? 0 : code;
+    throw new Error('__EXIT__');
+  };
+  try {
+    fn();
+  } catch (e) {
+    if (e && e.message !== '__EXIT__') throw e;
+  } finally {
+    process.stdout.write = origWrite;
+    process.exit = origExit;
+  }
+  const stdout = chunks.join('');
+  let json = null;
+  try { json = JSON.parse(stdout); } catch { /* not JSON */ }
+  return { stdout, exitCode, json };
+}
+
+function gitLog(cwd) {
+  return execSync('git log --oneline', { cwd, encoding: 'utf-8' })
+    .trim().split('\n').filter(Boolean);
+}
+
+function gitShowFiles(cwd, ref) {
+  return execSync(`git show --name-only --format= ${ref}`, { cwd, encoding: 'utf-8' })
+    .trim().split('\n').filter(Boolean);
+}
+
+function gitLastMessage(cwd) {
+  return execSync('git log -1 --format=%s', { cwd, encoding: 'utf-8' }).trim();
+}
+
+/**
+ * Write a rich fixture atop createTempProject for Phase 01 finalize tests.
+ * Returns { cwd, cleanup } from createTempProject after adding ROADMAP, STATE,
+ * REQUIREMENTS, phase dir, and VERIFICATION.md — all committed to a clean tree.
+ */
+function makePhaseFinalizeFixture() {
+  const fixture = createTempProject({ withGit: false, withPhases: false, withConfig: {} });
+
+  // Remove v2 markers so this is treated as a v1/root-layout project (phases at root)
+  fs.unlinkSync(path.join(fixture.cwd, 'PROJECTS.md'));
+  fs.unlinkSync(path.join(fixture.cwd, 'REPOS.md'));
+
+  // Richer ROADMAP.md with parseable Phase 01 entry + progress table row
+  fs.writeFileSync(path.join(fixture.cwd, 'ROADMAP.md'),
+    '# Roadmap\n\n' +
+    '## Progress\n\n' +
+    '| Phase | Plans | Status | Date |\n' +
+    '|-------|-------|--------|------|\n' +
+    '| 01. Test | 1/1 | In Progress |  |\n\n' +
+    '## Phases\n\n' +
+    '- [ ] **Phase 01: Test** - desc\n\n' +
+    '## Phase 01: Test Phase\n\n' +
+    '**Plans:** 1/1 plans executed\n' +
+    '**Requirements:** [REQ-01]\n'
+  );
+
+  // STATE.md with all the fields cmdPhaseComplete regex-replaces
+  fs.writeFileSync(path.join(fixture.cwd, 'STATE.md'),
+    '# State\n\n' +
+    '**Current Phase:** 01\n' +
+    '**Current Phase Name:** Test Phase\n' +
+    '**Status:** In Progress\n' +
+    '**Current Plan:** 01-01\n' +
+    '**Last Activity:** 2025-01-01\n' +
+    '**Last Activity Description:** Working\n'
+  );
+
+  // REQUIREMENTS.md
+  fs.writeFileSync(path.join(fixture.cwd, 'REQUIREMENTS.md'),
+    '# Requirements\n\n' +
+    '- [ ] **REQ-01** Do thing\n\n' +
+    '| ID | Phase | Status |\n' +
+    '|----|-------|--------|\n' +
+    '| REQ-01 | Phase 01 | Pending |\n'
+  );
+
+  // Phase dir + PLAN + SUMMARY so findPhaseInternal finds it
+  fs.mkdirSync(path.join(fixture.cwd, 'phases/01-test-phase'), { recursive: true });
+  fs.writeFileSync(path.join(fixture.cwd, 'phases/01-test-phase/01-01-PLAN.md'), '# Plan\n');
+  fs.writeFileSync(path.join(fixture.cwd, 'phases/01-test-phase/01-01-SUMMARY.md'), '# Summary\n');
+
+  // Commit fixture additions so finalize produces a clean new commit
+  execSync('git add .', { cwd: fixture.cwd, stdio: 'pipe' });
+  execSync('git commit -m "fixture setup"', { cwd: fixture.cwd, stdio: 'pipe' });
+
+  // Write VERIFICATION.md AFTER the commit — this mirrors the real workflow where
+  // the verifier writes it just before finalize. It's untracked, so finalize must
+  // stage + commit it.
+  fs.writeFileSync(path.join(fixture.cwd, 'phases/01-test-phase/01-VERIFICATION.md'), '# Verification\n\nPassed.\n');
+
+  return fixture;
+}
+
+/**
+ * Write a rich fixture for Plan 01 finalize tests. Similar to above but the
+ * PLAN.md has real frontmatter with plan_name + requirements.
+ */
+function makePlanFinalizeFixture() {
+  const fixture = createTempProject({ withGit: false, withPhases: false, withConfig: {} });
+
+  // Remove v2 markers so this is treated as a v1/root-layout project (phases at root)
+  fs.unlinkSync(path.join(fixture.cwd, 'PROJECTS.md'));
+  fs.unlinkSync(path.join(fixture.cwd, 'REPOS.md'));
+
+  // ROADMAP.md with Phase 04 (same structure pattern)
+  fs.writeFileSync(path.join(fixture.cwd, 'ROADMAP.md'),
+    '# Roadmap\n\n' +
+    '## Progress\n\n' +
+    '| Phase | Plans | Status | Date |\n' +
+    '|-------|-------|--------|------|\n' +
+    '| 04. Auth | 0/1 | Planned |  |\n\n' +
+    '## Phases\n\n' +
+    '- [ ] **Phase 04: Auth** - auth layer\n\n' +
+    '## Phase 04: Auth\n\n' +
+    '**Plans:** 0/1 plans executed\n' +
+    '**Requirements:** [AUTH-01]\n'
+  );
+
+  fs.writeFileSync(path.join(fixture.cwd, 'STATE.md'),
+    '# State\n\n' +
+    '**Current Phase:** 04\n' +
+    '**Current Plan:** 04-01\n' +
+    'Progress: [░░░░░░░░░░] 0%\n'
+  );
+
+  fs.writeFileSync(path.join(fixture.cwd, 'REQUIREMENTS.md'),
+    '# Requirements\n\n' +
+    '- [ ] **AUTH-01** Login\n\n' +
+    '| ID | Phase | Status |\n' +
+    '|----|-------|--------|\n' +
+    '| AUTH-01 | Phase 04 | Pending |\n'
+  );
+
+  // Phase dir + PLAN.md (committed before finalize runs)
+  fs.mkdirSync(path.join(fixture.cwd, 'phases/04-auth'), { recursive: true });
+  fs.writeFileSync(path.join(fixture.cwd, 'phases/04-auth/04-01-PLAN.md'),
+    '---\n' +
+    'phase: 04-auth\n' +
+    'plan: 01\n' +
+    'plan_name: auth-login\n' +
+    'requirements: [AUTH-01]\n' +
+    '---\n' +
+    '# Plan\n'
+  );
+
+  execSync('git add .', { cwd: fixture.cwd, stdio: 'pipe' });
+  execSync('git commit -m "fixture setup"', { cwd: fixture.cwd, stdio: 'pipe' });
+
+  // SUMMARY.md written AFTER the initial commit — matches real workflow where
+  // the executor produces SUMMARY.md as its final artifact before finalize runs.
+  // PLAN.md also gets touched so it's re-staged (the real workflow updates it
+  // with executed_by / completion metadata during the session).
+  fs.writeFileSync(path.join(fixture.cwd, 'phases/04-auth/04-01-SUMMARY.md'), '# Summary\n');
+  fs.appendFileSync(path.join(fixture.cwd, 'phases/04-auth/04-01-PLAN.md'), '\nexecuted.\n');
+
+  return fixture;
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe('cmdPhaseFinalize', () => {
+  let fixture;
+  let phase;
+
+  beforeEach(() => {
+    fixture = makePhaseFinalizeFixture();
+    // Reload phase.cjs each time so the fixture cwd's config is re-read fresh
+    delete require.cache[require.resolve('./phase.cjs')];
+    phase = require('./phase.cjs');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('creates a single commit containing tracking files + VERIFICATION.md', () => {
+    const before = gitLog(fixture.cwd).length;
+    const { json } = captureStdout(() =>
+      phase.cmdPhaseFinalize(fixture.cwd, '01', { push: false }, true)
+    );
+
+    assert.ok(json, 'should emit JSON output');
+    assert.equal(json.committed, true);
+    assert.ok(json.hash, 'should return commit hash');
+    assert.equal(gitLog(fixture.cwd).length, before + 1, 'exactly one new commit');
+
+    const files = gitShowFiles(fixture.cwd, 'HEAD');
+    assert.ok(files.includes('ROADMAP.md'), 'ROADMAP.md staged');
+    assert.ok(files.includes('STATE.md'), 'STATE.md staged');
+    assert.ok(files.includes('REQUIREMENTS.md'), 'REQUIREMENTS.md staged');
+    assert.ok(
+      files.some(f => /VERIFICATION\.md$/.test(f)),
+      'VERIFICATION.md staged'
+    );
+  });
+
+  it('commit message uses docs(phase-NN): format', () => {
+    captureStdout(() =>
+      phase.cmdPhaseFinalize(fixture.cwd, '01', { push: false }, true)
+    );
+    assert.equal(gitLastMessage(fixture.cwd), 'docs(phase-01): complete phase execution');
+  });
+
+  it('succeeds when VERIFICATION.md is absent', () => {
+    // Simply delete the untracked VERIFICATION.md (never committed)
+    fs.unlinkSync(path.join(fixture.cwd, 'phases/01-test-phase/01-VERIFICATION.md'));
+
+    const { json } = captureStdout(() =>
+      phase.cmdPhaseFinalize(fixture.cwd, '01', { push: false }, true)
+    );
+
+    assert.equal(json.committed, true);
+    const files = gitShowFiles(fixture.cwd, 'HEAD');
+    assert.ok(!files.some(f => /VERIFICATION\.md$/.test(f)), 'no VERIFICATION in commit');
+    assert.ok(files.includes('ROADMAP.md'), 'ROADMAP still committed');
+  });
+
+  it('succeeds when REQUIREMENTS.md is absent', () => {
+    // VERIFICATION.md is untracked at this point — stage only the REQUIREMENTS removal.
+    fs.unlinkSync(path.join(fixture.cwd, 'REQUIREMENTS.md'));
+    execSync('git add REQUIREMENTS.md', { cwd: fixture.cwd, stdio: 'pipe' });
+    execSync('git commit -m "remove req"', { cwd: fixture.cwd, stdio: 'pipe' });
+
+    const { json } = captureStdout(() =>
+      phase.cmdPhaseFinalize(fixture.cwd, '01', { push: false }, true)
+    );
+
+    assert.equal(json.committed, true);
+    const files = gitShowFiles(fixture.cwd, 'HEAD');
+    assert.ok(!files.includes('REQUIREMENTS.md'), 'no REQUIREMENTS in commit');
+    assert.ok(files.includes('ROADMAP.md'), 'ROADMAP still committed');
+    assert.ok(files.includes('STATE.md'), 'STATE still committed');
+    assert.ok(
+      files.some(f => /VERIFICATION\.md$/.test(f)),
+      'VERIFICATION still committed'
+    );
+  });
+
+  it('honors commit_docs=false (no commit, but file writes still happen)', () => {
+    const cfgPath = path.join(fixture.cwd, 'config.json');
+    const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+    cfg.commit_docs = false;
+    fs.writeFileSync(cfgPath, JSON.stringify(cfg));
+    // Commit only the config change (VERIFICATION.md is untracked; leave it)
+    execSync('git add config.json', { cwd: fixture.cwd, stdio: 'pipe' });
+    execSync('git commit -m "disable commit_docs"', { cwd: fixture.cwd, stdio: 'pipe' });
+
+    const before = gitLog(fixture.cwd).length;
+    const { json } = captureStdout(() =>
+      phase.cmdPhaseFinalize(fixture.cwd, '01', { push: false }, true)
+    );
+
+    assert.equal(json.committed, false);
+    assert.equal(json.commit_reason, 'skipped_commit_docs_false');
+    assert.equal(gitLog(fixture.cwd).length, before, 'no new commit created');
+
+    // File writes still happened: ROADMAP should have [x]
+    const roadmap = fs.readFileSync(path.join(fixture.cwd, 'ROADMAP.md'), 'utf-8');
+    assert.match(roadmap, /\[x\]/, 'roadmap checkbox updated despite no commit');
+  });
+
+  it('returns committed=false with nothing_to_commit when no files to stage', () => {
+    // Remove all tracking files and VERIFICATION.md BEFORE finalize. findPhaseInternal
+    // still succeeds via the phase dir + PLAN.md, but no files exist to stage.
+    fs.unlinkSync(path.join(fixture.cwd, 'phases/01-test-phase/01-VERIFICATION.md'));
+    fs.unlinkSync(path.join(fixture.cwd, 'ROADMAP.md'));
+    fs.unlinkSync(path.join(fixture.cwd, 'STATE.md'));
+    fs.unlinkSync(path.join(fixture.cwd, 'REQUIREMENTS.md'));
+    execSync('git add -A', { cwd: fixture.cwd, stdio: 'pipe' });
+    execSync('git commit -m "remove all tracking"', { cwd: fixture.cwd, stdio: 'pipe' });
+
+    const before = gitLog(fixture.cwd).length;
+    const { json } = captureStdout(() =>
+      phase.cmdPhaseFinalize(fixture.cwd, '01', { push: false }, true)
+    );
+    assert.equal(json.committed, false);
+    assert.equal(json.commit_reason, 'nothing_to_commit');
+    assert.equal(gitLog(fixture.cwd).length, before, 'no new commit');
+  });
+});
+
+describe('cmdPlanFinalize', () => {
+  let fixture;
+  let commands;
+
+  beforeEach(() => {
+    fixture = makePlanFinalizeFixture();
+    delete require.cache[require.resolve('./commands.cjs')];
+    commands = require('./commands.cjs');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('creates a single commit containing PLAN + SUMMARY + tracking files', () => {
+    const before = gitLog(fixture.cwd).length;
+    const { json } = captureStdout(() =>
+      commands.cmdPlanFinalize(fixture.cwd, '04', '01', { push: false }, true)
+    );
+
+    assert.ok(json, 'should emit JSON output');
+    assert.equal(json.committed, true);
+    assert.ok(json.hash);
+    assert.equal(gitLog(fixture.cwd).length, before + 1, 'exactly one new commit');
+
+    const files = gitShowFiles(fixture.cwd, 'HEAD');
+    assert.ok(files.some(f => f.endsWith('04-01-PLAN.md')), 'PLAN.md staged');
+    assert.ok(files.some(f => f.endsWith('04-01-SUMMARY.md')), 'SUMMARY.md staged');
+    assert.ok(files.includes('STATE.md'), 'STATE.md staged');
+    assert.ok(files.includes('ROADMAP.md'), 'ROADMAP.md staged');
+    assert.ok(files.includes('REQUIREMENTS.md'), 'REQUIREMENTS.md staged');
+  });
+
+  it('commit message uses plan_name from PLAN.md frontmatter', () => {
+    captureStdout(() =>
+      commands.cmdPlanFinalize(fixture.cwd, '04', '01', { push: false }, true)
+    );
+    assert.equal(gitLastMessage(fixture.cwd), 'docs(04-01): complete auth-login plan');
+  });
+
+  it('--plan-name flag overrides frontmatter plan_name', () => {
+    captureStdout(() =>
+      commands.cmdPlanFinalize(fixture.cwd, '04', '01', { push: false, planName: 'override-name' }, true)
+    );
+    assert.equal(gitLastMessage(fixture.cwd), 'docs(04-01): complete override-name plan');
+  });
+
+  it('marks requirements from frontmatter complete', () => {
+    const { json } = captureStdout(() =>
+      commands.cmdPlanFinalize(fixture.cwd, '04', '01', { push: false }, true)
+    );
+    assert.equal(json.committed, true);
+    assert.deepEqual(json.requirements.marked_complete, ['AUTH-01']);
+
+    const reqContent = fs.readFileSync(path.join(fixture.cwd, 'REQUIREMENTS.md'), 'utf-8');
+    assert.match(reqContent, /- \[x\] \*\*AUTH-01\*\*/, 'checkbox marked');
+    assert.match(reqContent, /\|\s*AUTH-01\s*\|[^|]+\|\s*Complete\s*\|/, 'traceability Complete');
+  });
+
+  it('succeeds gracefully when REQUIREMENTS.md is absent', () => {
+    fs.unlinkSync(path.join(fixture.cwd, 'REQUIREMENTS.md'));
+    // Stage only the REQUIREMENTS removal — leave PLAN/SUMMARY untracked/dirty
+    // so finalize picks them up in the atomic commit.
+    execSync('git add REQUIREMENTS.md', { cwd: fixture.cwd, stdio: 'pipe' });
+    execSync('git commit -m "remove req"', { cwd: fixture.cwd, stdio: 'pipe' });
+
+    const { json } = captureStdout(() =>
+      commands.cmdPlanFinalize(fixture.cwd, '04', '01', { push: false }, true)
+    );
+    assert.equal(json.committed, true);
+    const files = gitShowFiles(fixture.cwd, 'HEAD');
+    assert.ok(!files.includes('REQUIREMENTS.md'), 'REQUIREMENTS not committed');
+    assert.ok(files.some(f => f.endsWith('04-01-PLAN.md')), 'PLAN still committed');
+    assert.ok(files.some(f => f.endsWith('04-01-SUMMARY.md')), 'SUMMARY still committed');
+    assert.ok(files.includes('STATE.md'), 'STATE still committed');
+    assert.ok(files.includes('ROADMAP.md'), 'ROADMAP still committed');
+  });
+
+  it('honors commit_docs=false (no commit, but file writes still happen)', () => {
+    const cfgPath = path.join(fixture.cwd, 'config.json');
+    const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf-8'));
+    cfg.commit_docs = false;
+    fs.writeFileSync(cfgPath, JSON.stringify(cfg));
+    execSync('git add -A', { cwd: fixture.cwd, stdio: 'pipe' });
+    execSync('git commit -m "disable commit_docs"', { cwd: fixture.cwd, stdio: 'pipe' });
+
+    const before = gitLog(fixture.cwd).length;
+    const { json } = captureStdout(() =>
+      commands.cmdPlanFinalize(fixture.cwd, '04', '01', { push: false }, true)
+    );
+    assert.equal(json.committed, false);
+    assert.equal(json.commit_reason, 'skipped_commit_docs_false');
+    assert.equal(gitLog(fixture.cwd).length, before, 'no new commit');
+  });
+
+  it('falls back to "execution" when plan_name missing and no flag', () => {
+    // Remove plan_name from frontmatter
+    const planPath = path.join(fixture.cwd, 'phases/04-auth/04-01-PLAN.md');
+    const content = fs.readFileSync(planPath, 'utf-8').replace(/plan_name:.*\n/, '');
+    fs.writeFileSync(planPath, content);
+    execSync('git add -A', { cwd: fixture.cwd, stdio: 'pipe' });
+    execSync('git commit -m "strip plan_name"', { cwd: fixture.cwd, stdio: 'pipe' });
+
+    captureStdout(() =>
+      commands.cmdPlanFinalize(fixture.cwd, '04', '01', { push: false }, true)
+    );
+    assert.equal(gitLastMessage(fixture.cwd), 'docs(04-01): complete execution plan');
+  });
+});

package/deliver-great-systems/bin/lib/plan-number-validity.test.cjs

@@ -0,0 +1,48 @@
+// deliver-great-systems/bin/lib/plan-number-validity.test.cjs
+// REL-04 regression test scaffold — initially RED. Turns GREEN after plan 02
+// adds Dimension 10 (plan-number validity) to agents/dgs-plan-checker.md.
+//
+// Strategy: this is an agent-prompt assertion, not a CLI test. Tests read
+// agents/dgs-plan-checker.md and assert the dimension exists with the required
+// remediation text + soft-fail marker + named-follow-up-phase reference.
+
+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 checkerPath = path.join(repoRoot, 'agents/dgs-plan-checker.md');
+
+test('REL-04: dgs-plan-checker has Dimension 10 (plan-number validity)', () => {
+  const content = fs.readFileSync(checkerPath, 'utf-8');
+  assert.match(content, /## Dimension 10: Plan Number Validity/, 'Dimension 10 must exist');
+});
+
+test('REL-04: Dimension 10 enumerates rejected plan-number forms', () => {
+  const content = fs.readFileSync(checkerPath, 'utf-8');
+  for (const form of ['plan: 00', 'plan: 0', 'positive integer']) {
+    assert.ok(content.includes(form), `Dimension 10 must mention "${form}"`);
+  }
+});
+
+test('REL-04: Dimension 10 includes exact rename remediation command', () => {
+  const content = fs.readFileSync(checkerPath, 'utf-8');
+  assert.match(content, /git mv .*-00-PLAN\.md.*-01-PLAN\.md/, 'remediation must include git mv command');
+});
+
+test('REL-04: Dimension 10 is soft-fail (warning, not block) on initial rollout', () => {
+  const content = fs.readFileSync(checkerPath, 'utf-8');
+  const dim10Match = content.match(/## Dimension 10[\s\S]+?(?=## Dimension|$)/);
+  assert.ok(dim10Match, 'Dimension 10 block must exist');
+  const dim10Text = dim10Match[0];
+  assert.ok(/soft-fail|warning|warn/i.test(dim10Text), 'Dimension 10 must mark itself as soft-fail/warning');
+});
+
+test('REL-04: Dimension 10 references the named follow-up phase for hard-reject promotion', () => {
+  const content = fs.readFileSync(checkerPath, 'utf-8');
+  assert.ok(/follow-up phase|hard-reject promotion/i.test(content),
+    'Dimension 10 must reference hard-reject deferral to a named follow-up phase');
+});
+
+// REL-04 sentinel — flag this file as a Wave-0 RED scaffold for plan 02.