cleargate 0.8.2 → 0.10.0

package/dist/templates/cleargate-planning/.cleargate/scripts/close_sprint.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * close_sprint.mjs — Six-step sprint close pipeline
+ * close_sprint.mjs — Eight-step sprint close pipeline
  *
  * Usage: node close_sprint.mjs <sprint-id> [--assume-ack]
  *        node close_sprint.mjs <sprint-id> --report-body-stdin   (STORY-014-10)
@@ -9,20 +9,56 @@
  *   1. Load and validate state.json via validateState
  *   2. Refuse if any story state is not in TERMINAL_STATES (exit non-zero, list offenders)
  *   3. Invoke prefill_report.mjs on all agent reports
+ *   3.5 Build curated Reporter context bundle via prep_reporter_context.mjs (non-fatal)
  *   4. Orchestrator spawns Reporter separately (script validates preconditions only)
  *   5. On Reporter success + user ack (or --assume-ack flag), flip sprint_status -> "Completed"
  *   6. Invoke suggest_improvements.mjs unconditionally
+ *   7. Auto-push per-artifact status updates to MCP via cleargate sync work-items (non-fatal)
+ *   8. Verbose post-close handoff list (6-item next-steps block to stdout)
+ *
+ * Report filename: SPRINT-<#>_REPORT.md for new sprints (SPRINT-18+).
+ *   Backwards-compat: if SPRINT-<#>_REPORT.md is absent but REPORT.md exists (legacy
+ *   SPRINT-01..17), fall back to REPORT.md for read operations. New writes always
+ *   use SPRINT-<#>_REPORT.md when the sprint-id carries a numeric portion.
+ *   If the sprint-id has no numeric portion (e.g. SPRINT-TEST), plain REPORT.md is used.
  *
  * Stdin fallback (STORY-014-10): when `--report-body-stdin` is passed, the script
- * reads the full REPORT.md body from stdin and writes it atomically in lieu of
+ * reads the full SPRINT-<#>_REPORT.md body from stdin and writes it atomically in lieu of
  * waiting for a Reporter-produced file. Replaces the Step-4 gate; implies ack.
- * Refuses empty stdin or pre-existing REPORT.md.
+ * Refuses empty stdin or pre-existing report file.
  *
  * Does NOT archive the sprint file (pending-sync -> archive stays human per EPIC-013 §4.5 step 7).
  *
  * Reuse: TERMINAL_STATES, VALID_STATES from constants.mjs
  *        validateState from validate_state.mjs
  *        atomicWrite pattern from update_state.mjs
+ *
+ * Test seams (CR-022 M1):
+ *   CLEARGATE_SKIP_LIFECYCLE_CHECK=1  — skip Step 2.6 lifecycle reconciliation entirely
+ *                                       (test environments where the CLI binary is present
+ *                                       but real git history would produce drift false-positives).
+ *   CLEARGATE_SKIP_WORKTREE_CHECK=1   — skip Step 2.7 entirely (test environments that cannot
+ *                                       run git worktree list from a real git root).
+ *   CLEARGATE_FORCE_WORKTREE_PATHS=p1,p2 — comma-separated fake worktree paths injected into
+ *                                          Step 2.7 instead of running git worktree list.
+ *                                          Used to exercise the v2 block / v1 advisory paths
+ *                                          without a real .worktrees/STORY-* directory.
+ *   CLEARGATE_SKIP_MERGE_CHECK=1     — skip Step 2.8 entirely (test environments where git
+ *                                      refs are absent or merge state is irrelevant).
+ *   CLEARGATE_FORCE_MERGE_STATUS=merged|unmerged — inject merge status for Step 2.8 without
+ *                                                  running git merge-base. Used to exercise
+ *                                                  the v2 block / v1 advisory paths.
+ *   CLEARGATE_REPO_ROOT=<path>       — override REPO_ROOT for Step 2.8 git commands
+ *                                      (used in tests that need a controlled git repo).
+ *   CLEARGATE_SKIP_SPRINT_TRENDS=1   — skip Step 6.5 entirely (test environments).
+ *   CLEARGATE_SKIP_SKILL_CANDIDATES=1 — skip Step 6.6 entirely (test environments).
+ *   CLEARGATE_SKIP_FLASHCARD_CLEANUP=1 — skip Step 6.7 entirely (test environments).
+ *   CLEARGATE_SPRINT_RUNS_DIR=<path> — override .cleargate/sprint-runs/ root for
+ *                                      sibling-sprint counting in sprint_trends.mjs.
+ *   CLEARGATE_FLASHCARD_PATH=<path>  — override .cleargate/FLASHCARD.md path for
+ *                                      --flashcard-cleanup scan in suggest_improvements.mjs.
+ *   CLEARGATE_FLASHCARD_LOOKBACK=<N> — override 3-sprint default lookback for
+ *                                      --flashcard-cleanup scan.
  */
 
 import fs from 'node:fs';
@@ -31,6 +67,7 @@ import { fileURLToPath } from 'node:url';
 import { execSync } from 'node:child_process';
 import { TERMINAL_STATES } from './constants.mjs';
 import { validateState } from './validate_state.mjs';
+import { reportFilename } from './lib/report-filename.mjs';
 
 /**
  * Migrate a v1 state.json to v2 by injecting lane fields with defaults.
@@ -56,7 +93,9 @@ function migrateV1ToV2(state) {
 }
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const REPO_ROOT = process.env.CLEARGATE_REPO_ROOT
+  ? path.resolve(process.env.CLEARGATE_REPO_ROOT)
+  : path.resolve(__dirname, '..', '..');
 const SCRIPTS_DIR = __dirname;
 
 function usage() {
@@ -64,12 +103,13 @@ function usage() {
     'Usage: node close_sprint.mjs <sprint-id> [--assume-ack | --report-body-stdin]\n' +
     '\n' +
     'Options:\n' +
-    '  --assume-ack           Skip user acknowledgement prompt (for automated tests)\n' +
-    '  --report-body-stdin    Read REPORT.md body from stdin; implies ack (STORY-014-10)\n'
+    '  --assume-ack           Skip user acknowledgement prompt (automated tests ONLY — conversational orchestrators MUST NOT pass this)\n' +
+    '  --report-body-stdin    Read SPRINT-<#>_REPORT.md body from stdin; implies ack (STORY-014-10)\n'
   );
   process.exit(2);
 }
 
+
 /**
  * Atomic write using tmp+rename pattern (per M1 update_state.mjs convention).
  * @param {string} filePath
@@ -202,11 +242,11 @@ function main() {
       process.exit(1);
     }
 
-    // Read REPORT.md
-    const reportFile2 = path.join(sprintDir, 'REPORT.md');
+    // Read SPRINT-<#>_REPORT.md (with legacy REPORT.md fallback for pre-CR-021 sprints)
+    const reportFile2 = reportFilename(sprintDir, sprintId, { forRead: true });
     if (!fs.existsSync(reportFile2)) {
       process.stderr.write(
-        `close_sprint: v2.1 validation requires REPORT.md at ${reportFile2}\n` +
+        `close_sprint: v2.1 validation requires ${path.basename(reportFile2)} at ${reportFile2}\n` +
         '  Run the Reporter agent first, then re-run close_sprint.mjs.\n'
       );
       process.exit(1);
@@ -247,6 +287,217 @@ function main() {
     process.stdout.write('Step 2.5 passed: v2.1 validation — all required §3 metrics and §5 sections present.\n');
   }
 
+  // ── Step 2.6: Lifecycle Reconciliation (CR-017) ──────────────────────────
+  // Block close if any artifact referenced in this sprint's commits is still
+  // non-terminal in pending-sync (excluding carry_over: true).
+  // Invokes `cleargate sprint reconcile-lifecycle <sprint-id>` CLI wrapper.
+  // Fail-open if CLI binary is unavailable (non-blocking for test environments).
+  // Test seam: CLEARGATE_SKIP_LIFECYCLE_CHECK=1 skips this step entirely (non-fatal).
+  process.stdout.write('Step 2.6: running lifecycle reconciliation...\n');
+  if (process.env.CLEARGATE_SKIP_LIFECYCLE_CHECK === '1') {
+    process.stdout.write('Step 2.6 skipped: CLEARGATE_SKIP_LIFECYCLE_CHECK=1 set (test seam).\n');
+  } else {
+    try {
+      // Resolve CLI binary: prefer local dist/
+      const cliBin = path.join(REPO_ROOT, 'cleargate-cli', 'dist', 'cli.js');
+
+      if (fs.existsSync(cliBin)) {
+        // Read sprint start_date from frontmatter for the --since arg
+        let sinceArg = '';
+        try {
+          const pendingDir = path.join(REPO_ROOT, '.cleargate', 'delivery', 'pending-sync');
+          if (fs.existsSync(pendingDir)) {
+            const entries = fs.readdirSync(pendingDir);
+            const sprintFile = entries.find(
+              (e) => (e.startsWith(`${sprintId}_`) || e === `${sprintId}.md`) && e.endsWith('.md')
+            );
+            if (sprintFile) {
+              const raw = fs.readFileSync(path.join(pendingDir, sprintFile), 'utf8');
+              const startDateMatch = /^start_date:\s*(.+)$/m.exec(raw);
+              if (startDateMatch && startDateMatch[1]) {
+                sinceArg = `--since ${startDateMatch[1].trim()}`;
+              }
+            }
+          }
+        } catch { /* ignore */ }
+
+        const reconcileArgs = [
+          'node', JSON.stringify(cliBin), 'sprint', 'reconcile-lifecycle', JSON.stringify(sprintId),
+        ];
+        if (sinceArg) reconcileArgs.push(sinceArg);
+        const reconcileCmd = reconcileArgs.join(' ');
+
+        try {
+          execSync(reconcileCmd, { stdio: 'inherit', env: process.env });
+          process.stdout.write('Step 2.6 passed: lifecycle reconciliation clean.\n');
+        } catch (_reconcileErr) {
+          // Exit code 1 from reconcile-lifecycle means drift found
+          process.stderr.write(
+            'close_sprint: Step 2.6 FAILED — lifecycle drift blocks sprint close.\n' +
+            '  Remediate the listed artifacts and re-run close_sprint.mjs.\n' +
+            '  To carry over an artifact: set carry_over: true in its frontmatter.\n'
+          );
+          process.exit(1);
+        }
+      } else {
+        process.stdout.write('Step 2.6 skipped: CLI binary not found at cleargate-cli/dist/cli.js (non-fatal).\n');
+      }
+    } catch (step26Err) {
+      // Unexpected error — fail-open (log but do not block)
+      process.stderr.write(`Step 2.6 warning: lifecycle reconciliation unavailable: ${step26Err.message}\n`);
+    }
+  }
+
+  // ── Step 2.7: Worktree-Closed Check (CR-022 M1) ──────────────────────────
+  // Block close if any .worktrees/STORY-* path is present.
+  // v2 enforcing (exit 1); v1 advisory (warn + continue).
+  // Skip if git worktree list is unavailable (non-fatal — tests run against tmpdirs).
+  // Test seams: CLEARGATE_SKIP_WORKTREE_CHECK=1 bypasses entirely;
+  //             CLEARGATE_FORCE_WORKTREE_PATHS=p1,p2 injects fake paths (no git call).
+  process.stdout.write('Step 2.7: checking for leftover worktrees...\n');
+  {
+    if (process.env.CLEARGATE_SKIP_WORKTREE_CHECK === '1') {
+      process.stdout.write('Step 2.7 skipped: CLEARGATE_SKIP_WORKTREE_CHECK=1 set (test seam).\n');
+    } else {
+      let leftoverWorktrees = [];
+      let worktreeListAvailable = true;
+
+      if (process.env.CLEARGATE_FORCE_WORKTREE_PATHS) {
+        // Test seam: inject fake worktree paths without running git
+        leftoverWorktrees = process.env.CLEARGATE_FORCE_WORKTREE_PATHS
+          .split(',')
+          .map((p) => p.trim())
+          .filter(Boolean);
+      } else {
+        try {
+          const output = execSync('git worktree list --porcelain', {
+            cwd: REPO_ROOT,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+          });
+          for (const line of output.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed.startsWith('worktree ')) continue;
+            const wtPath = trimmed.slice('worktree '.length);
+            if (/[/\\]\.worktrees[/\\]STORY-/.test(wtPath)) {
+              const m = /(\.(worktrees)[/\\]STORY-.+)$/.exec(wtPath);
+              leftoverWorktrees.push(m ? m[1] : wtPath);
+            }
+          }
+        } catch {
+          worktreeListAvailable = false;
+        }
+      }
+
+      // Step 2.7 enforcing mode: v2 execution_mode (not just schema_version, since
+      // migration bumps schema_version to 2 for all sprints before isV2 is evaluated).
+      // Using execution_mode preserves v1 advisory behaviour for sprints initialised
+      // with execution_mode: "v1" even after their schema is migrated.
+      const isEnforcingV2 = isV2 && state.execution_mode === 'v2';
+
+      if (!worktreeListAvailable) {
+        process.stdout.write('Step 2.7 skipped: git worktree list unavailable (non-fatal).\n');
+      } else if (leftoverWorktrees.length === 0) {
+        process.stdout.write('Step 2.7 passed: no leftover worktrees.\n');
+      } else if (isEnforcingV2) {
+        // v2 enforcing — block close
+        process.stderr.write(
+          `close_sprint: Step 2.7 failed: leftover worktree at ${leftoverWorktrees[0]}\n` +
+          `  ${leftoverWorktrees.length === 1 ? '' : `(plus ${leftoverWorktrees.length - 1} more)\n  `}` +
+          `Run \`git worktree remove ${leftoverWorktrees[0]}\` if abandoned, or merge the work in progress.\n` +
+          `  All worktrees must be closed before sprint close.\n`
+        );
+        process.exit(1);
+      } else {
+        // v1 advisory — warn + continue
+        process.stderr.write(
+          `Step 2.7 warning: leftover worktree at ${leftoverWorktrees[0]} (advisory in v1).\n`
+        );
+      }
+    }
+  }
+
+  // ── Step 2.8: Sprint branch merged to main (verify-only, NO auto-merge) ──────
+  // CR-022 §1: verify-only — script asserts merge ancestry, does NOT run the merge.
+  // On miss: list unmerged commits + exit 1 (v2 enforcing); warn + continue (v1 advisory).
+  // Skip when sprintId has no numeric portion (e.g. SPRINT-TEST fixture).
+  // Test seams: CLEARGATE_SKIP_MERGE_CHECK=1 bypasses entirely;
+  //             CLEARGATE_FORCE_MERGE_STATUS=merged|unmerged injects status without git call.
+  {
+    if (process.env.CLEARGATE_SKIP_MERGE_CHECK === '1') {
+      process.stdout.write('Step 2.8 skipped: CLEARGATE_SKIP_MERGE_CHECK=1 set (test seam).\n');
+    } else {
+      const sprintNumMatch = /^SPRINT-(\d{2,3})$/.exec(sprintId);
+      if (!sprintNumMatch) {
+        process.stdout.write(`Step 2.8 skipped: sprint-id "${sprintId}" has no numeric portion.\n`);
+      } else {
+        const sprintBranch = `refs/heads/sprint/S-${sprintNumMatch[1]}`;
+        const mainBranch = 'refs/heads/main';
+        process.stdout.write(`Step 2.8: verifying ${sprintBranch} merged to ${mainBranch}...\n`);
+
+        const isEnforcingV2 = isV2 && state.execution_mode === 'v2';
+
+        const forcedStatus = process.env.CLEARGATE_FORCE_MERGE_STATUS;
+        let isMerged = false;
+        let mergeCheckAvailable = true;
+
+        if (forcedStatus === 'merged') {
+          isMerged = true;
+        } else if (forcedStatus === 'unmerged') {
+          isMerged = false;
+        } else {
+          try {
+            execSync(
+              `git merge-base --is-ancestor ${sprintBranch} ${mainBranch}`,
+              { stdio: 'pipe', cwd: REPO_ROOT, env: process.env }
+            );
+            isMerged = true;
+          } catch (mergeErr) {
+            const exitStatus = /** @type {any} */ (mergeErr).status;
+            if (exitStatus === 1) {
+              isMerged = false;
+            } else {
+              // exit 128: refs missing or other git failure — fail-open with warning
+              mergeCheckAvailable = false;
+              process.stderr.write(
+                `Step 2.8 warning: git merge-base check unavailable (${/** @type {Error} */ (mergeErr).message}). ` +
+                `Skipping merge verification.\n`
+              );
+            }
+          }
+        }
+
+        if (!mergeCheckAvailable) {
+          // fail-open: refs missing or git unavailable — continue to Step 3
+        } else if (isMerged) {
+          process.stdout.write(`Step 2.8 passed: ${sprintBranch} is merged to ${mainBranch}.\n`);
+        } else if (isEnforcingV2) {
+          // v2 enforcing — block close
+          let unmergedLog = '';
+          if (!forcedStatus) {
+            try {
+              unmergedLog = execSync(
+                `git log ${mainBranch}..${sprintBranch} --oneline`,
+                { encoding: 'utf8', cwd: REPO_ROOT, env: process.env }
+              );
+            } catch { /* unmerged-log fetch failed — proceed without */ }
+          }
+          process.stderr.write(
+            `Step 2.8 failed: sprint/S-${sprintNumMatch[1]} not merged to main.\n` +
+            (unmergedLog ? `  Unmerged commits:\n${unmergedLog}` : '') +
+            `  Resolve: merge sprint/S-${sprintNumMatch[1]} → main, then re-run close_sprint.mjs.\n`
+          );
+          process.exit(1);
+        } else {
+          // v1 advisory — warn + continue
+          process.stderr.write(
+            `Step 2.8 warning: sprint/S-${sprintNumMatch[1]} not merged to main (advisory in v1).\n`
+          );
+        }
+      }
+    }
+  }
+
   // ── Step 3: Invoke prefill_report.mjs ─────────────────────────────────────
   process.stdout.write('Step 3: running prefill_report.mjs...\n');
   try {
@@ -259,24 +510,37 @@ function main() {
     process.exit(1);
   }
 
+  // ── Step 3.5: Build curated Reporter context bundle ───────────────────────
+  process.stdout.write('Step 3.5: building Reporter context bundle...\n');
+  try {
+    invokeScript('prep_reporter_context.mjs', [sprintId], {
+      CLEARGATE_STATE_FILE: stateFile,
+      CLEARGATE_SPRINT_DIR: sprintDir,
+    });
+    process.stdout.write(`Step 3.5 passed: ${sprintDir}/.reporter-context.md ready.\n`);
+  } catch (err) {
+    // Non-fatal — Reporter falls back to source files
+    process.stderr.write(`Step 3.5 warning: prep_reporter_context.mjs failed: ${/** @type {Error} */ (err).message}\n`);
+    process.stderr.write('Reporter will fall back to broad-fetch context loading.\n');
+  }
+
   // ── Step 4: Orchestrator spawns Reporter separately ───────────────────────
   // This script only validates preconditions; it does NOT fork the Reporter agent.
+  const reportFile = reportFilename(sprintDir, sprintId);
+  const reportBasename = path.basename(reportFile);
   process.stdout.write(
     'Step 4: preconditions satisfied — orchestrator should now spawn the Reporter agent.\n' +
-    '        The Reporter writes REPORT.md using the sprint_report.md template.\n' +
-    `        Expected output: ${path.join(sprintDir, 'REPORT.md')}\n`
+    `        The Reporter writes ${reportBasename} using the sprint_report.md template.\n` +
+    `        Expected output: ${reportFile}\n`
   );
 
-  // Check if REPORT.md already exists (e.g., --assume-ack path in tests)
-  const reportFile = path.join(sprintDir, 'REPORT.md');
-
   // ── Step 4.5 (STORY-014-10): --report-body-stdin fallback ────────────────
   // Orchestrator pipes the Reporter's markdown body here when the Reporter's
-  // Write tool is blocked. Refuses empty stdin + pre-existing REPORT.md.
+  // Write tool is blocked. Refuses empty stdin + pre-existing report file.
   if (reportBodyStdin) {
     if (fs.existsSync(reportFile)) {
       process.stderr.write(
-        `Error: REPORT.md already exists at ${reportFile}\n` +
+        `Error: ${reportBasename} already exists at ${reportFile}\n` +
         'Delete it or skip --report-body-stdin mode to use the primary Reporter-write path.\n'
       );
       process.exit(1);
@@ -285,7 +549,7 @@ function main() {
     try {
       body = fs.readFileSync(0, 'utf8');
     } catch (err) {
-      process.stderr.write(`Error: failed to read stdin: ${err.message}\n`);
+      process.stderr.write(`Error: failed to read stdin: ${/** @type {Error} */ (err).message}\n`);
       process.exit(1);
     }
     if (!body || body.trim().length === 0) {
@@ -294,20 +558,22 @@ function main() {
     }
     atomicWriteString(reportFile, body);
     process.stdout.write(
-      `Step 4.5 (stdin mode): REPORT.md written (${body.length} bytes) at ${reportFile}\n`
+      `Step 4.5 (stdin mode): ${reportBasename} written (${body.length} bytes) at ${reportFile}\n`
     );
-    // Fall through to Step 5 + 6 unconditionally — stdin mode implies ack.
+    // Fall through to Step 5 + 6 + 7 unconditionally — stdin mode implies ack.
   } else if (!assumeAck) {
-    if (!fs.existsSync(reportFile)) {
+    // Apply read-fallback for legacy sprints (e.g. SPRINT-15 with plain REPORT.md)
+    const reportFileForCheck = reportFilename(sprintDir, sprintId, { forRead: true });
+    if (!fs.existsSync(reportFileForCheck)) {
       process.stdout.write(
-        '\nWaiting for Reporter to produce REPORT.md...\n' +
+        `\nWaiting for Reporter to produce ${reportBasename}...\n` +
         'After Reporter succeeds, re-run with --assume-ack to complete the close.\n'
       );
       process.exit(0);
     }
-    // In non-assume-ack mode with existing REPORT.md, prompt user
+    // In non-assume-ack mode with existing report, prompt user
     process.stdout.write(
-      `\nREPORT.md found at ${reportFile}\n` +
+      `\n${reportBasename} found at ${reportFileForCheck}\n` +
       'Review the report, then confirm close by re-running with --assume-ack\n'
     );
     process.exit(0);
@@ -331,13 +597,107 @@ function main() {
     });
   } catch (err) {
     // suggest_improvements failure is non-fatal — log but do not abort
-    process.stderr.write(`Warning: suggest_improvements.mjs failed: ${err.message}\n`);
+    process.stderr.write(`Warning: suggest_improvements.mjs failed: ${/** @type {Error} */ (err).message}\n`);
     process.stderr.write('Sprint is still marked Completed; improvement suggestions may be incomplete.\n');
   }
 
-  process.stdout.write(`\nSprint ${sprintId} close pipeline complete.\n`);
-  process.stdout.write(`  state.json: sprint_status = Completed\n`);
-  process.stdout.write(`  improvement-suggestions.md: ${path.join(sprintDir, 'improvement-suggestions.md')}\n`);
+  // ── Step 6.5: Run sprint_trends.mjs (stub — full impl deferred to CR-027) ──
+  if (process.env.CLEARGATE_SKIP_SPRINT_TRENDS !== '1') {
+    process.stdout.write('Step 6.5: running sprint_trends.mjs (stub)...\n');
+    try {
+      invokeScript('sprint_trends.mjs', [sprintId], {
+        CLEARGATE_STATE_FILE: stateFile,
+        CLEARGATE_SPRINT_DIR: sprintDir,
+      });
+    } catch (err) {
+      // Non-fatal — sprint stays Completed; trends are advisory only.
+      process.stderr.write(`Step 6.5 warning: sprint_trends.mjs failed: ${/** @type {Error} */ (err).message}\n`);
+    }
+  }
+
+  // ── Step 6.6: Skill-candidate detection (folds into suggest_improvements.mjs) ──
+  if (process.env.CLEARGATE_SKIP_SKILL_CANDIDATES !== '1') {
+    process.stdout.write('Step 6.6: scanning for skill candidates...\n');
+    try {
+      invokeScript('suggest_improvements.mjs', [sprintId, '--skill-candidates'], {
+        CLEARGATE_STATE_FILE: stateFile,
+        CLEARGATE_SPRINT_DIR: sprintDir,
+      });
+    } catch (err) {
+      process.stderr.write(`Step 6.6 warning: skill-candidate scan failed: ${/** @type {Error} */ (err).message}\n`);
+    }
+  }
+
+  // ── Step 6.7: FLASHCARD cleanup pass (folds into suggest_improvements.mjs) ──
+  if (process.env.CLEARGATE_SKIP_FLASHCARD_CLEANUP !== '1') {
+    process.stdout.write('Step 6.7: scanning FLASHCARD.md for cleanup candidates...\n');
+    try {
+      invokeScript('suggest_improvements.mjs', [sprintId, '--flashcard-cleanup'], {
+        CLEARGATE_STATE_FILE: stateFile,
+        CLEARGATE_SPRINT_DIR: sprintDir,
+      });
+    } catch (err) {
+      process.stderr.write(`Step 6.7 warning: FLASHCARD cleanup scan failed: ${/** @type {Error} */ (err).message}\n`);
+    }
+  }
+
+  // ── Step 7: Auto-push per-artifact status updates to MCP ─────────────────
+  // Runs after Gate 4 ack succeeds. Non-fatal: sprint stays Completed on failure.
+  process.stdout.write('Step 7: pushing per-artifact status updates to MCP...\n');
+  try {
+    const cliBin = path.join(REPO_ROOT, 'cleargate-cli', 'dist', 'cli.js');
+    if (fs.existsSync(cliBin)) {
+      // cleargate sync work-items takes ZERO positional args (verified cli.ts:592-598).
+      // CR-021 §3.2.3 spec shows a sprint-id arg — that is spec drift; drop it.
+      execSync(`node ${JSON.stringify(cliBin)} sync work-items`, {
+        stdio: 'inherit',
+        env: process.env,
+        timeout: 30000,
+      });
+      process.stdout.write('Step 7 passed: work-item statuses synced.\n');
+    } else {
+      process.stdout.write('Step 7 skipped: CLI binary not found (non-fatal).\n');
+    }
+  } catch (err) {
+    // Non-fatal — sprint stays Completed; sync can be retried manually
+    process.stderr.write(`Step 7 warning: sync work-items failed: ${/** @type {Error} */ (err).message}\n`);
+    process.stderr.write('Run `cleargate sync work-items` manually to retry.\n');
+  }
+
+  // ── Step 8: Verbose post-close handoff list ───────────────────────────────
+  // Prints 6 explicit next-step items to stdout (CR-022 §3 M4).
+  {
+    const sprintNumMatch = /^SPRINT-(\d{2,3})$/.exec(sprintId);
+    const nextSprintNum = sprintNumMatch
+      ? String(parseInt(sprintNumMatch[1], 10) + 1).padStart(sprintNumMatch[1].length, '0')
+      : null;
+    const nextSprintId = nextSprintNum ? `SPRINT-${nextSprintNum}` : '<next-sprint-id>';
+    const reportBasename = path.basename(reportFile);
+    const suggestionsPath = path.join(sprintDir, 'improvement-suggestions.md');
+
+    process.stdout.write(`\n${sprintId} closed. Next steps:\n`);
+    process.stdout.write(`  1. Review ${reportBasename}\n`);
+    process.stdout.write(
+      `  2. Review improvement-suggestions.md (sections: Suggestions / Skill Candidates / FLASHCARD Cleanup)\n`,
+    );
+    process.stdout.write(
+      `  3. Approve or reject Skill Candidates → run /improve or cleargate skill create <name>\n`,
+    );
+    process.stdout.write(
+      `  4. Approve or reject FLASHCARD cleanup entries → run /improve or cleargate flashcard prune\n`,
+    );
+    process.stdout.write(
+      `  5. Push approved status changes to MCP if Step 7 warned (\`cleargate sync work-items\`)\n`,
+    );
+    process.stdout.write(
+      `  6. Initialize next sprint: \`cleargate sprint init ${nextSprintId} --stories <ids>\`\n`,
+    );
+
+    // Surface artifact paths for convenience
+    process.stdout.write(`\nArtifacts:\n`);
+    process.stdout.write(`  report:               ${reportFile}\n`);
+    process.stdout.write(`  improvement-suggestions: ${suggestionsPath}\n`);
+  }
 }
 
 main();