cleargate 0.2.1 → 0.4.0

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

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * assert_story_files.mjs — Gate-2 story-file existence assertion
+ *
+ * Usage: node assert_story_files.mjs <sprint-file-path>
+ *
+ * Parses the "## 1. Consolidated Deliverables" section of a sprint file for
+ * STORY-\d+-\d+ IDs, then checks that each has a corresponding
+ * pending-sync/STORY-<id>_*.md file under the repo root.
+ *
+ * Exit 0:  all story files present (prints summary to stdout)
+ * Exit 1:  one or more missing (prints JSON {missing,present} to stderr)
+ * Exit 2:  usage / parse error
+ *
+ * Env:
+ *   CLEARGATE_REPO_ROOT  override repo root (for test isolation)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Resolve repo root: .cleargate/scripts/ -> ../../ (two levels up)
+const REPO_ROOT = process.env.CLEARGATE_REPO_ROOT
+  ? path.resolve(process.env.CLEARGATE_REPO_ROOT)
+  : path.resolve(__dirname, '..', '..');
+
+function usage() {
+  process.stderr.write('Usage: node assert_story_files.mjs <sprint-file-path>\n');
+  process.exit(2);
+}
+
+/**
+ * Extract the "## 1. Consolidated Deliverables" section from sprint markdown.
+ * Returns the section text or null if not found.
+ *
+ * Strategy: split on ^## headings, find the one starting with "1. Consolidated Deliverables".
+ * This avoids regex lookahead pitfalls with end-of-string anchors in JS.
+ */
+function extractDeliverablesSection(content) {
+  // Split on lines that start a new ## section (lookahead keeps delimiter in next part)
+  const parts = content.split(/^(?=## )/m);
+  const deliverables = parts.find((p) =>
+    /^## 1\.? Consolidated Deliverables\b/m.test(p)
+  );
+  if (!deliverables) return null;
+  // Strip the header line itself, return the rest
+  return deliverables.replace(/^## [^\n]*\n/, '');
+}
+
+/**
+ * Extract deduplicated STORY-\d+-\d+ IDs from a text block.
+ */
+function extractStoryIds(text) {
+  const matches = text.match(/STORY-\d+-\d+/g) || [];
+  return [...new Set(matches)];
+}
+
+/**
+ * Check whether pending-sync contains a file matching STORY-<id>_*.md
+ * Returns the matching filename or null.
+ */
+function findStoryFile(repoRoot, storyId) {
+  const pendingSync = path.join(repoRoot, '.cleargate', 'delivery', 'pending-sync');
+  let entries;
+  try {
+    entries = fs.readdirSync(pendingSync);
+  } catch {
+    return null;
+  }
+  const prefix = `${storyId}_`;
+  const match = entries.find(
+    (e) => e.startsWith(prefix) && e.endsWith('.md')
+  );
+  return match ? path.join(pendingSync, match) : null;
+}
+
+/**
+ * Main assertion logic.
+ * Returns { missing: string[], present: string[] }
+ */
+function assertStoryFiles(sprintFilePath, repoRoot) {
+  let content;
+  try {
+    content = fs.readFileSync(sprintFilePath, 'utf8');
+  } catch (err) {
+    process.stderr.write(`Error: cannot read sprint file: ${err.message}\n`);
+    process.exit(2);
+  }
+
+  const section = extractDeliverablesSection(content);
+  if (section === null) {
+    process.stderr.write(
+      'Error: "## 1. Consolidated Deliverables" section not found in sprint file\n'
+    );
+    process.exit(2);
+  }
+
+  const storyIds = extractStoryIds(section);
+  if (storyIds.length === 0) {
+    process.stderr.write('Warning: no STORY-IDs found in §1 Consolidated Deliverables\n');
+    // Return empty — no files to check, nothing is missing
+    return { missing: [], present: [] };
+  }
+
+  const missing = [];
+  const present = [];
+  for (const id of storyIds) {
+    const found = findStoryFile(repoRoot, id);
+    if (found) {
+      present.push(id);
+    } else {
+      missing.push(id);
+    }
+  }
+
+  return { missing, present };
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length === 0 || args[0].startsWith('--')) usage();
+
+  const sprintFilePath = path.resolve(args[0]);
+
+  const { missing, present } = assertStoryFiles(sprintFilePath, REPO_ROOT);
+
+  if (missing.length === 0) {
+    process.stdout.write(
+      `OK: all ${present.length} story file(s) present in pending-sync/\n`
+    );
+    process.exit(0);
+  } else {
+    process.stderr.write(
+      JSON.stringify({ missing, present }, null, 2) + '\n'
+    );
+    process.stderr.write(
+      `MISSING: ${missing.length} story file(s) not found in pending-sync/: ${missing.join(', ')}\n`
+    );
+    process.exit(1);
+  }
+}
+
+main();

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

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+/**
+ * close_sprint.mjs — Six-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)
+ *
+ * Steps:
+ *   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
+ *   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
+ *
+ * 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
+ * waiting for a Reporter-produced file. Replaces the Step-4 gate; implies ack.
+ * Refuses empty stdin or pre-existing REPORT.md.
+ *
+ * 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
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
+import { TERMINAL_STATES } from './constants.mjs';
+import { validateState } from './validate_state.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const SCRIPTS_DIR = __dirname;
+
+function usage() {
+  process.stderr.write(
+    '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'
+  );
+  process.exit(2);
+}
+
+/**
+ * Atomic write using tmp+rename pattern (per M1 update_state.mjs convention).
+ * @param {string} filePath
+ * @param {object} data
+ */
+function atomicWrite(filePath, data) {
+  const tmpFile = `${filePath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmpFile, JSON.stringify(data, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmpFile, filePath);
+}
+
+/**
+ * Atomic write for a string body. Separate from atomicWrite() so we don't
+ * accidentally JSON.stringify a markdown body.
+ * @param {string} filePath
+ * @param {string} body
+ */
+function atomicWriteString(filePath, body) {
+  const tmpFile = `${filePath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmpFile, body, 'utf8');
+  fs.renameSync(tmpFile, filePath);
+}
+
+/**
+ * Invoke a script via node (for .mjs scripts in the same directory).
+ * Throws on non-zero exit.
+ * @param {string} scriptName
+ * @param {string[]} scriptArgs
+ * @param {object} env
+ */
+function invokeScript(scriptName, scriptArgs, env) {
+  const scriptPath = path.join(SCRIPTS_DIR, scriptName);
+  if (!fs.existsSync(scriptPath)) {
+    throw new Error(`Script not found: ${scriptPath}`);
+  }
+  const argStr = scriptArgs.map(a => JSON.stringify(a)).join(' ');
+  const cmd = `node ${JSON.stringify(scriptPath)} ${argStr}`;
+  execSync(cmd, {
+    stdio: 'inherit',
+    env: Object.assign({}, process.env, env || {}),
+  });
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length < 1) usage();
+
+  const sprintId = args[0];
+  const reportBodyStdin = args.includes('--report-body-stdin');
+  const assumeAck = args.includes('--assume-ack') || reportBodyStdin;
+
+  const sprintDir = process.env.CLEARGATE_SPRINT_DIR
+    ? path.resolve(process.env.CLEARGATE_SPRINT_DIR)
+    : path.join(REPO_ROOT, '.cleargate', 'sprint-runs', sprintId);
+
+  if (!fs.existsSync(sprintDir)) {
+    process.stderr.write(`Error: sprint directory not found: ${sprintDir}\n`);
+    process.exit(1);
+  }
+
+  const stateFile = process.env.CLEARGATE_STATE_FILE
+    ? path.resolve(process.env.CLEARGATE_STATE_FILE)
+    : path.join(sprintDir, 'state.json');
+
+  // ── Step 1: Load and validate state.json ──────────────────────────────────
+  if (!fs.existsSync(stateFile)) {
+    process.stderr.write(
+      `Error: state.json not found at ${stateFile}\n` +
+      `Hint: run init_sprint.mjs ${sprintId} --stories <ids> first\n`
+    );
+    process.exit(1);
+  }
+
+  let state;
+  try {
+    state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+  } catch (err) {
+    process.stderr.write(`Error: failed to parse state.json: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  const { valid, errors } = validateState(state);
+  if (!valid) {
+    process.stderr.write('Error: state.json validation failed:\n');
+    for (const e of errors) process.stderr.write(`  - ${e}\n`);
+    process.exit(1);
+  }
+
+  // ── Step 2: Refuse if any story not in TERMINAL_STATES ────────────────────
+  const nonTerminal = [];
+  for (const [storyId, story] of Object.entries(state.stories || {})) {
+    if (!TERMINAL_STATES.includes(story.state)) {
+      nonTerminal.push(`${storyId}: ${story.state} — not terminal`);
+    }
+  }
+
+  if (nonTerminal.length > 0) {
+    process.stderr.write('Error: sprint cannot close — non-terminal stories:\n');
+    for (const msg of nonTerminal) {
+      process.stderr.write(`  ${msg}\n`);
+    }
+    process.exit(1);
+  }
+
+  process.stdout.write(`Step 1-2 passed: all ${Object.keys(state.stories || {}).length} stories are terminal.\n`);
+
+  // ── Step 3: Invoke prefill_report.mjs ─────────────────────────────────────
+  process.stdout.write('Step 3: running prefill_report.mjs...\n');
+  try {
+    invokeScript('prefill_report.mjs', [sprintId], {
+      CLEARGATE_STATE_FILE: stateFile,
+      CLEARGATE_SPRINT_DIR: sprintDir,
+    });
+  } catch (err) {
+    process.stderr.write(`Error: prefill_report.mjs failed: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  // ── Step 4: Orchestrator spawns Reporter separately ───────────────────────
+  // This script only validates preconditions; it does NOT fork the Reporter agent.
+  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`
+  );
+
+  // 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.
+  if (reportBodyStdin) {
+    if (fs.existsSync(reportFile)) {
+      process.stderr.write(
+        `Error: REPORT.md already exists at ${reportFile}\n` +
+        'Delete it or skip --report-body-stdin mode to use the primary Reporter-write path.\n'
+      );
+      process.exit(1);
+    }
+    let body;
+    try {
+      body = fs.readFileSync(0, 'utf8');
+    } catch (err) {
+      process.stderr.write(`Error: failed to read stdin: ${err.message}\n`);
+      process.exit(1);
+    }
+    if (!body || body.trim().length === 0) {
+      process.stderr.write('Error: empty report body — refusing to write.\n');
+      process.exit(1);
+    }
+    atomicWriteString(reportFile, body);
+    process.stdout.write(
+      `Step 4.5 (stdin mode): REPORT.md written (${body.length} bytes) at ${reportFile}\n`
+    );
+    // Fall through to Step 5 + 6 unconditionally — stdin mode implies ack.
+  } else if (!assumeAck) {
+    if (!fs.existsSync(reportFile)) {
+      process.stdout.write(
+        '\nWaiting for Reporter to produce REPORT.md...\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
+    process.stdout.write(
+      `\nREPORT.md found at ${reportFile}\n` +
+      'Review the report, then confirm close by re-running with --assume-ack\n'
+    );
+    process.exit(0);
+  }
+
+  // ── Step 5: Flip sprint_status to "Completed" ────────────────────────────
+  process.stdout.write('Step 5: flipping sprint_status to "Completed"...\n');
+  const now = new Date().toISOString();
+  state.sprint_status = 'Completed';
+  state.last_action = `close_sprint: sprint ${sprintId} completed`;
+  state.updated_at = now;
+  atomicWrite(stateFile, state);
+  process.stdout.write(`sprint_status flipped to "Completed" at ${now}\n`);
+
+  // ── Step 6: Invoke suggest_improvements.mjs unconditionally ───────────────
+  process.stdout.write('Step 6: running suggest_improvements.mjs...\n');
+  try {
+    invokeScript('suggest_improvements.mjs', [sprintId], {
+      CLEARGATE_STATE_FILE: stateFile,
+      CLEARGATE_SPRINT_DIR: sprintDir,
+    });
+  } 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('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`);
+}
+
+main();

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

@@ -0,0 +1,57 @@
+/**
+ * ClearGate Execution Phase v2 — Constants
+ *
+ * state.json v1 Schema (LOCKED — any future field change must bump schema_version):
+ *
+ * {
+ *   "schema_version": 1,          // integer, mandatory
+ *   "sprint_id": "S-NN",          // string
+ *   "execution_mode": "v1"|"v2",  // string
+ *   "sprint_status": "Active",    // string
+ *   "stories": {
+ *     "STORY-NNN-NN": {
+ *       "state": "Ready to Bounce",  // one of VALID_STATES
+ *       "qa_bounces": 0,             // integer 0..BOUNCE_CAP
+ *       "arch_bounces": 0,           // integer 0..BOUNCE_CAP
+ *       "worktree": null,            // string|null — path to worktree checkout
+ *       "updated_at": "<ISO-8601>",  // string
+ *       "notes": ""                  // string
+ *     }
+ *   },
+ *   "last_action": "<string>",    // human-readable last operation
+ *   "updated_at": "<ISO-8601>"    // string
+ * }
+ */
+
+export const SCHEMA_VERSION = 1;
+
+export const BOUNCE_CAP = 3;
+
+export const VALID_STATES = [
+  'Ready to Bounce',
+  'Bouncing',
+  'QA Passed',
+  'Architect Passed',
+  'Sprint Review',
+  'Done',
+  'Escalated',
+  'Parking Lot',
+];
+
+export const TERMINAL_STATES = ['Done', 'Escalated', 'Parking Lot'];
+
+/**
+ * Canonical state-machine transitions table.
+ * Key: current state. Value: array of allowed next states.
+ * Terminal states have empty arrays (no transitions out).
+ */
+export const STATE_TRANSITIONS = {
+  'Ready to Bounce':   ['Bouncing', 'Parking Lot'],
+  'Bouncing':          ['QA Passed', 'Ready to Bounce', 'Escalated', 'Parking Lot'],
+  'QA Passed':         ['Architect Passed', 'Ready to Bounce', 'Escalated', 'Parking Lot'],
+  'Architect Passed':  ['Sprint Review', 'Ready to Bounce', 'Escalated', 'Parking Lot'],
+  'Sprint Review':     ['Done', 'Ready to Bounce', 'Escalated', 'Parking Lot'],
+  'Done':              [],
+  'Escalated':         [],
+  'Parking Lot':       [],
+};