@ktpartners/dgs-platform 2.9.0 → 3.3.0

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

@@ -4,32 +4,31 @@
 
 const fs = require('fs');
 const path = require('path');
-const { escapeRegex, getMilestonePhaseFilter, output, error } = require('./core.cjs');
+const { escapeRegex, getMilestonePhaseFilter, getProjectRoot, output, error, loadConfig } = require('./core.cjs');
 const { extractFrontmatter } = require('./frontmatter.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
 const { writeStateMd } = require('./state.cjs');
+const { getContributors, checkFourEyes } = require('./governance.cjs');
+const { requireGitIdentity, formatAuthorString } = require('./identity.cjs');
 
-function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
-  if (!reqIdsRaw || reqIdsRaw.length === 0) {
-    error('requirement IDs required. Usage: requirements mark-complete REQ-01,REQ-02 or REQ-01 REQ-02');
-  }
-
-  // Accept comma-separated, space-separated, or bracket-wrapped: [REQ-01, REQ-02]
-  const reqIds = reqIdsRaw
-    .join(' ')
-    .replace(/[\[\]]/g, '')
-    .split(/[,\s]+/)
-    .map(r => r.trim())
-    .filter(Boolean);
-
-  if (reqIds.length === 0) {
+/**
+ * Internal helper: marks requirement IDs complete in REQUIREMENTS.md.
+ * Accepts an already-parsed array of IDs. Returns { result, reqPath, rawValue }
+ * WITHOUT calling output()/exit.
+ */
+function requirementsMarkCompleteInternal(cwd, reqIds) {
+  if (!Array.isArray(reqIds) || reqIds.length === 0) {
     error('no valid requirement IDs found');
   }
 
-  const reqPath = path.join(getPlanningRoot(cwd), 'REQUIREMENTS.md');
+  const projectRootRel = getProjectRoot(cwd);
+  const reqPath = path.join(getPlanningRoot(cwd), projectRootRel, 'REQUIREMENTS.md');
   if (!fs.existsSync(reqPath)) {
-    output({ updated: false, reason: 'REQUIREMENTS.md not found', ids: reqIds }, raw, 'no requirements file');
-    return;
+    return {
+      result: { updated: false, reason: 'REQUIREMENTS.md not found', ids: reqIds },
+      reqPath,
+      rawValue: 'no requirements file',
+    };
   }
 
   let reqContent = fs.readFileSync(reqPath, 'utf-8');
@@ -69,12 +68,37 @@ function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
     fs.writeFileSync(reqPath, reqContent, 'utf-8');
   }
 
-  output({
-    updated: updated.length > 0,
-    marked_complete: updated,
-    not_found: notFound,
-    total: reqIds.length,
-  }, raw, `${updated.length}/${reqIds.length} requirements marked complete`);
+  return {
+    result: {
+      updated: updated.length > 0,
+      marked_complete: updated,
+      not_found: notFound,
+      total: reqIds.length,
+    },
+    reqPath,
+    rawValue: `${updated.length}/${reqIds.length} requirements marked complete`,
+  };
+}
+
+function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
+  if (!reqIdsRaw || reqIdsRaw.length === 0) {
+    error('requirement IDs required. Usage: requirements mark-complete REQ-01,REQ-02 or REQ-01 REQ-02');
+  }
+
+  // Accept comma-separated, space-separated, or bracket-wrapped: [REQ-01, REQ-02]
+  const reqIds = reqIdsRaw
+    .join(' ')
+    .replace(/[\[\]]/g, '')
+    .split(/[,\s]+/)
+    .map(r => r.trim())
+    .filter(Boolean);
+
+  if (reqIds.length === 0) {
+    error('no valid requirement IDs found');
+  }
+
+  const { result, rawValue } = requirementsMarkCompleteInternal(cwd, reqIds);
+  output(result, raw, rawValue);
 }
 
 function cmdMilestoneComplete(cwd, version, options, raw) {
@@ -83,12 +107,14 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
   }
 
   const planRoot = getPlanningRoot(cwd);
-  const roadmapPath = path.join(planRoot, 'ROADMAP.md');
-  const reqPath = path.join(planRoot, 'REQUIREMENTS.md');
-  const statePath = path.join(planRoot, 'STATE.md');
+  const projectRootRel = getProjectRoot(cwd);
+  const projectRoot = path.join(planRoot, projectRootRel);
+  const roadmapPath = path.join(projectRoot, 'ROADMAP.md');
+  const reqPath = path.join(projectRoot, 'REQUIREMENTS.md');
+  const statePath = path.join(projectRoot, 'STATE.md');
   const milestonesPath = path.join(planRoot, 'MILESTONES.md');
   const archiveDir = path.join(planRoot, 'milestones');
-  const phasesDir = path.join(planRoot, 'phases');
+  const phasesDir = path.join(projectRoot, 'phases');
   const today = new Date().toISOString().split('T')[0];
   const milestoneName = options.name || version;
 
@@ -135,6 +161,72 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     }
   } catch {}
 
+  // ── Four-Eyes Gate (GATE-01) ───────────────────────────────────────────────
+  const config = loadConfig(cwd);
+  const rawConfig = (() => {
+    try {
+      return JSON.parse(fs.readFileSync(path.join(planRoot, 'config.json'), 'utf-8'));
+    } catch { return {}; }
+  })();
+  const fourEyesMode = (rawConfig.workflow && rawConfig.workflow.four_eyes) || 'off';
+  let governanceNote = null;
+
+  if (fourEyesMode !== 'off') {
+    // Resolve current user identity
+    let currentUserStr = '';
+    try {
+      const identity = requireGitIdentity(cwd);
+      currentUserStr = formatAuthorString(identity);
+    } catch {
+      // Identity gate already ran — this is a safety fallback
+      currentUserStr = '';
+    }
+
+    // Get contributors for this milestone
+    const contribResult = getContributors(cwd);
+    const contributors = contribResult.contributors || [];
+
+    // Run four-eyes check
+    const feResult = checkFourEyes(contributors, currentUserStr, fourEyesMode);
+
+    // Display contributor list (SHR-02 — always when not off)
+    const contribNames = contributors.length > 0
+      ? contributors.join(', ')
+      : '(none detected)';
+
+    if (feResult.passed) {
+      // Four-eyes satisfied — display and continue
+      process.stderr.write('Contributors: ' + contribNames + ' \u2014 \u2714 Four-eyes satisfied\n');
+    } else {
+      // Four-eyes failed — display contributor list first
+      process.stderr.write('Contributors: ' + contribNames + '\n');
+
+      // Extract current user name for display
+      let displayName = currentUserStr;
+      try {
+        const identity = requireGitIdentity(cwd);
+        displayName = identity.name;
+      } catch { /* use full string */ }
+
+      if (fourEyesMode === 'warn') {
+        // GATE-04: warn mode — display warning, proceed, log
+        process.stderr.write('\u26A0 You (' + displayName + ') contributed to this milestone. Completing anyway (warn mode).\n');
+        governanceNote = 'Four-eyes warning: ' + displayName + ' completed while also a contributor. Contributors: ' + contribNames;
+      } else if (fourEyesMode === 'enforce') {
+        if (options.force) {
+          // GATE-06: --force bypasses enforce
+          process.stderr.write('\u26A0 Forced: you (' + displayName + ') are the only contributor. Override logged.\n');
+          governanceNote = 'Four-eyes override: ' + displayName + ' force-completed. Contributors: ' + contribNames;
+        } else {
+          // GATE-05: enforce mode — block completion
+          error('\u2718 Blocked: you (' + displayName + ') are the only contributor. Use --force to override.');
+          return;
+        }
+      }
+    }
+  }
+  // Off mode: no check, no output, no performance impact (GATE-03)
+
   // Archive ROADMAP.md
   if (fs.existsSync(roadmapPath)) {
     const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
@@ -149,14 +241,15 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
   }
 
   // Archive audit file if exists
-  const auditFile = path.join(planRoot, `${version}-MILESTONE-AUDIT.md`);
+  const auditFile = path.join(projectRoot, `${version}-MILESTONE-AUDIT.md`);
   if (fs.existsSync(auditFile)) {
     fs.renameSync(auditFile, path.join(archiveDir, `${version}-MILESTONE-AUDIT.md`));
   }
 
   // Create/append MILESTONES.md entry
   const accomplishmentsList = accomplishments.map(a => `- ${a}`).join('\n');
-  const milestoneEntry = `## ${version} ${milestoneName} (Shipped: ${today})\n\n**Phases completed:** ${phaseCount} phases, ${totalPlans} plans, ${totalTasks} tasks\n\n**Key accomplishments:**\n${accomplishmentsList || '- (none recorded)'}\n\n---\n\n`;
+  const governanceLine = governanceNote ? `\n**Governance:** ${governanceNote}\n` : '';
+  const milestoneEntry = `## ${version} ${milestoneName} (Shipped: ${today})\n\n**Phases completed:** ${phaseCount} phases, ${totalPlans} plans, ${totalTasks} tasks\n\n**Key accomplishments:**\n${accomplishmentsList || '- (none recorded)'}${governanceLine}\n\n---\n\n`;
 
   if (fs.existsSync(milestonesPath)) {
     const existing = fs.readFileSync(milestonesPath, 'utf-8');
@@ -190,9 +283,12 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
       /(\*\*Last Activity:\*\*\s*).*/,
       `$1${today}`
     );
+    const activitySuffix = governanceNote
+      ? ` (four-eyes: ${fourEyesMode === 'warn' ? 'warn' : 'force'} override by ${(() => { try { return requireGitIdentity(cwd).name; } catch { return 'unknown'; } })()})`
+      : '';
     stateContent = stateContent.replace(
       /(\*\*Last Activity Description:\*\*\s*).*/,
-      `$1${version} milestone completed and archived`
+      `$1${version} milestone completed and archived${activitySuffix}`
     );
     writeStateMd(statePath, stateContent, cwd);
   }
@@ -216,6 +312,31 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
     } catch {}
   }
 
+  // Archive completed quick task directories
+  let quickArchived = false;
+  const quickDir = path.join(projectRoot, 'quick');
+  if (fs.existsSync(quickDir)) {
+    try {
+      const quickArchiveDir = path.join(archiveDir, `${version}-quick`);
+      const quickEntries = fs.readdirSync(quickDir, { withFileTypes: true });
+      const quickDirNames = quickEntries.filter(e => e.isDirectory()).map(e => e.name);
+      let archivedCount = 0;
+      for (const dir of quickDirNames) {
+        // Check if this quick dir has a SUMMARY file (completed)
+        const dirPath = path.join(quickDir, dir);
+        const dirFiles = fs.readdirSync(dirPath);
+        const hasSummary = dirFiles.some(f => f.endsWith('-SUMMARY.md'));
+        if (!hasSummary) continue;
+        if (!fs.existsSync(quickArchiveDir)) {
+          fs.mkdirSync(quickArchiveDir, { recursive: true });
+        }
+        fs.renameSync(dirPath, path.join(quickArchiveDir, dir));
+        archivedCount++;
+      }
+      quickArchived = archivedCount > 0;
+    } catch {}
+  }
+
   const result = {
     version,
     name: milestoneName,
@@ -229,6 +350,7 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
       requirements: fs.existsSync(path.join(archiveDir, `${version}-REQUIREMENTS.md`)),
       audit: fs.existsSync(path.join(archiveDir, `${version}-MILESTONE-AUDIT.md`)),
       phases: phasesArchived,
+      quick: quickArchived,
     },
     milestones_updated: true,
     state_updated: fs.existsSync(statePath),
@@ -239,5 +361,6 @@ function cmdMilestoneComplete(cwd, version, options, raw) {
 
 module.exports = {
   cmdRequirementsMarkComplete,
+  requirementsMarkCompleteInternal,
   cmdMilestoneComplete,
 };

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

@@ -0,0 +1,203 @@
+/**
+ * Tests for milestone.cjs — quick dir archival in cmdMilestoneComplete
+ *
+ * Uses Node.js built-in test runner (node:test) and assert (node:assert).
+ * Each test creates an isolated temp directory fixture and cleans up after.
+ */
+
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+const { createFixture, writeFile } = require('./test-helpers.cjs');
+const { cmdMilestoneComplete } = require('./milestone.cjs');
+
+// Helper: capture stdout from cmdMilestoneComplete (which calls output())
+function captureResult(fn) {
+  const chunks = [];
+  const origWrite = process.stdout.write;
+  process.stdout.write = function (chunk) {
+    chunks.push(String(chunk));
+  };
+  // Also suppress stderr (governance / state messages)
+  const origStderrWrite = process.stderr.write;
+  process.stderr.write = function () {};
+  // Prevent process.exit from actually exiting during tests
+  const origExit = process.exit;
+  process.exit = function () {};
+  try {
+    fn();
+  } finally {
+    process.stdout.write = origWrite;
+    process.stderr.write = origStderrWrite;
+    process.exit = origExit;
+  }
+  const raw = chunks.join('');
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Creates a root-layout fixture suitable for cmdMilestoneComplete.
+ * Root layout: no PROJECTS.md/REPOS.md (avoids v2 detection).
+ * Includes config.local.json with planningRoot, STATE.md, ROADMAP.md, phases/.
+ */
+function createMilestoneFixture(extras) {
+  const base = {
+    'config.json': JSON.stringify({}),
+    'config.local.json': JSON.stringify({ planningRoot: '.' }),
+    'STATE.md': '# Project State\n\nPhase: 1\nStatus: Ready\nProgress: [----------] 0%\n',
+    'ROADMAP.md': '# Roadmap\n\n## Phase 1: Test\n',
+    'phases/': null,
+  };
+  if (extras) {
+    Object.assign(base, extras);
+  }
+  return createFixture(base);
+}
+
+// ─── Quick Dir Archival Tests ────────────────────────────────────────────────
+
+describe('cmdMilestoneComplete quick dir archival', () => {
+  let fixture;
+
+  afterEach(() => {
+    if (fixture) fixture.cleanup();
+  });
+
+  it('archives completed quick dirs (with SUMMARY.md) to milestones/v1.0-quick/', () => {
+    fixture = createMilestoneFixture({
+      'quick/260101-abc-some-task/260101-abc-PLAN.md': '# Plan',
+      'quick/260101-abc-some-task/260101-abc-SUMMARY.md': '# Summary',
+    });
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v1.0', {}, false);
+    });
+
+    // Quick dir should be moved to milestones/v1.0-quick/
+    const archivedDir = path.join(cwd, 'milestones', 'v1.0-quick', '260101-abc-some-task');
+    assert.ok(fs.existsSync(archivedDir), 'Quick dir should be archived to milestones/v1.0-quick/');
+    assert.ok(!fs.existsSync(path.join(cwd, 'quick', '260101-abc-some-task')), 'Quick dir should be removed from quick/');
+    assert.ok(result, 'Should return result JSON');
+    assert.equal(result.archived.quick, true, 'archived.quick should be true');
+  });
+
+  it('does not move HISTORY.md from quick/', () => {
+    fixture = createMilestoneFixture({
+      'quick/HISTORY.md': '# History\n',
+      'quick/260102-def-other/260102-def-SUMMARY.md': '# Summary',
+    });
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v1.0', {}, false);
+    });
+
+    // HISTORY.md should remain in quick/
+    assert.ok(fs.existsSync(path.join(cwd, 'quick', 'HISTORY.md')), 'HISTORY.md should stay in quick/');
+    // The completed dir should be archived
+    assert.ok(fs.existsSync(path.join(cwd, 'milestones', 'v1.0-quick', '260102-def-other')), 'Completed dir should be archived');
+  });
+
+  it('skips plain files (non-directories) in quick/', () => {
+    fixture = createMilestoneFixture({
+      'quick/some-notes.txt': 'random notes',
+      'quick/260103-ghi-task/260103-ghi-SUMMARY.md': '# Summary',
+    });
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v1.0', {}, false);
+    });
+
+    // File should remain
+    assert.ok(fs.existsSync(path.join(cwd, 'quick', 'some-notes.txt')), 'Plain files should remain in quick/');
+    // Dir should be archived
+    assert.ok(fs.existsSync(path.join(cwd, 'milestones', 'v1.0-quick', '260103-ghi-task')), 'Completed dir should be archived');
+  });
+
+  it('does NOT move quick dirs without SUMMARY.md (incomplete)', () => {
+    fixture = createMilestoneFixture({
+      'quick/260104-jkl-wip/260104-jkl-PLAN.md': '# Plan',
+    });
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v1.0', {}, false);
+    });
+
+    // Should NOT be moved
+    assert.ok(fs.existsSync(path.join(cwd, 'quick', '260104-jkl-wip')), 'Incomplete quick dir should stay in quick/');
+    assert.ok(!fs.existsSync(path.join(cwd, 'milestones', 'v1.0-quick')), 'No quick archive dir should be created');
+    assert.ok(result, 'Should return result JSON');
+    assert.equal(result.archived.quick, false, 'archived.quick should be false when nothing archived');
+  });
+
+  it('gracefully handles when quick/ does not exist', () => {
+    fixture = createMilestoneFixture();
+    const cwd = fixture.cwd;
+
+    // No quick/ directory at all
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v1.0', {}, false);
+    });
+
+    assert.ok(result, 'Should return result JSON without error');
+    assert.equal(result.archived.quick, false, 'archived.quick should be false when no quick/ dir');
+  });
+
+  it('returns quickArchived=false when quick/ has no completed dirs', () => {
+    fixture = createMilestoneFixture({
+      'quick/HISTORY.md': '# History',
+      'quick/260105-mno-wip/260105-mno-PLAN.md': '# Plan',
+    });
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v1.0', {}, false);
+    });
+
+    assert.equal(result.archived.quick, false, 'archived.quick should be false');
+    assert.ok(!fs.existsSync(path.join(cwd, 'milestones', 'v1.0-quick')), 'No quick archive dir should be created');
+  });
+
+  it('creates milestones/v{X.Y}-quick/ only when there are dirs to archive', () => {
+    fixture = createMilestoneFixture({
+      'quick/260106-pqr-first/260106-pqr-SUMMARY.md': '# Summary',
+      'quick/260107-stu-second/260107-stu-SUMMARY.md': '# Summary',
+      'quick/260108-vwx-wip/260108-vwx-PLAN.md': '# Plan',
+    });
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v2.0', {}, false);
+    });
+
+    // Both completed dirs should be archived
+    assert.ok(fs.existsSync(path.join(cwd, 'milestones', 'v2.0-quick', '260106-pqr-first')), 'First completed dir archived');
+    assert.ok(fs.existsSync(path.join(cwd, 'milestones', 'v2.0-quick', '260107-stu-second')), 'Second completed dir archived');
+    // Incomplete dir should remain
+    assert.ok(fs.existsSync(path.join(cwd, 'quick', '260108-vwx-wip')), 'Incomplete dir should stay');
+    assert.equal(result.archived.quick, true, 'archived.quick should be true');
+  });
+
+  it('result JSON includes archived.quick field', () => {
+    fixture = createMilestoneFixture();
+    const cwd = fixture.cwd;
+
+    const result = captureResult(() => {
+      cmdMilestoneComplete(cwd, 'v1.0', {}, false);
+    });
+
+    assert.ok(result, 'Should return result');
+    assert.ok('archived' in result, 'Result should have archived object');
+    assert.ok('quick' in result.archived, 'archived should have quick field');
+    assert.equal(typeof result.archived.quick, 'boolean', 'archived.quick should be boolean');
+  });
+});