@ktpartners/dgs-platform 3.0.4 → 3.3.0

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

@@ -283,18 +283,44 @@ function cmdResolveModel(cwd, agentType, raw) {
  *   Config loading still uses cwd. Used by fast-path in milestone-context to
  *   commit in a worktree while loading config from the planning root.
  */
-function cmdCommit(cwd, message, files, raw, amend, push, repoCwd) {
-  if (!message && !amend) {
-    error('commit message required');
-  }
+// Collect the list of still-dirty paths in `gitCwd` immediately after a
+// commit (or nothing_to_commit). Purely informational: populates
+// `result.dirty_after` so callers can detect verify-step side effects
+// (formatter reflows, type narrowings) that leaked outside the staged
+// file set. Never throws — returns [] on any error.
+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+/, '')); // strip two-char XY status prefix + space
+}
 
+/**
+ * Internal commit primitive — RETURNS the JSON result object instead of
+ * calling output()/process.exit. Extracted from cmdCommit for reuse by
+ * verifyPlanCommit (REL-01, Phase 156). External callers should keep
+ * using cmdCommit; this helper is library-internal only.
+ *
+ * @param {string} cwd - Planning root (config loaded from here)
+ * @param {string} message - Commit message (required unless amend)
+ * @param {string[]|undefined} files - Files to stage; if empty/undefined,
+ *   the historical behaviour is to fall back to ['.'] (sweeping the
+ *   working tree). REL-01's verifyPlanCommit guards against this fallback
+ *   for the orchestrator commit case BEFORE it ever reaches commitInternal.
+ * @param {boolean} amend
+ * @param {boolean} push
+ * @param {string} [repoCwd] - Where git operations actually run.
+ * @returns {object} JSON result matching cmdCommit's existing contract.
+ */
+function commitInternal(cwd, message, files, amend, push, repoCwd) {
   const config = loadConfig(cwd);
 
   // Check commit_docs config
   if (!config.commit_docs) {
-    const result = { committed: false, hash: null, reason: 'skipped_commit_docs_false' };
-    output(result, raw, 'skipped');
-    return;
+    return { committed: false, hash: null, reason: 'skipped_commit_docs_false' };
   }
 
   // Resolve git-operation cwd: use repoCwd when provided, otherwise cwd.
@@ -313,19 +339,15 @@ function cmdCommit(cwd, message, files, raw, amend, push, repoCwd) {
   const commitResult = execGit(gitCwd, commitArgs);
   if (commitResult.exitCode !== 0) {
     if (commitResult.stdout.includes('nothing to commit') || commitResult.stderr.includes('nothing to commit')) {
-      const result = { committed: false, hash: null, reason: 'nothing_to_commit' };
-      output(result, raw, 'nothing');
-      return;
+      return { committed: false, hash: null, reason: 'nothing_to_commit', dirty_after: collectDirtyAfter(gitCwd) };
     }
-    const result = { committed: false, hash: null, reason: 'nothing_to_commit', error: commitResult.stderr };
-    output(result, raw, 'nothing');
-    return;
+    return { committed: false, hash: null, reason: 'nothing_to_commit', error: commitResult.stderr, dirty_after: collectDirtyAfter(gitCwd) };
   }
 
   // Get short hash
   const hashResult = execGit(gitCwd, ['rev-parse', '--short', 'HEAD']);
   const hash = hashResult.exitCode === 0 ? hashResult.stdout : null;
-  const result = { committed: true, hash, reason: 'committed' };
+  const result = { committed: true, hash, reason: 'committed', dirty_after: collectDirtyAfter(gitCwd) };
 
   // Handle push if requested
   if (push) {
@@ -347,7 +369,234 @@ function cmdCommit(cwd, message, files, raw, amend, push, repoCwd) {
     // 'off' or any other value: no push fields added
   }
 
-  output(result, raw, hash || 'committed');
+  return result;
+}
+
+function cmdCommit(cwd, message, files, raw, amend, push, repoCwd) {
+  if (!message && !amend) {
+    error('commit message required');
+  }
+
+  const result = commitInternal(cwd, message, files, amend, push, repoCwd);
+
+  // Branch labels per the original cmdCommit output() calls
+  if (result.reason === 'skipped_commit_docs_false') {
+    output(result, raw, 'skipped');
+    return;
+  }
+  if (result.reason === 'nothing_to_commit') {
+    output(result, raw, 'nothing');
+    return;
+  }
+  output(result, raw, result.hash || 'committed');
+}
+
+/**
+ * REL-01 (Phase 156, plan 02): orchestrator-side commit + verification
+ * helper consumed by /dgs:plan-phase to commit planner-reported
+ * created_files. Guarantees:
+ *
+ * - Empty createdFiles → returns plan-commit-incomplete WITHOUT calling
+ *   commitInternal. Defends against cmdCommit's `['.']` fallback that
+ *   would otherwise sweep the working tree (Hypothesis C from
+ *   156-Q1-FINDINGS.md).
+ * - commit_docs:false → silent success ({ ok: true, hash: null,
+ *   reason: 'skipped_commit_docs_false' }). NOT a failure.
+ * - cmdCommit failure → plan-commit-incomplete with reason: 'commit_failed'.
+ * - Verification: every entry in (createdFiles + extraFiles) MUST appear
+ *   in `git show --name-only HEAD`; mismatches → plan-commit-incomplete
+ *   with reason: 'verification_failed' and a `missing` array.
+ *
+ * @param {string} cwd - Planning root (config loaded from here)
+ * @param {object} options - {
+ *     message: string (REQUIRED),
+ *     createdFiles: string[] (REQUIRED),
+ *     extraFiles?: string[],
+ *     repoCwd?: string,
+ *     push?: boolean,
+ *   }
+ * @param {boolean} raw - Emit raw JSON via output() if true.
+ * @returns {object} Returns the result object directly (so the test
+ *   harness can assert on it). Also calls output() when invoked from CLI.
+ */
+function verifyPlanCommit(cwd, options, raw) {
+  const opts = options || {};
+  const message = opts.message;
+  const createdFiles = opts.createdFiles;
+  const extraFiles = opts.extraFiles || [];
+  const repoCwd = opts.repoCwd;
+  const push = !!opts.push;
+
+  // verifyPlanCommit is a pure helper — it RETURNS the result object
+  // (so library callers and tests can assert on it). The `raw` argument
+  // is accepted for CLI dispatch parity but is intentionally unused
+  // here; the dgs-tools CLI dispatcher (dgs-tools.cjs) is responsible
+  // for calling output()/process.exit on the returned object.
+  void raw;
+
+  if (!message) {
+    return {
+      ok: false,
+      exitLabel: 'plan-commit-incomplete',
+      reason: 'missing_message',
+    };
+  }
+
+  // Empty-list guard — defends Hypothesis C (cmdCommit `['.']` fallback)
+  if (!Array.isArray(createdFiles) || createdFiles.length === 0) {
+    return {
+      ok: false,
+      exitLabel: 'plan-commit-incomplete',
+      reason: 'empty_created_files',
+    };
+  }
+
+  const filesToCommit = [...createdFiles, ...extraFiles];
+
+  const commitResult = commitInternal(cwd, message, filesToCommit, false, push, repoCwd);
+
+  // commit_docs config gate — silent success
+  if (commitResult.reason === 'skipped_commit_docs_false') {
+    return {
+      ok: true,
+      hash: null,
+      reason: 'skipped_commit_docs_false',
+    };
+  }
+
+  // Any non-success commit reason is a plan-commit-incomplete failure
+  if (commitResult.committed !== true) {
+    return {
+      ok: false,
+      exitLabel: 'plan-commit-incomplete',
+      reason: 'commit_failed',
+      commit_reason: commitResult.reason,
+      error: commitResult.error,
+    };
+  }
+
+  // Verification: every reported path MUST appear in HEAD
+  const gitCwd = repoCwd || cwd;
+  const showResult = execGit(gitCwd, ['show', '--name-only', '--pretty=', 'HEAD']);
+  const committedFiles = (showResult.stdout || '')
+    .split('\n')
+    .map(l => l.trim())
+    .filter(Boolean);
+  const missing = filesToCommit.filter(f => !committedFiles.includes(f));
+
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      exitLabel: 'plan-commit-incomplete',
+      reason: 'verification_failed',
+      hash: commitResult.hash,
+      missing,
+      committedFiles,
+    };
+  }
+
+  return {
+    ok: true,
+    hash: commitResult.hash,
+    reason: 'committed',
+    files_verified: filesToCommit,
+    missing: [],
+  };
+}
+
+/**
+ * REL-02 (Phase 156, plan 03): compute the executor's final-commit
+ * phase-dir sweep. Always sweeps the current phase directory and takes
+ * the UNION with the executor-reported modified_files list, then
+ * scope-filters out anything that does not start with the
+ * ${phasesDir}/${phaseDir}/ prefix.
+ *
+ * Hard scope guarantee: dirty files in sibling phases, ideas/, specs/,
+ * or the project root are NEVER returned in `swept`. They are returned
+ * in `dropped` for diagnostic visibility.
+ *
+ * @param {string} cwd - Planning root (where git status runs)
+ * @param {object} options - {
+ *     phasesDir: string,        // e.g. 'projects/gsd/phases'
+ *     phaseDir: string,         // e.g. '156-idea-26-closure-...'
+ *     modifiedFiles?: string[]  // executor-reported paths (planning-root-relative)
+ *   }
+ * @param {boolean} raw
+ * @returns {{
+ *   swept: string[],         // commit list — UNION, scope-filtered, sorted
+ *   dropped: string[],       // out-of-scope paths the helper rejected
+ *   gitDirtyPaths: string[], // git-discovered phase-dir paths (pre-union)
+ *   reportedPaths: string[], // executor-reported list (pre-union)
+ *   scopePrefix: string      // ${phasesDir}/${phaseDir}/
+ * }}
+ */
+function computePhaseSweep(cwd, options, raw) {
+  const opts = options || {};
+  const phasesDir = opts.phasesDir;
+  const phaseDir = opts.phaseDir;
+  const reportedPathsRaw = opts.modifiedFiles || [];
+
+  void raw;
+
+  if (!phasesDir || !phaseDir) {
+    return {
+      swept: [],
+      dropped: [],
+      gitDirtyPaths: [],
+      reportedPaths: [],
+      scopePrefix: null,
+      error: 'phasesDir and phaseDir required for compute-phase-sweep',
+    };
+  }
+
+  const scopePrefix = `${phasesDir}/${phaseDir}/`;
+
+  // Run path-scoped porcelain. Use --untracked-files=all so untracked
+  // files inside untracked directories are listed individually rather
+  // than collapsed into a single directory entry like `phases/{dir}/`.
+  const gitArgs = ['status', '--porcelain', '--untracked-files=all', '--', `${phasesDir}/${phaseDir}`];
+  const gitResult = execGit(cwd, gitArgs);
+  const gitDirtyPaths = gitResult.exitCode === 0
+    ? (gitResult.stdout || '')
+        .split('\n')
+        .map(l => l.trim())
+        .filter(Boolean)
+        // Strip 2-char XY status prefix + space (matches collectDirtyAfter)
+        .map(l => l.replace(/^..\s+/, ''))
+    : [];
+
+  // Strip optional `repoName:` prefix from reported paths — multi-repo
+  // entries with explicit repoName are out of scope for the planning-root
+  // sweep (they route through their own resolveRepoRelativePath flow).
+  const reportedPaths = reportedPathsRaw
+    .map(p => {
+      // If the entry contains a `:` and the leading segment looks like a
+      // repo name (no `/`), treat it as repoName:path and drop it for
+      // planning-root sweep purposes.
+      const colonIdx = p.indexOf(':');
+      if (colonIdx > 0 && p.indexOf('/') > colonIdx) return null;
+      return p;
+    })
+    .filter(p => p !== null);
+
+  // Compute the UNION (dedupe via Set)
+  const candidates = Array.from(new Set([...gitDirtyPaths, ...reportedPaths]));
+
+  // Belt-and-braces: scope-filter via prefix check
+  const swept = candidates
+    .filter(p => p.startsWith(scopePrefix))
+    .sort();
+  const dropped = candidates
+    .filter(p => !p.startsWith(scopePrefix))
+    .sort();
+
+  return {
+    swept,
+    dropped,
+    gitDirtyPaths,
+    reportedPaths,
+    scopePrefix,
+  };
 }
 
 /**
@@ -530,7 +779,9 @@ function cmdSummaryExtract(cwd, summaryPath, fields, raw) {
     tech_added: (fm['tech-stack'] && fm['tech-stack'].added) || [],
     patterns: fm['patterns-established'] || [],
     decisions: parseDecisions(fm['key-decisions']),
-    requirements_completed: fm['requirements-completed'] || [],
+    // REL-07/10 transitional dual-read: canonical underscore key takes precedence;
+    // legacy hyphen key fallback preserves audit-readability for archived v23.1 SUMMARYs.
+    requirements_completed: fm['requirements_completed'] || fm['requirements-completed'] || [],
   };
 
   // If fields specified, filter to only those fields
@@ -849,6 +1100,46 @@ function cmdContextHelp(raw) {
   output(result, raw, result.subcommands.map(s => s.usage).join('\n'));
 }
 
+// REL-08 (Phase 157): pre-commit precondition gate.
+// Reads PLAN.md `requirements:` and SUMMARY.md `requirements_completed:` (canonical) /
+// `requirements-completed:` (legacy fallback). If PLAN is non-empty AND SUMMARY is empty,
+// writes `summary-frontmatter-mismatch:` label to stderr and exits non-zero.
+// NEVER writes to the working tree — read-only check.
+function cmdFinalCommitPrecondition(cwd, options) {
+  const planPath = options && options.plan;
+  const summaryPath = options && options.summary;
+  if (!planPath || !summaryPath) {
+    process.stderr.write('summary-frontmatter-mismatch: --plan and --summary required\n');
+    process.exit(2);
+  }
+  const { extractFrontmatter } = require('./frontmatter.cjs');
+  const planAbs = path.isAbsolute(planPath) ? planPath : path.join(cwd, planPath);
+  const summaryAbs = path.isAbsolute(summaryPath) ? summaryPath : path.join(cwd, summaryPath);
+
+  if (!fs.existsSync(planAbs)) {
+    process.stderr.write(`summary-frontmatter-mismatch: PLAN not found at ${planPath}\n`);
+    process.exit(2);
+  }
+  if (!fs.existsSync(summaryAbs)) {
+    process.stderr.write(`summary-frontmatter-mismatch: SUMMARY not found at ${summaryPath}\n`);
+    process.exit(2);
+  }
+  const planFm = extractFrontmatter(fs.readFileSync(planAbs, 'utf-8'));
+  const summaryFm = extractFrontmatter(fs.readFileSync(summaryAbs, 'utf-8'));
+  const planReq = Array.isArray(planFm.requirements) ? planFm.requirements : [];
+  // Dual-read: canonical underscore key first, legacy hyphen fallback (REL-07/10 dual-read).
+  const summaryReq = summaryFm['requirements_completed'] || summaryFm['requirements-completed'] || [];
+
+  if (planReq.length > 0 && summaryReq.length === 0) {
+    process.stderr.write(
+      `summary-frontmatter-mismatch: PLAN.md declared requirements [${planReq.join(', ')}]; ` +
+      `SUMMARY.md requirements_completed is empty. Re-run executor or manually populate before committing.\n`
+    );
+    process.exit(2);
+  }
+  process.exit(0);
+}
+
 module.exports = {
   TODO_STATUSES,
   setTodoStatus,
@@ -859,6 +1150,9 @@ module.exports = {
   cmdHistoryDigest,
   cmdResolveModel,
   cmdCommit,
+  commitInternal,
+  verifyPlanCommit,
+  computePhaseSweep,
   cmdPlanFinalize,
   cmdSummaryExtract,
   cmdWebsearch,
@@ -866,4 +1160,5 @@ module.exports = {
   cmdTodoComplete,
   cmdScaffold,
   cmdContextHelp,
+  cmdFinalCommitPrecondition,
 };

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

@@ -541,6 +541,121 @@ describe('cmdCommit with --repo-cwd flag', () => {
   });
 });
 
+// ─── cmdCommit populates dirty_after ────────────────────────────────────────
+// Uses captureStdout (not captureCommitOutput) because cmdCommit's output() goes
+// through process.stdout.write + process.exit, not console.log. captureStdout
+// mocks both correctly. captureCommitOutput exists for historical reasons but
+// doesn't actually intercept output() writes — its assertions silently no-op
+// because process.exit kills the test worker before they run.
+
+describe('cmdCommit populates dirty_after', () => {
+  let fixture;
+  let commands;
+
+  beforeEach(() => {
+    fixture = setupGitFixture('off');
+    commands = require('./commands.cjs');
+  });
+
+  afterEach(() => {
+    fixture.cleanup();
+  });
+
+  it('returns dirty_after=[] when tree is clean after commit', () => {
+    writeAndStageFile(fixture.cwd, 'clean-after.txt', 'clean');
+    const capture = captureStdout(() => {
+      commands.cmdCommit(fixture.cwd, 'test: clean dirty_after', [], false, false, false);
+    });
+    const result = capture.json;
+    assert.ok(result, 'expected JSON result. stdout: ' + capture.stdout);
+    assert.equal(result.committed, true);
+    assert.ok(result.hash);
+    assert.ok(Array.isArray(result.dirty_after), 'dirty_after should be an array');
+    assert.equal(result.dirty_after.length, 0, `clean tree should have empty dirty_after, got: ${JSON.stringify(result.dirty_after)}`);
+  });
+
+  it('includes unstaged files in dirty_after after commit', () => {
+    // Stage and commit file A
+    writeAndStageFile(fixture.cwd, 'staged-file.txt', 'staged');
+    // Write (but do NOT stage) file B — it should remain dirty after the commit
+    fs.writeFileSync(path.join(fixture.cwd, 'dirty-file.txt'), 'unstaged');
+
+    const capture = captureStdout(() => {
+      commands.cmdCommit(fixture.cwd, 'test: dirty dirty_after', ['staged-file.txt'], false, false, false);
+    });
+    const result = capture.json;
+    assert.ok(result, 'expected JSON result. stdout: ' + capture.stdout);
+    assert.equal(result.committed, true);
+    assert.ok(result.hash);
+    assert.ok(Array.isArray(result.dirty_after), 'dirty_after should be an array');
+    assert.ok(
+      result.dirty_after.includes('dirty-file.txt'),
+      `dirty_after should include the unstaged file, got: ${JSON.stringify(result.dirty_after)}`
+    );
+  });
+
+  it('emits dirty_after in nothing_to_commit branch', () => {
+    // Create an unstaged file to make the tree dirty
+    fs.writeFileSync(path.join(fixture.cwd, 'unstaged-only.txt'), 'unstaged');
+
+    const capture = captureStdout(() => {
+      // Pass a pathspec that matches nothing so staging is a no-op — the
+      // unstaged file remains dirty AND there is nothing_to_commit.
+      commands.cmdCommit(fixture.cwd, 'test: nothing', ['nonexistent-pathspec-zzz'], false, false, false);
+    });
+    const result = capture.json;
+    assert.ok(result, 'expected JSON result. stdout: ' + capture.stdout);
+    assert.equal(result.committed, false, `expected committed=false, got result: ${JSON.stringify(result)}`);
+    assert.equal(result.reason, 'nothing_to_commit');
+    assert.ok(Array.isArray(result.dirty_after), 'dirty_after should be an array even when nothing_to_commit');
+    assert.ok(
+      result.dirty_after.includes('unstaged-only.txt'),
+      `dirty_after should include the unstaged file in nothing_to_commit branch, got: ${JSON.stringify(result.dirty_after)}`
+    );
+  });
+
+  it('runs porcelain in repoCwd when --repo-cwd is passed (not in cwd)', () => {
+    // Second fixture for the worktree
+    const worktreeFixture = setupGitFixture('off');
+    try {
+      // Write file in the worktree ONLY — planning root stays untouched
+      const stagedName = 'worktree-staged.txt';
+      fs.writeFileSync(path.join(worktreeFixture.cwd, stagedName), 'content');
+      execSync(`git add "${stagedName}"`, { cwd: worktreeFixture.cwd, stdio: 'pipe' });
+      // Dirty file in the worktree that is NOT staged
+      fs.writeFileSync(path.join(worktreeFixture.cwd, 'worktree-dirty.txt'), 'unstaged');
+      // Separately, make the PLANNING root dirty — this should NOT appear in dirty_after
+      fs.writeFileSync(path.join(fixture.cwd, 'planning-dirty.txt'), 'should-not-see-this');
+
+      const capture = captureStdout(() => {
+        commands.cmdCommit(
+          fixture.cwd,            // cwd (planning root)
+          'test: repo-cwd dirty', // message
+          [stagedName],           // files (relative to repoCwd)
+          false,                  // raw=false -> JSON output
+          false,
+          false,
+          worktreeFixture.cwd     // repoCwd
+        );
+      });
+      const result = capture.json;
+      assert.ok(result, 'expected JSON result. stdout: ' + capture.stdout);
+      assert.equal(result.committed, true);
+      assert.ok(Array.isArray(result.dirty_after), 'dirty_after should be an array');
+      assert.ok(
+        result.dirty_after.includes('worktree-dirty.txt'),
+        `dirty_after should include the worktree-unstaged file, got: ${JSON.stringify(result.dirty_after)}`
+      );
+      assert.ok(
+        !result.dirty_after.includes('planning-dirty.txt'),
+        `dirty_after must NOT include planning-root files when --repo-cwd is set, got: ${JSON.stringify(result.dirty_after)}`
+      );
+    } finally {
+      worktreeFixture.cleanup();
+    }
+  });
+});
+
 // ─── TODO_STATUSES constant ─────────────────────────────────────────────────
 
 describe('TODO_STATUSES constant', () => {