cleargate 0.8.2 → 0.11.0

package/templates/cleargate-planning/.cleargate/scripts/dedupe_frontmatter.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+/**
+ * dedupe_frontmatter.mjs — BUG-025
+ *
+ * One-shot corpus dedupe pass: scan every .md file under
+ * .cleargate/delivery/pending-sync/ and .cleargate/delivery/archive/.
+ * For any file whose YAML frontmatter contains duplicate top-level keys,
+ * keep the LAST occurrence of each key (closest to the body — this is what
+ * the stamp hook writes most recently) and rewrite the file.
+ *
+ * Idempotent: re-running produces zero diff when no duplicates remain.
+ *
+ * Usage:
+ *   node .cleargate/scripts/dedupe_frontmatter.mjs [--dry-run] [<dir>]
+ *
+ *   --dry-run   Print which files would be rewritten without writing.
+ *   <dir>       Walk only this directory instead of the canonical corpus dirs.
+ *               Used by integration tests targeting a tmpdir.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as url from 'node:url';
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+const args = process.argv.slice(2);
+const DRY_RUN = args.includes('--dry-run');
+const DIR_ARG = args.find((a) => !a.startsWith('--'));
+
+const PENDING_SYNC = path.join(REPO_ROOT, '.cleargate', 'delivery', 'pending-sync');
+const ARCHIVE = path.join(REPO_ROOT, '.cleargate', 'delivery', 'archive');
+
+/**
+ * Collect all .md files in a flat directory (non-recursive — delivery dirs are flat).
+ */
+function collectMd(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && e.name.endsWith('.md'))
+    .map((e) => path.join(dir, e.name));
+}
+
+/**
+ * Parse a raw markdown string into:
+ *   fmLines  — the lines between the opening and closing `---` delimiters
+ *   closeIdx — index of the closing `---` line (in the full `lines` array)
+ *   lines    — all lines of the file
+ *
+ * Returns null if the file has no valid frontmatter.
+ */
+function parseFmLines(raw) {
+  const lines = raw.split('\n');
+  if (lines[0] !== '---') return null;
+  let closeIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === '---') {
+      closeIdx = i;
+      break;
+    }
+  }
+  if (closeIdx === -1) return null;
+  return { lines, closeIdx, fmLines: lines.slice(1, closeIdx) };
+}
+
+/**
+ * Given the frontmatter lines, detect duplicate top-level keys.
+ * Returns a Map from key → array of line-indices (within fmLines) where it appears.
+ * Only entries with ≥2 occurrences indicate duplicates.
+ *
+ * A "top-level key" is a line that starts with a non-space character followed by
+ * `:<space>` or `:<end-of-line>`. Multi-line values (YAML scalars, blocks) that
+ * contain `:` on continuation lines are NOT top-level keys (they start with space/tab).
+ */
+function findDuplicateKeys(fmLines) {
+  /** @type {Map<string, number[]>} */
+  const keyMap = new Map();
+  for (let i = 0; i < fmLines.length; i++) {
+    const line = fmLines[i];
+    // Top-level key: starts at column 0, has `:` after a word character sequence
+    const m = line.match(/^([A-Za-z_][A-Za-z0-9_]*):/);
+    if (m) {
+      const key = m[1];
+      if (!keyMap.has(key)) {
+        keyMap.set(key, []);
+      }
+      keyMap.get(key).push(i);
+    }
+  }
+  // Return only keys with duplicates
+  /** @type {Map<string, number[]>} */
+  const dupes = new Map();
+  for (const [k, indices] of keyMap) {
+    if (indices.length > 1) {
+      dupes.set(k, indices);
+    }
+  }
+  return dupes;
+}
+
+/**
+ * Deduplicate frontmatter lines: for each duplicate key, keep the LAST occurrence
+ * and discard all earlier ones (including their potential multi-line values).
+ *
+ * Multi-line value detection: lines that follow a key line and start with
+ * whitespace (` ` or `\t`) belong to the preceding key's value.
+ *
+ * Returns the deduplicated fmLines array (may be the same reference if no changes).
+ */
+function dedupeLines(fmLines, dupes) {
+  if (dupes.size === 0) return fmLines;
+
+  // Build a set of fmLine indices to DROP (all but the last occurrence of each dup key,
+  // including their continuation lines).
+  /** @type {Set<number>} */
+  const dropSet = new Set();
+
+  for (const [, indices] of dupes) {
+    // Keep last occurrence; drop all earlier ones (+ their continuations)
+    const toRemove = indices.slice(0, -1); // all but last
+    for (const startIdx of toRemove) {
+      dropSet.add(startIdx);
+      // Mark continuation lines (indent-starting lines following a key line)
+      let j = startIdx + 1;
+      while (j < fmLines.length && /^[ \t]/.test(fmLines[j])) {
+        dropSet.add(j);
+        j++;
+      }
+    }
+  }
+
+  return fmLines.filter((_, i) => !dropSet.has(i));
+}
+
+/**
+ * Atomic write: write to a .tmp file then rename over the target.
+ */
+function writeAtomic(filePath, content) {
+  const tmpPath = `${filePath}.tmp.${Date.now()}`;
+  fs.writeFileSync(tmpPath, content, 'utf8');
+  fs.renameSync(tmpPath, filePath);
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+const files = DIR_ARG
+  ? collectMd(path.resolve(DIR_ARG))
+  : [...collectMd(PENDING_SYNC), ...collectMd(ARCHIVE)];
+
+let rewritten = 0;
+let skipped = 0;
+let errors = 0;
+
+for (const filePath of files) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (e) {
+    console.error(`error reading ${filePath}: ${e.message}`);
+    errors++;
+    continue;
+  }
+
+  const parsed = parseFmLines(raw);
+  if (!parsed) {
+    skipped++;
+    continue;
+  }
+
+  const { lines, closeIdx, fmLines } = parsed;
+  const dupes = findDuplicateKeys(fmLines);
+
+  if (dupes.size === 0) {
+    skipped++;
+    continue;
+  }
+
+  const relPath = path.relative(REPO_ROOT, filePath);
+  const dupeSummary = Array.from(dupes.keys()).join(', ');
+
+  if (DRY_RUN) {
+    console.log(`would-rewrite: ${relPath} (duplicate keys: ${dupeSummary})`);
+    rewritten++;
+    continue;
+  }
+
+  // Build the new file content: deduplicated frontmatter + rest unchanged
+  const cleanedFmLines = dedupeLines(fmLines, dupes);
+  const newLines = [
+    lines[0],            // opening ---
+    ...cleanedFmLines,
+    lines[closeIdx],     // closing ---
+    ...lines.slice(closeIdx + 1),
+  ];
+  const newContent = newLines.join('\n');
+
+  // Verify the result is actually different (guard against no-op edge cases)
+  if (newContent === raw) {
+    skipped++;
+    continue;
+  }
+
+  writeAtomic(filePath, newContent);
+  console.log(`rewritten: ${relPath} (removed duplicate keys: ${dupeSummary})`);
+  rewritten++;
+}
+
+console.log(
+  `\nDedupe complete: ${rewritten} ${DRY_RUN ? 'would-rewrite' : 'rewritten'}, ${skipped} skipped, ${errors} errors.`,
+);
+if (errors > 0) {
+  process.exit(1);
+}

package/templates/cleargate-planning/.cleargate/scripts/gate-checks.json

@@ -1,13 +1,13 @@
 {
   "schema_version": 1,
   "qa": {
-    "typecheck": "npm run typecheck",
+    "typecheck": "cd cleargate-cli && npm run typecheck",
     "debug_patterns": ["console.log", "console.debug", "debugger"],
     "todo_patterns": ["TODO", "FIXME", "XXX"],
-    "test": "npm test"
+    "test": "cd cleargate-cli && npm test"
   },
   "arch": {
-    "typecheck": "npm run typecheck",
+    "typecheck": "cd cleargate-cli && npm run typecheck",
     "new_deps_check": true,
     "stray_env_files": [".env", ".env.local", ".env.production"],
     "file_count_report": true

package/templates/cleargate-planning/.cleargate/scripts/init_sprint.mjs

@@ -2,7 +2,12 @@
 /**
  * init_sprint.mjs — Initialize a sprint state.json
  *
- * Usage: node init_sprint.mjs <sprint-id> --stories ID1,ID2,... [--force]
+ * Usage: node init_sprint.mjs <sprint-id> --stories ID1,ID2,... [--force] [--preserve-bounces]
+ *
+ * --preserve-bounces requires --force; reads existing state.json and carries
+ * forward qa_bounces / arch_bounces / state / lane / worktree per matching
+ * story-id. Items not in the new --stories list are dropped. Useful when
+ * mid-sprint dogfood / rerun must not lose kickback history.
  *
  * Creates .cleargate/sprint-runs/<sprint-id>/state.json with initial state
  * "Ready to Bounce" for each story. Refuses if state.json already exists
@@ -117,6 +122,7 @@ function main() {
   }
 
   const force = args.includes('--force');
+  const preserveBounces = args.includes('--preserve-bounces');
 
   const sprintDir = path.join(REPO_ROOT, '.cleargate', 'sprint-runs', sprintId);
   const stateFile = path.join(sprintDir, 'state.json');
@@ -128,6 +134,20 @@ function main() {
     process.exit(1);
   }
 
+  // --- CR-049-followup: Preserve bounce counters when --force re-inits an in-flight sprint ---
+  // Default --force overwrites everything (initial design). With --preserve-bounces,
+  // qa_bounces / arch_bounces / state are read from the existing state.json and merged
+  // back per-story. Only Ready-to-Bounce default fields get reset.
+  let preserved = {};
+  if (force && preserveBounces && fs.existsSync(stateFile)) {
+    try {
+      const existing = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+      preserved = existing.stories || {};
+    } catch (err) {
+      process.stderr.write(`WARN: --preserve-bounces could not read existing state.json: ${err.message}\n`);
+    }
+  }
+
   // --- Read execution_mode from sprint frontmatter ---
   const sprintFilePath = findSprintFile(REPO_ROOT, sprintId);
   const executionMode = sprintFilePath ? readExecutionMode(sprintFilePath) : 'v1';
@@ -159,17 +179,18 @@ function main() {
   const now = new Date().toISOString();
   const stories = {};
   for (const id of storyIds) {
+    const carry = preserved[id] || {};
     stories[id] = {
-      state: 'Ready to Bounce',
-      qa_bounces: 0,
-      arch_bounces: 0,
-      worktree: null,
+      state: carry.state ?? 'Ready to Bounce',
+      qa_bounces: carry.qa_bounces ?? 0,
+      arch_bounces: carry.arch_bounces ?? 0,
+      worktree: carry.worktree ?? null,
       updated_at: now,
-      notes: '',
-      lane: 'standard',
-      lane_assigned_by: 'migration-default',
-      lane_demoted_at: null,
-      lane_demotion_reason: null,
+      notes: carry.notes ?? '',
+      lane: carry.lane ?? 'standard',
+      lane_assigned_by: carry.lane_assigned_by ?? 'migration-default',
+      lane_demoted_at: carry.lane_demoted_at ?? null,
+      lane_demotion_reason: carry.lane_demotion_reason ?? null,
     };
   }
 
@@ -189,6 +210,61 @@ function main() {
   fs.writeFileSync(tmpFile, JSON.stringify(state, null, 2) + '\n', 'utf8');
   fs.renameSync(tmpFile, stateFile);
 
+  // --- CR-045: Write sprint-context.md from template ---
+  // Reads .cleargate/templates/sprint_context.md, substitutes frontmatter fields,
+  // optionally splices the sprint goal from the sprint plan §0, and writes atomically.
+  // Skip if file already exists and --force was not passed (idempotency-safe re-init).
+  const ctxTemplate = path.join(REPO_ROOT, '.cleargate', 'templates', 'sprint_context.md');
+  const ctxOut = path.join(sprintDir, 'sprint-context.md');
+
+  if (!fs.existsSync(ctxOut) || force) {
+    let ctxContent;
+    try {
+      ctxContent = fs.readFileSync(ctxTemplate, 'utf8');
+    } catch {
+      // Template absent — log warning and continue (non-fatal)
+      process.stderr.write(
+        `WARN: sprint-context.md template not found at ${ctxTemplate}; skipping sprint-context.md write.\n`
+      );
+      ctxContent = null;
+    }
+
+    if (ctxContent !== null) {
+      // Substitute frontmatter placeholders
+      ctxContent = ctxContent.replace(/sprint_id:\s*["']?S-NN["']?/, `sprint_id: "${sprintId}"`);
+      ctxContent = ctxContent.replace(/created_at:\s*["']?YYYY-MM-DDTHH:MM:SSZ["']?/, `created_at: "${now}"`);
+      ctxContent = ctxContent.replace(/last_updated:\s*["']?YYYY-MM-DDTHH:MM:SSZ["']?/, `last_updated: "${now}"`);
+
+      // Optionally extract sprint goal from sprint plan §0.
+      // Regex matches `- **Sprint Goal:** <text>` within first 200 lines (after H1).
+      // Falls back to placeholder if absent — non-fatal.
+      if (sprintFilePath) {
+        try {
+          const planContent = fs.readFileSync(sprintFilePath, 'utf8');
+          const planLines = planContent.split('\n').slice(0, 200);
+          const goalLine = planLines.find((l) => /^- \*\*Sprint Goal:\*\* (.+)$/.test(l.trim()));
+          if (goalLine) {
+            const goalMatch = goalLine.trim().match(/^- \*\*Sprint Goal:\*\* (.+)$/);
+            if (goalMatch) {
+              const goalText = goalMatch[1].trim();
+              ctxContent = ctxContent.replace(
+                '_(populated by orchestrator from sprint plan §0 at kickoff)_',
+                goalText
+              );
+            }
+          }
+        } catch {
+          // Goal extraction failed — leave placeholder; non-fatal
+        }
+      }
+
+      // Write atomically via tmpFile + renameSync (mirrors state.json pattern)
+      const ctxTmp = `${ctxOut}.tmp.${process.pid}`;
+      fs.writeFileSync(ctxTmp, ctxContent, 'utf8');
+      fs.renameSync(ctxTmp, ctxOut);
+    }
+  }
+
   process.stdout.write(`Initialized state.json for sprint ${sprintId} with ${storyIds.length} stories\n`);
 }
 

package/templates/cleargate-planning/.cleargate/scripts/lib/report-filename.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * report-filename.mjs — Shared helper for computing the sprint report filename.
+ *
+ * Named export only — no default.
+ *
+ * Dependencies: node:path, node:fs only. No third-party deps.
+ *
+ * Design notes:
+ *   - Helper is pure given its arguments + a filesystem read (when opts.forRead=true).
+ *   - Never throws — callers decide whether to fs.readFileSync and handle ENOENT.
+ *   - Never reads env vars. Sprint dir resolution stays in callers.
+ *     (Each consumer owns CLEARGATE_SPRINT_DIR resolution.)
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+
+/**
+ * Compute the report filename for a given sprint directory + sprint ID.
+ *
+ * New naming (SPRINT-18+): SPRINT-<#>_REPORT.md where <#> is the numeric
+ *   portion of the sprint-id (e.g. "18" for "SPRINT-18").
+ * No-numeric-portion ids (e.g. "SPRINT-TEST") → plain REPORT.md.
+ *
+ * Backwards-compat read-fallback: when opts.forRead === true AND the new-name
+ *   file is absent BUT legacy REPORT.md exists, return the legacy path.
+ *   Covers SPRINT-01..17 archives written before STORY-025-03's naming change.
+ *   MUST NOT rename or rewrite those pre-existing files.
+ *
+ * @param {string} sprintDirPath  absolute path to the sprint directory
+ * @param {string} sprintId       e.g. "SPRINT-18" or "SPRINT-TEST"
+ * @param {{ forRead?: boolean }} [opts]
+ * @returns {string} absolute path to the report file
+ */
+export function reportFilename(sprintDirPath, sprintId, opts) {
+  const numMatch = sprintId.match(/^SPRINT-(\d+)$/);
+  if (!numMatch) {
+    // No numeric portion — use plain REPORT.md (e.g. SPRINT-TEST)
+    return path.join(sprintDirPath, 'REPORT.md');
+  }
+  const sprintNumber = numMatch[1];
+  const newName = path.join(sprintDirPath, `SPRINT-${sprintNumber}_REPORT.md`);
+
+  // Read-fallback: if the new-name file doesn't exist but legacy REPORT.md does, use legacy.
+  if (opts?.forRead) {
+    const legacyName = path.join(sprintDirPath, 'REPORT.md');
+    if (!fs.existsSync(newName) && fs.existsSync(legacyName)) {
+      return legacyName;
+    }
+  }
+
+  return newName;
+}