@ktpartners/dgs-platform 2.9.0 → 3.3.0

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

@@ -4,10 +4,12 @@
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');
-const { safeReadFile, loadConfig, isGitIgnored, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, resolveModelInternal, MODEL_PROFILES, toPosixPath, output, error, findPhaseInternal } = require('./core.cjs');
-const { extractFrontmatter } = require('./frontmatter.cjs');
+const { safeReadFile, loadConfig, isGitIgnored, execGit, normalizePhaseName, comparePhaseNum, getArchivedPhaseDirs, generateSlugInternal, getMilestoneInfo, getProjectRoot, resolveModelInternal, MODEL_PROFILES, toPosixPath, output, error, findPhaseInternal } = require('./core.cjs');
+const { extractFrontmatter, spliceFrontmatter, reconstructFrontmatter } = require('./frontmatter.cjs');
 const { getPlanningRoot } = require('./paths.cjs');
 
+const TODO_STATUSES = ['pending', 'done'];
+
 function cmdGenerateSlug(text, raw) {
   if (!text) {
     error('text required for slug generation');
@@ -43,15 +45,62 @@ function cmdCurrentTimestamp(format, raw) {
 }
 
 function cmdListTodos(cwd, area, raw) {
-  const pendingDir = path.join(getPlanningRoot(cwd), 'todos', 'pending');
-
   let count = 0;
   const todos = [];
+  const seenFiles = new Set();
 
+  // Flat-first scan: check todos/ root directory
+  const flatDir = path.join(getPlanningRoot(cwd), 'todos');
   try {
-    const files = fs.readdirSync(pendingDir).filter(f => f.endsWith('.md'));
+    const flatFiles = fs.readdirSync(flatDir).filter(f => f.endsWith('.md') && !fs.statSync(path.join(flatDir, f)).isDirectory());
+    for (const file of flatFiles) {
+      try {
+        const content = fs.readFileSync(path.join(flatDir, file), 'utf-8');
+
+        // Parse frontmatter status (if present)
+        let status = null;
+        const fmMatch = content.match(/^---\n([\s\S]+?)\n---/);
+        if (fmMatch) {
+          const statusMatch = fmMatch[1].match(/^status:\s*(.+)$/m);
+          if (statusMatch) status = statusMatch[1].trim();
+        }
+
+        // Only list pending todos (default behavior)
+        if (status && status !== 'pending') continue;
+
+        const createdMatch = content.match(/^created:\s*(.+)$/m);
+        const titleMatch = content.match(/^title:\s*(.+)$/m);
+        const areaMatch = content.match(/^area:\s*(.+)$/m);
+
+        const todoArea = areaMatch ? areaMatch[1].trim() : 'general';
+        if (area && todoArea !== area) continue;
+
+        count++;
+        seenFiles.add(file);
+        todos.push({
+          file,
+          created: createdMatch ? createdMatch[1].trim() : 'unknown',
+          title: titleMatch ? titleMatch[1].trim() : 'Untitled',
+          area: todoArea,
+          status: status || 'pending',
+          path: toPosixPath(path.join(path.relative(cwd, getPlanningRoot(cwd)) || '.', 'todos', file)),
+        });
+      } catch {}
+    }
+  } catch {
+    // Flat directory may not exist
+  }
 
+  // Legacy fallback: check todos/pending/
+  const pendingDir = path.join(getPlanningRoot(cwd), 'todos', 'pending');
+  try {
+    const files = fs.readdirSync(pendingDir).filter(f => f.endsWith('.md'));
     for (const file of files) {
+      if (seenFiles.has(file)) continue; // Skip if already found in flat directory
+
+      // Legacy fallback warning
+      process.stderr.write(`[DGS] Warning: todo '${file}' found in legacy pending/ directory. Run migration to flatten.\n`);
+
       try {
         const content = fs.readFileSync(path.join(pendingDir, file), 'utf-8');
         const createdMatch = content.match(/^created:\s*(.+)$/m);
@@ -59,8 +108,6 @@ function cmdListTodos(cwd, area, raw) {
         const areaMatch = content.match(/^area:\s*(.+)$/m);
 
         const todoArea = areaMatch ? areaMatch[1].trim() : 'general';
-
-        // Apply area filter if specified
         if (area && todoArea !== area) continue;
 
         count++;
@@ -69,6 +116,7 @@ function cmdListTodos(cwd, area, raw) {
           created: createdMatch ? createdMatch[1].trim() : 'unknown',
           title: titleMatch ? titleMatch[1].trim() : 'Untitled',
           area: todoArea,
+          status: 'pending',
           path: toPosixPath(path.join(path.relative(cwd, getPlanningRoot(cwd)) || '.', 'todos', 'pending', file)),
         });
       } catch {}
@@ -98,7 +146,13 @@ function cmdVerifyPathExists(cwd, targetPath, raw) {
 }
 
 function cmdHistoryDigest(cwd, raw) {
-  const phasesDir = path.join(getPlanningRoot(cwd), 'phases');
+  let phasesDir;
+  try {
+    const projectRoot = getProjectRoot(cwd);
+    phasesDir = path.join(cwd, projectRoot, 'phases');
+  } catch {
+    phasesDir = path.join(getPlanningRoot(cwd), 'phases');
+  }
   const digest = { phases: {}, decisions: [], tech_stack: new Set() };
 
   // Collect all phase directories: archived + current
@@ -214,44 +268,86 @@ function cmdResolveModel(cwd, agentType, raw) {
   output(result, raw, model);
 }
 
-function cmdCommit(cwd, message, files, raw, amend, push) {
-  if (!message && !amend) {
-    error('commit message required');
-  }
+/**
+ * Commit staged/unstaged files with an optional push orchestration.
+ *
+ * @param {string} cwd - Planning-root cwd. Config (commit_docs, sync_push,
+ *   current_project, worktree map) is always loaded from this directory.
+ * @param {string} message - Commit message (required unless amend=true).
+ * @param {string[]} files - Paths to stage. Resolved relative to repoCwd
+ *   (or cwd if repoCwd is not set). Defaults to ['.'].
+ * @param {boolean} raw - Emit raw (non-JSON) output.
+ * @param {boolean} amend - Run `git commit --amend --no-edit` instead.
+ * @param {boolean} push - Orchestrate push via pushAll() when sync_push=auto.
+ * @param {string} [repoCwd] - Optional absolute path where git operations run.
+ *   Config loading still uses cwd. Used by fast-path in milestone-context to
+ *   commit in a worktree while loading config from the planning root.
+ */
+// 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.
+  // Config is always loaded from cwd (planning root); only git exec targets
+  // the worktree filesystem.
+  const gitCwd = repoCwd || cwd;
+
   // Stage files
   const filesToStage = files && files.length > 0 ? files : ['.'];
   for (const file of filesToStage) {
-    execGit(cwd, ['add', file]);
+    execGit(gitCwd, ['add', file]);
   }
 
   // Commit
   const commitArgs = amend ? ['commit', '--amend', '--no-edit'] : ['commit', '-m', message];
-  const commitResult = execGit(cwd, commitArgs);
+  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(cwd, ['rev-parse', '--short', 'HEAD']);
+  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) {
@@ -273,7 +369,376 @@ function cmdCommit(cwd, message, files, raw, amend, push) {
     // '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,
+  };
+}
+
+/**
+ * CLI: `plan finalize <phase> <plan> [--plan-name <name>] [--push]`.
+ *
+ * Runs state update-progress + roadmap update-plan-progress + requirements
+ * mark-complete AND commits PLAN.md + SUMMARY.md + tracking files in a single
+ * atomic call. Requirement IDs are auto-extracted from PLAN.md frontmatter.
+ * Plan name resolution order: --plan-name flag > PLAN.md frontmatter plan_name
+ * > "execution" fallback.
+ *
+ * Does NOT call cmdCommit or the existing cmdStateUpdateProgress /
+ * cmdRoadmapUpdatePlanProgress / cmdRequirementsMarkComplete CLIs (all call
+ * output()/exit). Uses their *Internal helpers + execGit directly.
+ */
+function cmdPlanFinalize(cwd, phaseNum, planNum, options, raw) {
+  if (!phaseNum) error('phase number required for plan finalize');
+  if (!planNum) error('plan number required for plan finalize');
+
+  const { stateUpdateProgressInternal } = require('./state.cjs');
+  const { roadmapUpdatePlanProgressInternal } = require('./roadmap.cjs');
+  const { requirementsMarkCompleteInternal } = require('./milestone.cjs');
+
+  // Resolve phase dir via findPhaseInternal (returns phases/NN-name relative path)
+  const phaseInfo = findPhaseInternal(cwd, phaseNum);
+  if (!phaseInfo) error(`Phase ${phaseNum} not found`);
+  const phaseDir = path.join(cwd, phaseInfo.directory);
+
+  // Locate PLAN.md + SUMMARY.md within the phase dir using `${phaseNum}-${planNum}` prefix
+  // phaseInfo.phase_number is the canonical (padded) number e.g. "01".
+  const prefix = `${phaseInfo.phase_number || phaseNum}-${planNum}`;
+  let planPath = null;
+  let summaryPath = null;
+  try {
+    const entries = fs.readdirSync(phaseDir);
+    const planFile = entries.find(f =>
+      f.toLowerCase().startsWith(prefix.toLowerCase()) && /-PLAN\.md$/i.test(f)
+    );
+    const summaryFile = entries.find(f =>
+      f.toLowerCase().startsWith(prefix.toLowerCase()) && /-SUMMARY\.md$/i.test(f)
+    );
+    if (planFile) planPath = path.join(phaseDir, planFile);
+    if (summaryFile) summaryPath = path.join(phaseDir, summaryFile);
+  } catch { /* ignore */ }
+
+  // Extract plan_name + requirements from PLAN.md frontmatter
+  let planName = (options && options.planName) || null;
+  let reqIds = [];
+  if (planPath && fs.existsSync(planPath)) {
+    try {
+      const content = fs.readFileSync(planPath, 'utf-8');
+      const fm = extractFrontmatter(content);
+      if (fm) {
+        if (!planName && fm.plan_name) planName = String(fm.plan_name);
+        if (fm.requirements) {
+          reqIds = Array.isArray(fm.requirements)
+            ? fm.requirements.map(String).map(s => s.trim()).filter(Boolean)
+            : String(fm.requirements).replace(/[\[\]]/g, '').split(/[,\s]+/).map(s => s.trim()).filter(Boolean);
+        }
+      }
+    } catch { /* ignore */ }
+  }
+  if (!planName) planName = 'execution';
+
+  // Resolve tracking file paths (uses same project-root logic as phase finalize)
+  let projRoot;
+  try { projRoot = require('./core.cjs').getProjectRoot(cwd); } catch { projRoot = '.'; }
+  const roadmapPath = path.join(cwd, projRoot, 'ROADMAP.md');
+  const statePath = path.join(cwd, projRoot, 'STATE.md');
+  const requirementsPath = path.join(cwd, projRoot, 'REQUIREMENTS.md');
+
+  // Run internal updates (each returns { result, ... } without exit)
+  const stateUpdate = stateUpdateProgressInternal(cwd);
+  const roadmapUpdate = roadmapUpdatePlanProgressInternal(cwd, phaseNum);
+  const reqUpdate = reqIds.length > 0
+    ? requirementsMarkCompleteInternal(cwd, reqIds)
+    : { result: { updated: false, marked_complete: [], not_found: [], total: 0 }, reqPath: requirementsPath };
+
+  // Stage all files that exist on disk
+  const candidates = [planPath, summaryPath, statePath, roadmapPath, requirementsPath];
+  const filesToStage = candidates
+    .filter(p => p && fs.existsSync(p))
+    .map(p => path.relative(cwd, p));
+
+  const config = loadConfig(cwd);
+  const result = {
+    phase: phaseNum,
+    plan: planNum,
+    plan_name: planName,
+    state: stateUpdate.result,
+    roadmap: roadmapUpdate.result,
+    requirements: reqUpdate.result,
+    files_committed: [],
+  };
+
+  if (!config.commit_docs) {
+    result.committed = false;
+    result.commit_reason = 'skipped_commit_docs_false';
+    output(result, raw);
+    return;
+  }
+
+  const message = `docs(${phaseNum}-${planNum}): complete ${planName} plan`;
+  for (const f of filesToStage) {
+    execGit(cwd, ['add', f]);
+  }
+  const commitResult = execGit(cwd, ['commit', '-m', message]);
+  if (commitResult.exitCode !== 0) {
+    const nothing =
+      commitResult.stdout.includes('nothing to commit') ||
+      commitResult.stderr.includes('nothing to commit');
+    result.committed = false;
+    result.commit_reason = nothing ? 'nothing_to_commit' : 'commit_failed';
+    if (!nothing) result.commit_error = commitResult.stderr;
+    output(result, raw);
+    return;
+  }
+  const hashResult = execGit(cwd, ['rev-parse', '--short', 'HEAD']);
+  result.committed = true;
+  result.hash = hashResult.exitCode === 0 ? hashResult.stdout : null;
+  result.commit_reason = 'committed';
+  result.files_committed = filesToStage;
+
+  // Optional push (same semantics as cmdCommit / cmdPhaseFinalize)
+  if (options && options.push) {
+    const syncPush = config.sync_push || 'off';
+    if (syncPush === 'auto') {
+      try {
+        const { pushAll } = require('./sync.cjs');
+        const pushRes = pushAll(cwd, { force: true });
+        result.pushed = pushRes.ok;
+        result.push_result = pushRes;
+      } catch (err) {
+        result.pushed = false;
+        result.push_result = { ok: false, error: err.message };
+      }
+    } else if (syncPush === 'prompt') {
+      result.needs_push = true;
+    }
+  }
+
+  output(result, raw);
 }
 
 function cmdSummaryExtract(cwd, summaryPath, fields, raw) {
@@ -314,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
@@ -395,8 +862,17 @@ async function cmdWebsearch(query, options, raw) {
 }
 
 function cmdProgressRender(cwd, format, raw) {
-  const phasesDir = path.join(getPlanningRoot(cwd), 'phases');
-  const roadmapPath = path.join(getPlanningRoot(cwd), 'ROADMAP.md');
+  let phasesDir, roadmapPath;
+  try {
+    const projectRoot = getProjectRoot(cwd);
+    const projectAbs = path.join(cwd, projectRoot);
+    phasesDir = path.join(projectAbs, 'phases');
+    roadmapPath = path.join(projectAbs, 'ROADMAP.md');
+  } catch {
+    const planRoot = getPlanningRoot(cwd);
+    phasesDir = path.join(planRoot, 'phases');
+    roadmapPath = path.join(planRoot, 'ROADMAP.md');
+  }
   const milestone = getMilestoneInfo(cwd);
 
   const phases = [];
@@ -462,31 +938,88 @@ function cmdProgressRender(cwd, format, raw) {
   }
 }
 
-function cmdTodoComplete(cwd, filename, raw) {
-  if (!filename) {
-    error('filename required for todo complete');
+/**
+ * Set a todo's frontmatter status field (internal helper — throws on error).
+ *
+ * If the todo file has no YAML frontmatter, wraps existing content with a
+ * frontmatter block containing status (and completed_date if status is 'done').
+ *
+ * @param {string} cwd - Working directory
+ * @param {string} filename - Todo filename
+ * @param {string} status - Target status (must be in TODO_STATUSES)
+ * @returns {{ filename: string, previous_status: string, status: string, completed_date?: string }}
+ * @throws {Error} If status is invalid or todo not found
+ */
+function setTodoStatus(cwd, filename, status) {
+  if (!TODO_STATUSES.includes(status)) {
+    throw new Error(`Invalid status: ${status}. Allowed: ${TODO_STATUSES.join(', ')}`);
   }
 
-  const pendingDir = path.join(getPlanningRoot(cwd), 'todos', 'pending');
-  const completedDir = path.join(getPlanningRoot(cwd), 'todos', 'completed');
-  const sourcePath = path.join(pendingDir, filename);
+  // Search in both pending and completed directories
+  const planningRoot = getPlanningRoot(cwd);
+  let todoPath = null;
+  let previousStatus = 'pending';
 
-  if (!fs.existsSync(sourcePath)) {
-    error(`Todo not found: ${filename}`);
+  for (const dir of ['pending', 'completed']) {
+    const candidate = path.join(planningRoot, 'todos', dir, filename);
+    if (fs.existsSync(candidate)) {
+      todoPath = candidate;
+      previousStatus = dir === 'completed' ? 'done' : 'pending';
+      break;
+    }
+  }
+  // Also check flat todos/ directory (future layout)
+  if (!todoPath) {
+    const flat = path.join(planningRoot, 'todos', filename);
+    if (fs.existsSync(flat)) {
+      todoPath = flat;
+      const content = fs.readFileSync(flat, 'utf-8');
+      const fm = extractFrontmatter(content);
+      previousStatus = fm.status || 'pending';
+    }
   }
 
-  // Ensure completed directory exists
-  fs.mkdirSync(completedDir, { recursive: true });
+  if (!todoPath) {
+    throw new Error(`Todo not found: ${filename}`);
+  }
 
-  // Read, add completion timestamp, move
-  let content = fs.readFileSync(sourcePath, 'utf-8');
-  const today = new Date().toISOString().split('T')[0];
-  content = `completed: ${today}\n` + content;
+  let content = fs.readFileSync(todoPath, 'utf-8');
+  const fm = extractFrontmatter(content);
 
-  fs.writeFileSync(path.join(completedDir, filename), content, 'utf-8');
-  fs.unlinkSync(sourcePath);
+  // Build frontmatter fields
+  fm.status = status;
+  if (status === 'done') {
+    fm.completed_date = new Date().toISOString().split('T')[0];
+  }
+
+  // If file has frontmatter block, splice it; otherwise add one
+  if (content.match(/^---\n/)) {
+    content = spliceFrontmatter(content, fm);
+  } else {
+    // Strip bare "completed: YYYY-MM-DD" line if present (legacy format)
+    content = content.replace(/^completed:\s*\d{4}-\d{2}-\d{2}\n/, '');
+    const yamlStr = reconstructFrontmatter(fm);
+    content = `---\n${yamlStr}\n---\n${content}`;
+  }
+
+  fs.writeFileSync(todoPath, content, 'utf-8');
 
-  output({ completed: true, file: filename, date: today }, raw, 'completed');
+  const result = { filename, previous_status: previousStatus, status };
+  if (fm.completed_date) result.completed_date = fm.completed_date;
+  return result;
+}
+
+function cmdTodoComplete(cwd, filename, raw) {
+  if (!filename) {
+    error('filename required for todo complete');
+  }
+
+  // Use setTodoStatus to edit frontmatter status to 'done'
+  // setTodoStatus handles finding the file in flat or legacy directories
+  // and automatically sets completed_date when status is 'done'
+  const result = setTodoStatus(cwd, filename, 'done');
+
+  output({ completed: true, file: filename, date: result.completed_date || new Date().toISOString().split('T')[0] }, raw, 'completed');
 }
 
 function cmdScaffold(cwd, type, options, raw) {
@@ -567,7 +1100,49 @@ 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,
   cmdGenerateSlug,
   cmdCurrentTimestamp,
   cmdListTodos,
@@ -575,10 +1150,15 @@ module.exports = {
   cmdHistoryDigest,
   cmdResolveModel,
   cmdCommit,
+  commitInternal,
+  verifyPlanCommit,
+  computePhaseSweep,
+  cmdPlanFinalize,
   cmdSummaryExtract,
   cmdWebsearch,
   cmdProgressRender,
   cmdTodoComplete,
   cmdScaffold,
   cmdContextHelp,
+  cmdFinalCommitPrecondition,
 };