@ktpartners/dgs-platform 2.9.0 → 3.3.0

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/sync.cjs

@@ -378,6 +378,75 @@ function pullAll(cwd, options = {}) {
  * @param {string[]|null} [options.repos=null] - Filter to push only specific repos by name
  * @returns {{ ok: boolean, results: Array<{ repo: string, path: string, status: string, commits: number|null, message: string }>, problems?: Array, summary: string }}
  */
+/**
+ * Push active worktree branches to remote as backup. Best-effort — failures
+ * are appended to results but do not block other sync operations.
+ *
+ * Reads worktree entries from config.local.json for the current project.
+ * Skips stale entries where the worktree directory no longer exists.
+ * Push-only — no pull of worktree branches (deferred to future).
+ *
+ * @param {string} cwd - Planning root
+ * @param {Array} results - Results array to append push outcomes to
+ */
+function _pushWorktreeBranches(cwd, results) {
+  const config = loadConfig(cwd);
+  const project = config.current_project;
+  if (!project) return;
+
+  let localConfig;
+  try {
+    const localPath = getLocalConfigPath(cwd);
+    if (!fs.existsSync(localPath)) return;
+    localConfig = JSON.parse(fs.readFileSync(localPath, 'utf-8'));
+  } catch {
+    return; // No config.local.json or invalid JSON — nothing to push
+  }
+
+  const worktrees = (localConfig.projects && localConfig.projects[project] && localConfig.projects[project].worktrees) || {};
+
+  for (const [slug, entry] of Object.entries(worktrees)) {
+    const type = entry.type; // 'milestone' or 'quick'
+    const repos = entry.repos || {};
+
+    for (const [repoName, worktreePath] of Object.entries(repos)) {
+      // Skip stale worktrees (directory doesn't exist)
+      if (!fs.existsSync(worktreePath)) continue;
+
+      // Determine branch name based on type
+      const branchName = type === 'milestone' ? 'milestone/' + slug : 'quick/' + slug;
+      const label = repoName + ' (worktree: ' + slug + ')';
+
+      try {
+        // Check if worktree has a remote
+        if (!hasRemote(worktreePath)) continue;
+
+        // Push the worktree branch from the worktree directory
+        const pushResult = execGitWithTimeout(worktreePath, ['push', '-u', 'origin', branchName], 30000);
+
+        results.push({
+          repo: label,
+          path: worktreePath,
+          status: pushResult.exitCode === 0 ? 'pushed' : 'failed',
+          commits: 0,
+          message: pushResult.exitCode === 0
+            ? 'Pushed worktree branch ' + branchName
+            : 'Failed to push ' + branchName + ': ' + (pushResult.stderr || '').trim(),
+        });
+      } catch (e) {
+        // Best-effort — failure does not block other operations
+        results.push({
+          repo: label,
+          path: worktreePath,
+          status: 'failed',
+          commits: 0,
+          message: 'Push failed: ' + (e.message || String(e)),
+        });
+      }
+    }
+  }
+}
+
 function pushAll(cwd, options = {}) {
   const { dryRun = false, force = false, repos: repoFilter = null } = options;
   let allRepos = collectSyncRepos(cwd);
@@ -468,6 +537,12 @@ function pushAll(cwd, options = {}) {
     results.push({ repo: label, path: repo.path, status: 'pushed', commits: commitCount, message: `Pushed ${commitLabel}` });
   }
 
+  // --- Worktree Branch Push ---
+  // Push active worktree branches as remote backup (best-effort, non-blocking)
+  if (!dryRun) {
+    _pushWorktreeBranches(cwd, results);
+  }
+
   // Build summary
   const pushed = results.filter(r => r.status === 'pushed').length;
   const current = results.filter(r => r.status === 'current').length;