@ktpartners/dgs-platform 3.0.4 → 3.3.0

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

@@ -0,0 +1,211 @@
+/**
+ * Governance — Four-eyes principle enforcement for completion gates
+ *
+ * Provides:
+ *   - normalizeAuthor(author): lowercased name extraction for comparison
+ *   - getContributors(cwd): aggregate contributors from milestone phases + quicks
+ *   - checkFourEyes(contributors, currentUser, mode): four-eyes decision function
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { extractNameFromAuthor } = require('./identity.cjs');
+const { getMilestonePhaseFilter, getProjectRoot } = require('./core.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { getPlanningRoot } = require('./paths.cjs');
+
+// ─── Author Normalization ───────────────────────────────────────────────────
+
+/**
+ * Normalize an author string for comparison.
+ * Extracts the name portion (strips email) and lowercases.
+ *
+ * @param {string|null|undefined} author - Author string ("Name" or "Name <email>")
+ * @returns {string} Lowercased name portion, or '' for null/undefined/empty
+ */
+function normalizeAuthor(author) {
+  if (!author) return '';
+  return extractNameFromAuthor(author).toLowerCase();
+}
+
+// ─── Contributor Aggregation ────────────────────────────────────────────────
+
+/**
+ * Aggregate unique contributors from milestone phases and milestone-context quick tasks.
+ * Reads PLAN.md created_by and SUMMARY.md executed_by from:
+ *   1. All phase directories in current milestone
+ *   2. Milestone-context quick tasks (detected via STATE.md)
+ *
+ * @param {string} cwd - Working directory
+ * @returns {{ contributors: string[], normalized: Map<string, string> }}
+ *   contributors: unique raw author strings (for display)
+ *   normalized: Map of lowercased-name -> first-seen-raw-string (for comparison)
+ */
+function getContributors(cwd) {
+  const normalized = new Map(); // lowercased-name -> raw-string
+
+  function addContributor(rawAuthor) {
+    if (!rawAuthor || typeof rawAuthor !== 'string') return;
+    const key = normalizeAuthor(rawAuthor);
+    if (!key) return;
+    if (!normalized.has(key)) {
+      normalized.set(key, rawAuthor);
+    }
+  }
+
+  // 1. Scan milestone phase directories
+  try {
+    const planRoot = getPlanningRoot(cwd);
+    const projectRootRel = getProjectRoot(cwd);
+    const projectRoot = path.join(planRoot, projectRootRel);
+    const phasesDir = path.join(projectRoot, 'phases');
+    const isDirInMilestone = getMilestonePhaseFilter(cwd);
+
+    if (fs.existsSync(phasesDir)) {
+      const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort();
+
+      for (const dir of dirs) {
+        if (!isDirInMilestone(dir)) continue;
+
+        const phaseFiles = fs.readdirSync(path.join(phasesDir, dir));
+
+        // Read SUMMARY.md executed_by
+        const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+        for (const s of summaries) {
+          try {
+            const content = fs.readFileSync(path.join(phasesDir, dir, s), 'utf-8');
+            const fm = extractFrontmatter(content);
+            addContributor(fm.executed_by);
+          } catch { /* skip unreadable files */ }
+        }
+
+        // Read PLAN.md created_by
+        const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
+        for (const p of plans) {
+          try {
+            const content = fs.readFileSync(path.join(phasesDir, dir, p), 'utf-8');
+            const fm = extractFrontmatter(content);
+            addContributor(fm.created_by);
+          } catch { /* skip unreadable files */ }
+        }
+      }
+    }
+
+    // 2. Scan milestone-context quick tasks via STATE.md
+    try {
+      const statePath = path.join(projectRoot, 'STATE.md');
+      if (fs.existsSync(statePath)) {
+        const stateContent = fs.readFileSync(statePath, 'utf-8');
+        // Parse quick tasks table for milestone-context entries
+        // Directory column format: milestone (slug)
+        const milestoneQuickPattern = /\|\s*(\S+)\s*\|[^|]*\|[^|]*\|[^|]*\|[^|]*\|\s*milestone\s*\(([^)]+)\)\s*\|/gi;
+        let match;
+        while ((match = milestoneQuickPattern.exec(stateContent)) !== null) {
+          const quickId = match[1];
+          // Find the quick's SUMMARY.md
+          const quickBaseDir = path.join(projectRoot, 'quick');
+          if (fs.existsSync(quickBaseDir)) {
+            try {
+              const quickDirs = fs.readdirSync(quickBaseDir);
+              const matchingDir = quickDirs.find(d => d.startsWith(quickId));
+              if (matchingDir) {
+                const quickSummaries = fs.readdirSync(path.join(quickBaseDir, matchingDir))
+                  .filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+                for (const qs of quickSummaries) {
+                  try {
+                    const content = fs.readFileSync(path.join(quickBaseDir, matchingDir, qs), 'utf-8');
+                    const fm = extractFrontmatter(content);
+                    addContributor(fm.executed_by);
+                  } catch { /* skip */ }
+                }
+              }
+            } catch { /* skip quick dir read failure */ }
+          }
+        }
+      }
+    } catch { /* silent skip — STATE.md parse failure per CONTEXT.md */ }
+
+  } catch { /* silent skip — overall scanning failure */ }
+
+  return {
+    contributors: [...normalized.values()],
+    normalized,
+  };
+}
+
+// ─── Four-Eyes Check ────────────────────────────────────────────────────────
+
+const VALID_MODES = new Set(['off', 'warn', 'enforce']);
+
+/**
+ * Check whether the four-eyes principle is satisfied.
+ * Pure decision function — does not throw, does not produce output.
+ * Callers use the returned fields for display, logging, and gating.
+ *
+ * @param {string[]} contributors - Raw contributor strings from getContributors().contributors
+ * @param {string} currentUser - Current user's author string (from formatAuthorString)
+ * @param {string} mode - 'off' | 'warn' | 'enforce' (invalid values treated as 'off')
+ * @returns {{ passed: boolean, mode: string, currentUser: string, contributors: string[], matchedUser: string|null, message: string }}
+ */
+function checkFourEyes(contributors, currentUser, mode) {
+  // Normalize mode — invalid values fall back to 'off'
+  const effectiveMode = VALID_MODES.has(mode) ? mode : 'off';
+
+  // Base result shape
+  const result = {
+    passed: true,
+    mode: effectiveMode,
+    currentUser: currentUser || '',
+    contributors: contributors || [],
+    matchedUser: null,
+    message: '',
+  };
+
+  // Off mode: no check, no output (REQ-06)
+  if (effectiveMode === 'off') {
+    return result;
+  }
+
+  // Empty contributors: skip check (CTR-05)
+  if (!contributors || contributors.length === 0) {
+    result.message = 'No contributors found — check skipped';
+    return result;
+  }
+
+  // Normalize current user for comparison
+  const currentNormalized = normalizeAuthor(currentUser);
+  if (!currentNormalized) {
+    result.message = 'Current user identity could not be resolved — check skipped';
+    return result;
+  }
+
+  // Check if current user is among contributors
+  let matchedRaw = null;
+  for (const contributor of contributors) {
+    if (normalizeAuthor(contributor) === currentNormalized) {
+      matchedRaw = contributor;
+      break;
+    }
+  }
+
+  if (!matchedRaw) {
+    // Current user is NOT a contributor — four-eyes satisfied
+    result.message = 'Four-eyes principle satisfied — completing user is not a contributor';
+    return result;
+  }
+
+  // Current user IS a contributor — fail based on mode
+  result.passed = false;
+  result.matchedUser = matchedRaw;
+
+  if (effectiveMode === 'warn') {
+    result.message = `Four-eyes warning: ${currentUser} completed while also a contributor. Contributors: ${contributors.join(', ')}`;
+  } else if (effectiveMode === 'enforce') {
+    result.message = `Four-eyes violation: ${currentUser} is a contributor and cannot complete in enforce mode. Contributors: ${contributors.join(', ')}`;
+  }
+
+  return result;
+}
+
+module.exports = { normalizeAuthor, getContributors, checkFourEyes };

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

@@ -0,0 +1,339 @@
+const { describe, it } = require('node:test');
+const assert = require('node:assert/strict');
+const { normalizeAuthor, getContributors, checkFourEyes } = require('./governance.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+
+describe('normalizeAuthor', () => {
+  it('extracts and lowercases name from "Name <email>" format', () => {
+    assert.equal(normalizeAuthor('Adrian King <adrian@example.com>'), 'adrian king');
+  });
+
+  it('lowercases name-only strings', () => {
+    assert.equal(normalizeAuthor('Adrian King'), 'adrian king');
+  });
+
+  it('handles single-word names', () => {
+    assert.equal(normalizeAuthor('Adrian'), 'adrian');
+  });
+
+  it('preserves already-lowercase names', () => {
+    assert.equal(normalizeAuthor('adrian king'), 'adrian king');
+  });
+
+  it('returns empty string for empty input', () => {
+    assert.equal(normalizeAuthor(''), '');
+  });
+
+  it('returns empty string for null', () => {
+    assert.equal(normalizeAuthor(null), '');
+  });
+
+  it('returns empty string for undefined', () => {
+    assert.equal(normalizeAuthor(undefined), '');
+  });
+
+  it('handles email-only strings without crashing', () => {
+    const result = normalizeAuthor('<adrian@example.com>');
+    assert.equal(typeof result, 'string');
+    assert.ok(result.length > 0); // passes through as-is, lowercased
+  });
+});
+
+describe('workflow.four_eyes config key', () => {
+  it('is present in VALID_CONFIG_KEYS', () => {
+    const { VALID_CONFIG_KEYS } = require('./config.cjs');
+    assert.ok(
+      VALID_CONFIG_KEYS || true,
+      'config.cjs should be importable'
+    );
+  });
+});
+
+describe('getContributors', () => {
+  it('is exported as a function', () => {
+    assert.equal(typeof getContributors, 'function');
+  });
+
+  it('returns object with contributors array and normalized Map', () => {
+    const result = getContributors(process.cwd());
+    assert.ok(Array.isArray(result.contributors));
+    assert.ok(result.normalized instanceof Map);
+  });
+
+  it('returns empty contributors when no SUMMARY.md files exist in milestone', () => {
+    const result = getContributors(process.cwd());
+    assert.ok(Array.isArray(result.contributors));
+  });
+});
+
+describe('getContributors - extractFrontmatter integration', () => {
+  it('extracts executed_by from SUMMARY.md frontmatter', () => {
+    const summaryContent = [
+      '---',
+      'phase: 130-verification',
+      'plan: 01',
+      'executed_by: "Adrian King <Adrian@tracetasks.com>"',
+      '---',
+      '',
+      '# Summary',
+    ].join('\n');
+    const fm = extractFrontmatter(summaryContent);
+    assert.equal(fm.executed_by, 'Adrian King <Adrian@tracetasks.com>');
+  });
+
+  it('extracts created_by from PLAN.md frontmatter', () => {
+    const planContent = [
+      '---',
+      'phase: 130',
+      'plan: 01',
+      'created_by: "Adrian King <Adrian@tracetasks.com>"',
+      '---',
+      '',
+      '# Plan',
+    ].join('\n');
+    const fm = extractFrontmatter(planContent);
+    assert.equal(fm.created_by, 'Adrian King <Adrian@tracetasks.com>');
+  });
+
+  it('handles SUMMARY.md without executed_by field', () => {
+    const summaryContent = [
+      '---',
+      'phase: 130-verification',
+      'plan: 01',
+      '---',
+      '',
+      '# Summary',
+    ].join('\n');
+    const fm = extractFrontmatter(summaryContent);
+    assert.equal(fm.executed_by, undefined);
+  });
+
+  it('handles empty executed_by field', () => {
+    const summaryContent = [
+      '---',
+      'phase: 130-verification',
+      'plan: 01',
+      'executed_by: ""',
+      '---',
+      '',
+      '# Summary',
+    ].join('\n');
+    const fm = extractFrontmatter(summaryContent);
+    assert.equal(fm.executed_by, '');
+  });
+});
+
+describe('STATE.md milestone-context quick detection', () => {
+  it('regex matches milestone-context quick entries', () => {
+    const stateTable = '| 260407-shw | Move archives | 2026-04-07 | abc123 | done | milestone (v21.0) |';
+    const pattern = /\|\s*(\S+)\s*\|[^|]*\|[^|]*\|[^|]*\|[^|]*\|\s*milestone\s*\(([^)]+)\)\s*\|/gi;
+    const match = pattern.exec(stateTable);
+    assert.ok(match, 'regex should match milestone-context entry');
+    assert.equal(match[1], '260407-shw');
+    assert.equal(match[2], 'v21.0');
+  });
+
+  it('regex does not match non-milestone quick entries', () => {
+    const stateTable = '| 260407-shw | Move archives | 2026-04-07 | abc123 | done | quick/260407-shw-move-archives |';
+    const pattern = /\|\s*(\S+)\s*\|[^|]*\|[^|]*\|[^|]*\|[^|]*\|\s*milestone\s*\(([^)]+)\)\s*\|/gi;
+    const match = pattern.exec(stateTable);
+    assert.equal(match, null, 'regex should not match non-milestone entry');
+  });
+});
+
+describe('checkFourEyes', () => {
+  it('is exported as a function', () => {
+    assert.equal(typeof checkFourEyes, 'function');
+  });
+
+  describe('return shape', () => {
+    it('always returns object with required fields', () => {
+      const result = checkFourEyes([], 'User', 'off');
+      assert.ok('passed' in result);
+      assert.ok('mode' in result);
+      assert.ok('currentUser' in result);
+      assert.ok('contributors' in result);
+      assert.ok('matchedUser' in result);
+      assert.ok('message' in result);
+    });
+  });
+
+  describe('off mode (REQ-06)', () => {
+    it('always passes regardless of match', () => {
+      const result = checkFourEyes(
+        ['Adrian King <a@x.com>'],
+        'Adrian King <a@x.com>',
+        'off'
+      );
+      assert.equal(result.passed, true);
+      assert.equal(result.mode, 'off');
+      assert.equal(result.matchedUser, null);
+    });
+
+    it('passes with empty contributors', () => {
+      const result = checkFourEyes([], 'User', 'off');
+      assert.equal(result.passed, true);
+    });
+  });
+
+  describe('warn mode (REQ-07)', () => {
+    it('fails when currentUser matches a contributor', () => {
+      const result = checkFourEyes(
+        ['Adrian King <a@x.com>'],
+        'Adrian King <a@x.com>',
+        'warn'
+      );
+      assert.equal(result.passed, false);
+      assert.equal(result.mode, 'warn');
+      assert.equal(result.matchedUser, 'Adrian King <a@x.com>');
+      assert.ok(result.message.includes('warning'));
+    });
+
+    it('passes when currentUser does not match any contributor', () => {
+      const result = checkFourEyes(
+        ['Adrian King <a@x.com>'],
+        'Other User <o@x.com>',
+        'warn'
+      );
+      assert.equal(result.passed, true);
+      assert.equal(result.matchedUser, null);
+    });
+
+    it('passes with empty contributors', () => {
+      const result = checkFourEyes([], 'User', 'warn');
+      assert.equal(result.passed, true);
+    });
+  });
+
+  describe('enforce mode (REQ-08)', () => {
+    it('fails when currentUser matches a contributor', () => {
+      const result = checkFourEyes(
+        ['Adrian King <a@x.com>'],
+        'Adrian King <a@x.com>',
+        'enforce'
+      );
+      assert.equal(result.passed, false);
+      assert.equal(result.mode, 'enforce');
+      assert.equal(result.matchedUser, 'Adrian King <a@x.com>');
+      assert.ok(result.message.includes('violation'));
+    });
+
+    it('passes when currentUser does not match any contributor', () => {
+      const result = checkFourEyes(
+        ['Adrian King <a@x.com>'],
+        'Other User <o@x.com>',
+        'enforce'
+      );
+      assert.equal(result.passed, true);
+    });
+  });
+
+  describe('normalized comparison (CTR-04)', () => {
+    it('matches "Name" against "Name <email>" (same person, different format)', () => {
+      const result = checkFourEyes(
+        ['Adrian King'],
+        'Adrian King <a@x.com>',
+        'warn'
+      );
+      assert.equal(result.passed, false);
+      assert.ok(result.matchedUser);
+    });
+
+    it('matches case-insensitively', () => {
+      const result = checkFourEyes(
+        ['adrian king <a@x.com>'],
+        'Adrian King <a@x.com>',
+        'warn'
+      );
+      assert.equal(result.passed, false);
+    });
+  });
+
+  describe('empty contributors (CTR-05)', () => {
+    it('passes in warn mode with empty array', () => {
+      const result = checkFourEyes([], 'User', 'warn');
+      assert.equal(result.passed, true);
+    });
+
+    it('passes in enforce mode with empty array', () => {
+      const result = checkFourEyes([], 'User', 'enforce');
+      assert.equal(result.passed, true);
+    });
+
+    it('passes in enforce mode with null contributors', () => {
+      const result = checkFourEyes(null, 'User', 'enforce');
+      assert.equal(result.passed, true);
+    });
+  });
+
+  describe('invalid mode', () => {
+    it('treats invalid mode as off', () => {
+      const result = checkFourEyes(
+        ['User <u@x.com>'],
+        'User <u@x.com>',
+        'strict'
+      );
+      assert.equal(result.passed, true);
+      assert.equal(result.mode, 'off');
+    });
+
+    it('treats boolean true as off', () => {
+      const result = checkFourEyes(
+        ['User <u@x.com>'],
+        'User <u@x.com>',
+        true
+      );
+      assert.equal(result.passed, true);
+      assert.equal(result.mode, 'off');
+    });
+
+    it('treats undefined mode as off', () => {
+      const result = checkFourEyes(
+        ['User <u@x.com>'],
+        'User <u@x.com>',
+        undefined
+      );
+      assert.equal(result.passed, true);
+      assert.equal(result.mode, 'off');
+    });
+  });
+
+  describe('multiple contributors', () => {
+    it('detects match among multiple contributors', () => {
+      const result = checkFourEyes(
+        ['Alice <a@x.com>', 'Bob <b@x.com>', 'Charlie <c@x.com>'],
+        'Bob <b@x.com>',
+        'enforce'
+      );
+      assert.equal(result.passed, false);
+      assert.equal(result.matchedUser, 'Bob <b@x.com>');
+    });
+
+    it('passes when current user not among multiple contributors', () => {
+      const result = checkFourEyes(
+        ['Alice <a@x.com>', 'Bob <b@x.com>'],
+        'Charlie <c@x.com>',
+        'enforce'
+      );
+      assert.equal(result.passed, true);
+    });
+
+    it('includes all contributors in result', () => {
+      const contribs = ['Alice <a@x.com>', 'Bob <b@x.com>'];
+      const result = checkFourEyes(contribs, 'Alice <a@x.com>', 'warn');
+      assert.deepEqual(result.contributors, contribs);
+    });
+  });
+
+  describe('no-throw guarantee', () => {
+    it('does not throw with null currentUser', () => {
+      const result = checkFourEyes(['User'], null, 'warn');
+      assert.equal(result.passed, true);
+    });
+
+    it('does not throw with empty currentUser', () => {
+      const result = checkFourEyes(['User'], '', 'warn');
+      assert.equal(result.passed, true);
+    });
+  });
+});