@ktpartners/dgs-platform 2.9.0 → 3.3.0

package/deliver-great-systems/bin/lib/flat-migration.test.cjs

@@ -0,0 +1,396 @@
+/**
+ * Tests for migrateFlatStatus — flat status directory migration
+ *
+ * Phase 134 (v20.0): Migrates ideas/todos/jobs from state subdirectories
+ * to flat directories with frontmatter status fields.
+ */
+
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+const { createTempDir, cleanupDir, writeFile, initGitRepo } = require('./test-helpers.cjs');
+const { migrateFlatStatus } = require('./migration.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Creates a temp directory with git init, returns realpathSync'd path
+ * (macOS /var -> /private/var symlink fix from Phase 118).
+ */
+function makeGitDir() {
+  const tmpDir = createTempDir('flat-mig-test-');
+  initGitRepo(tmpDir);
+  return fs.realpathSync(tmpDir);
+}
+
+/**
+ * Creates a temp directory without git, returns realpathSync'd path.
+ */
+function makePlainDir() {
+  const tmpDir = createTempDir('flat-mig-test-');
+  return fs.realpathSync(tmpDir);
+}
+
+function gitCommitAll(dir, msg) {
+  const { execSync } = require('child_process');
+  execSync('git add -A', { cwd: dir, stdio: 'pipe' });
+  execSync(`git commit -m "${msg}" --allow-empty`, { cwd: dir, stdio: 'pipe' });
+}
+
+function readFile(dir, relPath) {
+  return fs.readFileSync(path.join(dir, relPath), 'utf-8');
+}
+
+function fileExists(dir, relPath) {
+  return fs.existsSync(path.join(dir, relPath));
+}
+
+/**
+ * Create a minimal idea file with frontmatter
+ */
+function makeIdea(id, title, opts = {}) {
+  const fm = [
+    '---',
+    `id: ${id}`,
+    `title: "${title}"`,
+  ];
+  if (opts.status) fm.push(`status: ${opts.status}`);
+  if (opts.consolidated_into) fm.push(`consolidated_into: "${opts.consolidated_into}"`);
+  if (opts.consolidated_from) {
+    fm.push('consolidated_from:');
+    for (const src of opts.consolidated_from) {
+      fm.push(`  - "${src}"`);
+    }
+  }
+  fm.push(`created: "2026-01-01T00:00:00Z"`);
+  fm.push(`updated: "2026-01-01T00:00:00Z"`);
+  fm.push('---');
+  fm.push('');
+  fm.push(`# ${title}`);
+  fm.push('');
+  fm.push(opts.body || 'Some idea content.');
+  if (opts.researchLog) {
+    fm.push('');
+    fm.push('## Research Log');
+    fm.push('');
+    fm.push(opts.researchLog);
+  }
+  return fm.join('\n') + '\n';
+}
+
+/**
+ * Create a minimal todo file (no frontmatter — tests that frontmatter gets added)
+ */
+function makeTodo(title) {
+  return `# ${title}\n\nSome todo content.\n`;
+}
+
+/**
+ * Create a minimal job file with bold-key Status header
+ */
+function makeJob(title, status) {
+  return `---\ntitle: "${title}"\n---\n\n# ${title}\n\n**Status:** ${status}\n\nJob details.\n`;
+}
+
+// ─── Tests ──────────────────────────────────────────────────────────────────
+
+describe('migrateFlatStatus', () => {
+  let tmpDir;
+
+  afterEach(() => {
+    if (tmpDir) cleanupDir(tmpDir);
+  });
+
+  describe('idempotency', () => {
+    it('returns early when flat_status_migration_done is true', () => {
+      tmpDir = makePlainDir();
+      writeFile(tmpDir, 'config.local.json', JSON.stringify({ flat_status_migration_done: true }));
+      const result = migrateFlatStatus(tmpDir);
+      assert.equal(result.migrated, false);
+      assert.equal(result.actions.length, 0);
+    });
+
+    it('sets flag and returns when no legacy files exist', () => {
+      tmpDir = makePlainDir();
+      writeFile(tmpDir, 'ideas/001-test.md', makeIdea(1, 'Test', { status: 'pending' }));
+      const result = migrateFlatStatus(tmpDir);
+      assert.equal(result.migrated, false);
+      assert.equal(result.actions.length, 0);
+      const config = JSON.parse(readFile(tmpDir, 'config.local.json'));
+      assert.equal(config.flat_status_migration_done, true);
+    });
+  });
+
+  describe('dry-run mode', () => {
+    it('returns actions without modifying files', () => {
+      tmpDir = makePlainDir();
+      writeFile(tmpDir, 'ideas/pending/001-test.md', makeIdea(1, 'Test'));
+
+      const result = migrateFlatStatus(tmpDir);
+
+      assert.equal(result.dryRun, true);
+      assert.equal(result.migrated, false);
+      assert.ok(result.actions.length > 0, 'should have actions');
+      assert.equal(result.filesMoved, 1);
+      // File should NOT have been moved
+      assert.ok(fileExists(tmpDir, 'ideas/pending/001-test.md'), 'original file should still exist');
+      assert.ok(!fileExists(tmpDir, 'ideas/001-test.md'), 'destination should not exist');
+    });
+
+    it('reports correct counts for multi-subsystem migration', () => {
+      tmpDir = makePlainDir();
+      writeFile(tmpDir, 'ideas/pending/001-idea.md', makeIdea(1, 'Idea'));
+      writeFile(tmpDir, 'ideas/done/002-done-idea.md', makeIdea(2, 'Done Idea'));
+      writeFile(tmpDir, 'todos/pending/todo-1.md', makeTodo('Todo 1'));
+      writeFile(tmpDir, 'jobs/completed/job-v1.md', makeJob('Job v1', 'completed'));
+
+      const result = migrateFlatStatus(tmpDir);
+
+      assert.equal(result.dryRun, true);
+      assert.equal(result.filesMoved, 4);
+      assert.equal(result.statusFieldsAdded, 4);
+    });
+  });
+
+  describe('apply mode', () => {
+    it('moves idea files and adds status frontmatter', () => {
+      tmpDir = makeGitDir();
+      writeFile(tmpDir, 'ideas/pending/001-test.md', makeIdea(1, 'Test'));
+      writeFile(tmpDir, 'ideas/done/002-shipped.md', makeIdea(2, 'Shipped'));
+      gitCommitAll(tmpDir, 'add ideas');
+
+      const result = migrateFlatStatus(tmpDir, { apply: true });
+
+      assert.equal(result.migrated, true);
+      assert.equal(result.dryRun, false);
+      assert.ok(result.commitHash, 'should have commit hash');
+
+      // Files moved to flat directory
+      assert.ok(fileExists(tmpDir, 'ideas/001-test.md'), 'idea should be in flat dir');
+      assert.ok(fileExists(tmpDir, 'ideas/002-shipped.md'), 'done idea should be in flat dir');
+      assert.ok(!fileExists(tmpDir, 'ideas/pending/001-test.md'), 'original should be gone');
+      assert.ok(!fileExists(tmpDir, 'ideas/done/002-shipped.md'), 'original should be gone');
+
+      // Status frontmatter added
+      const pendingContent = readFile(tmpDir, 'ideas/001-test.md');
+      const pendingFm = extractFrontmatter(pendingContent);
+      assert.equal(pendingFm.status, 'pending');
+
+      const doneContent = readFile(tmpDir, 'ideas/002-shipped.md');
+      const doneFm = extractFrontmatter(doneContent);
+      assert.equal(doneFm.status, 'done');
+    });
+
+    it('maps todo states correctly (completed -> done, resolved -> done)', () => {
+      tmpDir = makeGitDir();
+      writeFile(tmpDir, 'todos/pending/todo-1.md', makeTodo('Pending Todo'));
+      writeFile(tmpDir, 'todos/completed/todo-2.md', makeTodo('Completed Todo'));
+      writeFile(tmpDir, 'todos/done/todo-3.md', makeTodo('Done Todo'));
+      writeFile(tmpDir, 'todos/resolved/todo-4.md', makeTodo('Resolved Todo'));
+      gitCommitAll(tmpDir, 'add todos');
+
+      const result = migrateFlatStatus(tmpDir, { apply: true });
+
+      assert.equal(result.migrated, true);
+
+      // All files in flat dir
+      assert.ok(fileExists(tmpDir, 'todos/todo-1.md'));
+      assert.ok(fileExists(tmpDir, 'todos/todo-2.md'));
+      assert.ok(fileExists(tmpDir, 'todos/todo-3.md'));
+      assert.ok(fileExists(tmpDir, 'todos/todo-4.md'));
+
+      // Status mappings correct
+      const todo1 = extractFrontmatter(readFile(tmpDir, 'todos/todo-1.md'));
+      assert.equal(todo1.status, 'pending');
+      const todo2 = extractFrontmatter(readFile(tmpDir, 'todos/todo-2.md'));
+      assert.equal(todo2.status, 'done');
+      const todo3 = extractFrontmatter(readFile(tmpDir, 'todos/todo-3.md'));
+      assert.equal(todo3.status, 'done');
+      const todo4 = extractFrontmatter(readFile(tmpDir, 'todos/todo-4.md'));
+      assert.equal(todo4.status, 'done');
+    });
+
+    it('flattens research docs and updates path references in ideas', () => {
+      tmpDir = makeGitDir();
+      const ideaWithResearch = makeIdea(5, 'Research Idea', {
+        researchLog: '**Document:** docs/ideas/pending/research-idea-research.md\n**Date:** 2026-01-01'
+      });
+      writeFile(tmpDir, 'ideas/pending/005-research-idea.md', ideaWithResearch);
+      writeFile(tmpDir, 'docs/ideas/pending/research-idea-research.md', '# Research\n\nFindings here.\n');
+      gitCommitAll(tmpDir, 'add research');
+
+      const result = migrateFlatStatus(tmpDir, { apply: true });
+
+      assert.equal(result.migrated, true);
+
+      // Research doc flattened
+      assert.ok(fileExists(tmpDir, 'docs/ideas/research-idea-research.md'), 'research doc in flat dir');
+      assert.ok(!fileExists(tmpDir, 'docs/ideas/pending/research-idea-research.md'), 'research doc removed from state dir');
+
+      // Path reference updated in idea
+      const ideaContent = readFile(tmpDir, 'ideas/005-research-idea.md');
+      assert.ok(ideaContent.includes('docs/ideas/research-idea-research.md'), 'path should be flat');
+      assert.ok(!ideaContent.includes('docs/ideas/pending/research-idea-research.md'), 'state path should be gone');
+    });
+
+    it('normalizes consolidated_into and consolidated_from paths', () => {
+      tmpDir = makeGitDir();
+      const consolidatedIdea = makeIdea(3, 'Old Idea', {
+        consolidated_into: 'ideas/pending/010-merged.md'
+      });
+      const mergedIdea = makeIdea(10, 'Merged', {
+        consolidated_from: ['ideas/pending/003-old-idea.md', 'ideas/done/004-another.md']
+      });
+      writeFile(tmpDir, 'ideas/consolidated/003-old-idea.md', consolidatedIdea);
+      writeFile(tmpDir, 'ideas/pending/010-merged.md', mergedIdea);
+      gitCommitAll(tmpDir, 'add consolidated');
+
+      const result = migrateFlatStatus(tmpDir, { apply: true });
+
+      assert.equal(result.migrated, true);
+      assert.ok(result.pathsNormalized > 0, 'should have normalized paths');
+
+      // Check consolidated_into normalized
+      const oldContent = readFile(tmpDir, 'ideas/003-old-idea.md');
+      assert.ok(!oldContent.includes('ideas/pending/'), 'should not have state dir in path');
+      assert.ok(oldContent.includes('ideas/010-merged.md'), 'should have flat path');
+
+      // Check consolidated_from normalized
+      const mergedContent = readFile(tmpDir, 'ideas/010-merged.md');
+      assert.ok(!mergedContent.includes('ideas/pending/003'), 'should not have state dir');
+      assert.ok(!mergedContent.includes('ideas/done/004'), 'should not have state dir');
+    });
+
+    it('validates file count (no data loss)', () => {
+      tmpDir = makeGitDir();
+      writeFile(tmpDir, 'ideas/pending/001-a.md', makeIdea(1, 'A'));
+      writeFile(tmpDir, 'ideas/done/002-b.md', makeIdea(2, 'B'));
+      writeFile(tmpDir, 'ideas/rejected/003-c.md', makeIdea(3, 'C'));
+      gitCommitAll(tmpDir, 'add ideas');
+
+      const result = migrateFlatStatus(tmpDir, { apply: true });
+
+      assert.equal(result.migrated, true);
+      assert.equal(result.filesMoved, 3);
+
+      // Count files in flat dir (should be 3 ideas)
+      const flatFiles = fs.readdirSync(path.join(tmpDir, 'ideas')).filter(f => f.endsWith('.md'));
+      assert.equal(flatFiles.length, 3, 'all 3 ideas should be in flat dir');
+    });
+
+    it('handles jobs with dual-write status (frontmatter + bold-key header)', () => {
+      tmpDir = makeGitDir();
+      writeFile(tmpDir, 'jobs/completed/milestone-v5.md', makeJob('v5 Build', 'completed'));
+      writeFile(tmpDir, 'jobs/in-progress/milestone-v6.md', makeJob('v6 Build', 'in-progress'));
+      gitCommitAll(tmpDir, 'add jobs');
+
+      const result = migrateFlatStatus(tmpDir, { apply: true });
+
+      assert.equal(result.migrated, true);
+
+      // Check frontmatter status
+      const v5Content = readFile(tmpDir, 'jobs/milestone-v5.md');
+      const v5Fm = extractFrontmatter(v5Content);
+      assert.equal(v5Fm.status, 'completed');
+
+      // Check bold-key header still present
+      assert.ok(v5Content.includes('**Status:** completed'), 'bold-key header should be updated');
+
+      const v6Content = readFile(tmpDir, 'jobs/milestone-v6.md');
+      const v6Fm = extractFrontmatter(v6Content);
+      assert.equal(v6Fm.status, 'in-progress');
+      assert.ok(v6Content.includes('**Status:** in-progress'), 'bold-key header should be updated');
+    });
+  });
+
+  describe('realistic project fixtures', () => {
+    it('handles fc-like project (done ideas, research docs, pending todos, completed jobs)', () => {
+      tmpDir = makeGitDir();
+
+      // fc-like: 7 done ideas, 5 pending ideas, 11 pending todos, 1 resolved todo, 10 completed jobs, 1 research doc
+      for (let i = 1; i <= 7; i++) {
+        writeFile(tmpDir, `ideas/done/00${i}-done-idea-${i}.md`, makeIdea(i, `Done Idea ${i}`));
+      }
+      for (let i = 8; i <= 12; i++) {
+        writeFile(tmpDir, `ideas/pending/0${i}-pending-idea-${i}.md`, makeIdea(i, `Pending Idea ${i}`));
+      }
+
+      for (let i = 1; i <= 11; i++) {
+        writeFile(tmpDir, `todos/pending/todo-${i}.md`, makeTodo(`Todo ${i}`));
+      }
+      writeFile(tmpDir, 'todos/resolved/todo-resolved.md', makeTodo('Resolved Todo'));
+
+      for (let i = 1; i <= 10; i++) {
+        writeFile(tmpDir, `jobs/completed/milestone-v${i}.md`, makeJob(`v${i} Build`, 'completed'));
+      }
+
+      writeFile(tmpDir, 'docs/ideas/pending/research-doc.md', '# Research\n\nContent.\n');
+
+      gitCommitAll(tmpDir, 'init');
+
+      const result = migrateFlatStatus(tmpDir, { apply: true });
+
+      assert.equal(result.migrated, true);
+      // 7 done + 5 pending ideas + 12 todos + 10 jobs + 1 research = 35
+      assert.equal(result.filesMoved, 35);
+
+      // Spot check: done idea has status field
+      const doneIdea = readFile(tmpDir, 'ideas/001-done-idea-1.md');
+      assert.ok(doneIdea.includes('status: done'), 'done idea should have status: done');
+
+      // Resolved todo mapped to done
+      const resolvedTodo = readFile(tmpDir, 'todos/todo-resolved.md');
+      const resolvedFm = extractFrontmatter(resolvedTodo);
+      assert.equal(resolvedFm.status, 'done');
+
+      // Research doc flattened
+      assert.ok(fileExists(tmpDir, 'docs/ideas/research-doc.md'));
+      assert.ok(!fileExists(tmpDir, 'docs/ideas/pending/research-doc.md'));
+    });
+
+    it('handles gsd-like project (mixed todo states, in-progress job)', () => {
+      tmpDir = makeGitDir();
+
+      // gsd-like: 4 done ideas, 5 pending ideas, mixed todos, 1 in-progress job
+      for (let i = 1; i <= 4; i++) {
+        writeFile(tmpDir, `ideas/done/00${i}-done-${i}.md`, makeIdea(i, `Done ${i}`));
+      }
+      for (let i = 5; i <= 9; i++) {
+        writeFile(tmpDir, `ideas/pending/00${i}-pending-${i}.md`, makeIdea(i, `Pending ${i}`));
+      }
+
+      for (let i = 1; i <= 17; i++) {
+        writeFile(tmpDir, `todos/pending/todo-p${i}.md`, makeTodo(`Pending ${i}`));
+      }
+      for (let i = 1; i <= 4; i++) {
+        writeFile(tmpDir, `todos/completed/todo-c${i}.md`, makeTodo(`Completed ${i}`));
+      }
+      for (let i = 1; i <= 9; i++) {
+        writeFile(tmpDir, `todos/done/todo-d${i}.md`, makeTodo(`Done ${i}`));
+      }
+
+      writeFile(tmpDir, 'jobs/in-progress/milestone-v20.md', makeJob('v20 Build', 'in-progress'));
+      writeFile(tmpDir, 'jobs/completed/milestone-v19.md', makeJob('v19 Build', 'completed'));
+
+      gitCommitAll(tmpDir, 'init');
+
+      const result = migrateFlatStatus(tmpDir, { apply: true });
+
+      assert.equal(result.migrated, true);
+      // 4 done + 5 pending ideas + 17 pending + 4 completed + 9 done todos + 2 jobs = 41
+      assert.equal(result.filesMoved, 41);
+
+      // All todos in flat dir with correct status
+      const completedTodo = readFile(tmpDir, 'todos/todo-c1.md');
+      const completedFm = extractFrontmatter(completedTodo);
+      assert.equal(completedFm.status, 'done', 'completed -> done');
+
+      const doneTodo = readFile(tmpDir, 'todos/todo-d1.md');
+      const doneFm = extractFrontmatter(doneTodo);
+      assert.equal(doneFm.status, 'done', 'done -> done');
+    });
+  });
+});

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

@@ -251,7 +251,7 @@ function parseMustHavesBlock(content, blockName) {
 
 const FRONTMATTER_SCHEMAS = {
   plan: { required: ['phase', 'plan', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves'] },
-  summary: { required: ['phase', 'plan', 'subsystem', 'tags', 'duration', 'completed', 'requirements-completed'] },
+  summary: { required: ['phase', 'plan', 'subsystem', 'tags', 'duration', 'completed', 'requirements_completed'] },
   verification: { required: ['phase', 'verified', 'status', 'score'] },
 };
 

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 };