cleargate 0.2.1 → 0.4.0

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

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * update_state.mjs — Atomic state/counter update for a story in state.json
+ *
+ * Usage:
+ *   node update_state.mjs <STORY-ID> <new-state>   — transition to a new state
+ *   node update_state.mjs <STORY-ID> --qa-bounce   — increment qa_bounces counter
+ *   node update_state.mjs <STORY-ID> --arch-bounce — increment arch_bounces counter
+ *
+ * Atomic write: write to .tmp.<pid> file, then rename to final path.
+ * Idempotent: if new state equals current (for state transitions) and
+ *   no counter change, exit 0 without rewriting the file.
+ *
+ * Auto-escalation: when qa_bounces or arch_bounces reaches BOUNCE_CAP (3),
+ *   state is automatically set to "Escalated".
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SCHEMA_VERSION, VALID_STATES, TERMINAL_STATES, BOUNCE_CAP } from './constants.mjs';
+import { validateState } from './validate_state.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+function usage() {
+  process.stderr.write(
+    'Usage:\n' +
+    '  node update_state.mjs <STORY-ID> <new-state>\n' +
+    '  node update_state.mjs <STORY-ID> --qa-bounce\n' +
+    '  node update_state.mjs <STORY-ID> --arch-bounce\n'
+  );
+  process.exit(2);
+}
+
+function resolveStateFile() {
+  const envFile = process.env.CLEARGATE_STATE_FILE;
+  if (envFile) return path.resolve(envFile);
+  throw new Error(
+    'CLEARGATE_STATE_FILE env var not set; cannot resolve state.json'
+  );
+}
+
+function atomicWrite(stateFile, state) {
+  const tmpFile = `${stateFile}.tmp.${process.pid}`;
+  fs.writeFileSync(tmpFile, JSON.stringify(state, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmpFile, stateFile);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length < 2) usage();
+
+  const storyId = args[0];
+  const action = args[1];
+
+  const stateFile = resolveStateFile();
+
+  if (!fs.existsSync(stateFile)) {
+    process.stderr.write(`Error: state.json not found at ${stateFile}\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);
+  }
+
+  // Validate existing state before modifications
+  const { valid, errors } = validateState(state);
+  if (!valid) {
+    process.stderr.write(`Error: state.json is invalid:\n`);
+    for (const e of errors) process.stderr.write(`  - ${e}\n`);
+    process.exit(1);
+  }
+
+  if (!state.stories[storyId]) {
+    process.stderr.write(`Error: story ${storyId} not found in state.json\n`);
+    process.exit(1);
+  }
+
+  const story = state.stories[storyId];
+
+  if (action === '--qa-bounce') {
+    if (story.state === 'Escalated') {
+      process.stderr.write(`Error: story ${storyId} is already Escalated\n`);
+      process.exit(1);
+    }
+    story.qa_bounces += 1;
+    if (story.qa_bounces >= BOUNCE_CAP) {
+      story.state = 'Escalated';
+    }
+    story.updated_at = new Date().toISOString();
+    state.last_action = `qa-bounce ${storyId}: qa_bounces=${story.qa_bounces}`;
+    state.updated_at = story.updated_at;
+    atomicWrite(stateFile, state);
+    process.stdout.write(
+      `Updated ${storyId}: qa_bounces=${story.qa_bounces}, state=${story.state}\n`
+    );
+
+  } else if (action === '--arch-bounce') {
+    if (story.state === 'Escalated') {
+      process.stderr.write(`Error: story ${storyId} is already Escalated\n`);
+      process.exit(1);
+    }
+    story.arch_bounces += 1;
+    if (story.arch_bounces >= BOUNCE_CAP) {
+      story.state = 'Escalated';
+    }
+    story.updated_at = new Date().toISOString();
+    state.last_action = `arch-bounce ${storyId}: arch_bounces=${story.arch_bounces}`;
+    state.updated_at = story.updated_at;
+    atomicWrite(stateFile, state);
+    process.stdout.write(
+      `Updated ${storyId}: arch_bounces=${story.arch_bounces}, state=${story.state}\n`
+    );
+
+  } else {
+    // State transition
+    const newState = action;
+
+    if (!VALID_STATES.includes(newState)) {
+      process.stderr.write(
+        `Error: invalid state "${newState}"; valid states: ${VALID_STATES.join(', ')}\n`
+      );
+      process.exit(1);
+    }
+
+    // Idempotency: if state is already the target, no-op
+    if (story.state === newState) {
+      process.stdout.write(`No-op: ${storyId} is already in state "${newState}"\n`);
+      process.exit(0);
+    }
+
+    // Reset worktree to null on Done
+    if (newState === 'Done') {
+      story.worktree = null;
+    }
+
+    story.state = newState;
+    story.updated_at = new Date().toISOString();
+    state.last_action = `transition ${storyId} → ${newState}`;
+    state.updated_at = story.updated_at;
+    atomicWrite(stateFile, state);
+    process.stdout.write(`Updated ${storyId}: state="${newState}"\n`);
+  }
+}
+
+main();

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

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * validate_bounce_readiness.mjs — Pre-bounce gate check for a story
+ *
+ * Usage: node validate_bounce_readiness.mjs <STORY-ID>
+ *
+ * Checks:
+ *   (a) state.json exists and is valid
+ *   (b) story is present in state.json
+ *   (c) story state is "Ready to Bounce"
+ *   (d) git working tree is clean (git status --porcelain returns empty)
+ *
+ * Exits non-zero on any failure, with detail on stderr.
+ * Exits 0 if all checks pass.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
+import { validateState } from './validate_state.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+function usage() {
+  process.stderr.write('Usage: node validate_bounce_readiness.mjs <STORY-ID>\n');
+  process.exit(2);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length < 1 || args[0].startsWith('--')) usage();
+
+  const storyId = args[0];
+
+  const stateFile = process.env.CLEARGATE_STATE_FILE
+    ? path.resolve(process.env.CLEARGATE_STATE_FILE)
+    : null;
+
+  if (!stateFile) {
+    process.stderr.write(
+      'Error: CLEARGATE_STATE_FILE env var not set; cannot resolve state.json\n'
+    );
+    process.exit(1);
+  }
+
+  // (a) state.json exists
+  if (!fs.existsSync(stateFile)) {
+    process.stderr.write(`Error: state.json not found at ${stateFile}\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);
+  }
+
+  // (a) schema valid
+  const { valid, errors } = validateState(state);
+  if (!valid) {
+    process.stderr.write('Error: state.json is invalid:\n');
+    for (const e of errors) process.stderr.write(`  - ${e}\n`);
+    process.exit(1);
+  }
+
+  // (b) story present
+  if (!state.stories[storyId]) {
+    process.stderr.write(`Error: story ${storyId} not found in state.json\n`);
+    process.exit(1);
+  }
+
+  const story = state.stories[storyId];
+
+  // (c) state is "Ready to Bounce"
+  if (story.state !== 'Ready to Bounce') {
+    process.stderr.write(
+      `Error: story ${storyId} state is "${story.state}", expected "Ready to Bounce"\n`
+    );
+    process.exit(1);
+  }
+
+  // (d) git working tree is clean
+  let gitOutput;
+  try {
+    gitOutput = execSync('git status --porcelain', {
+      cwd: REPO_ROOT,
+      encoding: 'utf8',
+    });
+  } catch (err) {
+    process.stderr.write(`Error: failed to run git status: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  if (gitOutput.trim().length > 0) {
+    process.stderr.write(
+      `Error: git working tree is dirty. Uncommitted changes:\n${gitOutput}`
+    );
+    process.exit(1);
+  }
+
+  process.stdout.write(
+    `Bounce readiness check passed for ${storyId} (state="Ready to Bounce", clean tree)\n`
+  );
+  process.exit(0);
+}
+
+main();

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

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * validate_state.mjs — Validate state.json schema and invariants
+ *
+ * Usage: node validate_state.mjs [--state-file <path>]
+ *
+ * Reads .cleargate/sprint-runs/<sprint-id>/state.json (or a specified path),
+ * confirms schema version, and reports invariant violations.
+ *
+ * Exports validateState(state) for use by other scripts.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SCHEMA_VERSION, VALID_STATES, BOUNCE_CAP } from './constants.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+/**
+ * Validate a parsed state object.
+ * @param {object} state - Parsed state.json content
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateState(state) {
+  const errors = [];
+
+  if (typeof state !== 'object' || state === null) {
+    errors.push('state is not an object');
+    return { valid: false, errors };
+  }
+
+  if (state.schema_version !== SCHEMA_VERSION) {
+    errors.push(
+      `schema_version mismatch: expected ${SCHEMA_VERSION}, got ${state.schema_version}`
+    );
+  }
+
+  if (!state.sprint_id) {
+    errors.push('missing required field: sprint_id');
+  }
+
+  if (!state.execution_mode) {
+    errors.push('missing required field: execution_mode');
+  }
+
+  if (!state.sprint_status) {
+    errors.push('missing required field: sprint_status');
+  }
+
+  if (typeof state.stories !== 'object' || state.stories === null) {
+    errors.push('stories field must be an object');
+    return { valid: false, errors };
+  }
+
+  for (const [storyId, story] of Object.entries(state.stories)) {
+    if (typeof story !== 'object' || story === null) {
+      errors.push(`story ${storyId}: not an object`);
+      continue;
+    }
+
+    if (!VALID_STATES.includes(story.state)) {
+      errors.push(
+        `story ${storyId}: invalid state "${story.state}"; expected one of: ${VALID_STATES.join(', ')}`
+      );
+    }
+
+    if (typeof story.qa_bounces !== 'number') {
+      errors.push(`story ${storyId}: qa_bounces must be a number`);
+    } else if (story.qa_bounces > BOUNCE_CAP) {
+      errors.push(
+        `invariant violation: story ${storyId} qa_bounces=${story.qa_bounces} exceeds BOUNCE_CAP (${BOUNCE_CAP})`
+      );
+    } else if (story.qa_bounces < 0) {
+      errors.push(`story ${storyId}: qa_bounces must be >= 0`);
+    }
+
+    if (typeof story.arch_bounces !== 'number') {
+      errors.push(`story ${storyId}: arch_bounces must be a number`);
+    } else if (story.arch_bounces > BOUNCE_CAP) {
+      errors.push(
+        `invariant violation: story ${storyId} arch_bounces=${story.arch_bounces} exceeds BOUNCE_CAP (${BOUNCE_CAP})`
+      );
+    } else if (story.arch_bounces < 0) {
+      errors.push(`story ${storyId}: arch_bounces must be >= 0`);
+    }
+
+    if (!story.updated_at) {
+      errors.push(`story ${storyId}: missing required field: updated_at`);
+    }
+  }
+
+  if (!state.updated_at) {
+    errors.push('missing required top-level field: updated_at');
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+// CLI mode
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const args = process.argv.slice(2);
+  const fileIdx = args.indexOf('--state-file');
+  let stateFile;
+
+  if (fileIdx !== -1 && args[fileIdx + 1]) {
+    stateFile = path.resolve(args[fileIdx + 1]);
+  } else {
+    // Attempt to discover via environment or fallback
+    const envStateFile = process.env.CLEARGATE_STATE_FILE;
+    if (envStateFile) {
+      stateFile = path.resolve(envStateFile);
+    } else {
+      // Look for state.json in sprint-runs/
+      const sprintRunsDir = path.join(REPO_ROOT, '.cleargate', 'sprint-runs');
+      if (!fs.existsSync(sprintRunsDir)) {
+        process.stderr.write(`Error: sprint-runs directory not found at ${sprintRunsDir}\n`);
+        process.exit(1);
+      }
+      const entries = fs.readdirSync(sprintRunsDir);
+      const found = entries
+        .map((e) => path.join(sprintRunsDir, e, 'state.json'))
+        .filter((p) => fs.existsSync(p));
+      if (found.length === 0) {
+        process.stderr.write('Error: no state.json found in sprint-runs/\n');
+        process.exit(1);
+      }
+      if (found.length > 1) {
+        process.stderr.write(
+          `Multiple state.json files found; specify --state-file:\n${found.join('\n')}\n`
+        );
+        process.exit(1);
+      }
+      stateFile = found[0];
+    }
+  }
+
+  if (!fs.existsSync(stateFile)) {
+    process.stderr.write(`Error: state.json not found at ${stateFile}\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.stdout.write(`state.json at ${stateFile} is valid (schema_version=${state.schema_version})\n`);
+    process.exit(0);
+  } else {
+    process.stderr.write(`Validation failed for ${stateFile}:\n`);
+    for (const err of errors) {
+      process.stderr.write(`  - ${err}\n`);
+    }
+    process.exit(1);
+  }
+}

package/templates/cleargate-planning/.cleargate/templates/Bug.md

@@ -35,6 +35,15 @@ cached_gate_result:
   pass: null
   failing_criteria: []
   last_gate_check: null
+# Sync attribution (EPIC-010). Optional; stamped by `cleargate push` / `cleargate pull`.
+pushed_by: null            # STORY-010-07 writer / STORY-010-04 reader
+pushed_at: null            # STORY-010-07 writer / STORY-010-04 reader
+last_pulled_by: null       # STORY-010-04 writer / STORY-010-03 reader
+last_pulled_at: null       # STORY-010-04 writer / STORY-010-03 reader
+last_remote_update: null   # STORY-010-02 writer (from MCP) / STORY-010-03 reader
+source: "local-authored"   # STORY-010-05 flips to "remote-authored" on intake
+last_synced_status: null   # STORY-010-04 writer; required for conflict-detector rule 6
+last_synced_body_sha: null # STORY-010-04 writer; sha256 of body at last sync
 ---
 
 # BUG-{ID}: {Bug Name}

package/templates/cleargate-planning/.cleargate/templates/CR.md

@@ -33,6 +33,15 @@ cached_gate_result:
   pass: null
   failing_criteria: []
   last_gate_check: null
+# Sync attribution (EPIC-010). Optional; stamped by `cleargate push` / `cleargate pull`.
+pushed_by: null            # STORY-010-07 writer / STORY-010-04 reader
+pushed_at: null            # STORY-010-07 writer / STORY-010-04 reader
+last_pulled_by: null       # STORY-010-04 writer / STORY-010-03 reader
+last_pulled_at: null       # STORY-010-04 writer / STORY-010-03 reader
+last_remote_update: null   # STORY-010-02 writer (from MCP) / STORY-010-03 reader
+source: "local-authored"   # STORY-010-05 flips to "remote-authored" on intake
+last_synced_status: null   # STORY-010-04 writer; required for conflict-detector rule 6
+last_synced_body_sha: null # STORY-010-04 writer; sha256 of body at last sync
 ---
 
 # CR-{ID}: {Change Request Name}

package/templates/cleargate-planning/.cleargate/templates/Sprint Plan Template.md

@@ -11,6 +11,7 @@ sprint_id: "SPRINT-{ID}"
 remote_id: "{PM_TOOL_SPRINT_ID}"
 source_tool: "linear | jira"
 status: "Draft | Active | Completed"
+execution_mode: "v1"   # Enum: "v1" | "v2". Default "v1". Under "v2", §§15–18 of cleargate-protocol.md are enforcing (worktree isolation, pre-gate scanning, bounce counters, flashcard gate, sprint-close pipeline). Under "v1", those sections are advisory only and all new CLI commands (sprint init|close, story start|complete, gate qa|arch, state update|validate) print an inert-mode message. Set to "v2" only after all EPIC-013 M2 stories have shipped and the Architect has completed a Sprint Design Review (see §19 of the protocol).
 start_date: "{YYYY-MM-DD}"
 end_date: "{YYYY-MM-DD}"
 synced_at: "{ISO-8601 timestamp}"
@@ -36,11 +37,36 @@ cached_gate_result:
 ## Sprint Goal
 {One clear sentence describing the primary objective of this sprint, as defined in the PM tool.}
 
-## Consolidated Deliverables
+## 1. Consolidated Deliverables
 *(Pulled from PM tool. IDs are the remote PM entity IDs.)*
 
-- `{TASK-ID}`: {Title} — {Brief Description}
-- `{TASK-ID}`: {Title} — {Brief Description}
+| Story ID | Title | Milestone | Parallel? | Bounce Exposure |
+|---|---|---|---|---|
+| `{STORY-NNN-NN}` | {Title} | M{N} | y / n | low / med / high |
+
+## 2. Execution Strategy
+*(Written by Architect during Sprint Design Review. Required before `execution_mode: v2` sprint start. Under v1, this section may be omitted or left as a stub.)*
+
+### 2.1 Phase Plan
+{Parallel vs sequential story groups. List which stories run concurrently in each wave and which must be serialized.}
+Example:
+- Wave 1 (sequential): STORY-NNN-01 → STORY-NNN-02 (02 depends on 01's schema)
+- Wave 2 (parallel): STORY-NNN-03 ‖ STORY-NNN-04
+
+### 2.2 Merge Ordering (Shared-File Surface Analysis)
+{List files touched by more than one story. For each shared file, specify which story lands first and why.}
+
+| Shared File | Stories Touching It | Merge Order | Rationale |
+|---|---|---|---|
+| `.cleargate/knowledge/cleargate-protocol.md` | STORY-NNN-01, STORY-NNN-02 | 01 → 02 | 01 adds §16; 02 amends §16 |
+
+### 2.3 Shared-Surface Warnings
+{Explicit conflict risks. One bullet per risk. Cite file + story pair.}
+- None identified. (Replace with actual warnings if applicable.)
+
+### 2.4 ADR-Conflict Flags
+{Any story whose implementation conflicts with an Architectural Decision Record in `.cleargate/knowledge/` or prior sprint decisions. One bullet per flag.}
+- None identified. (Replace with actual flags if applicable.)
 
 ## Risks & Dependencies
 *(As defined in the PM tool.)*

package/templates/cleargate-planning/.cleargate/templates/epic.md

@@ -38,6 +38,15 @@ cached_gate_result:
   pass: null
   failing_criteria: []
   last_gate_check: null
+# Sync attribution (EPIC-010). Optional; stamped by `cleargate push` / `cleargate pull`.
+pushed_by: null            # STORY-010-07 writer / STORY-010-04 reader
+pushed_at: null            # STORY-010-07 writer / STORY-010-04 reader
+last_pulled_by: null       # STORY-010-04 writer / STORY-010-03 reader
+last_pulled_at: null       # STORY-010-04 writer / STORY-010-03 reader
+last_remote_update: null   # STORY-010-02 writer (from MCP) / STORY-010-03 reader
+source: "local-authored"   # STORY-010-05 flips to "remote-authored" on intake
+last_synced_status: null   # STORY-010-04 writer; required for conflict-detector rule 6
+last_synced_body_sha: null # STORY-010-04 writer; sha256 of body at last sync
 ---
 
 # EPIC-{ID}: {Epic Name}

package/templates/cleargate-planning/.cleargate/templates/proposal.md

@@ -28,6 +28,15 @@ cached_gate_result:
   pass: null
   failing_criteria: []
   last_gate_check: null
+# Sync attribution (EPIC-010). Optional; stamped by `cleargate push` / `cleargate pull`.
+pushed_by: null            # STORY-010-07 writer / STORY-010-04 reader
+pushed_at: null            # STORY-010-07 writer / STORY-010-04 reader
+last_pulled_by: null       # STORY-010-04 writer / STORY-010-03 reader
+last_pulled_at: null       # STORY-010-04 writer / STORY-010-03 reader
+last_remote_update: null   # STORY-010-02 writer (from MCP) / STORY-010-03 reader
+source: "local-authored"   # STORY-010-05 flips to "remote-authored" on intake
+last_synced_status: null   # STORY-010-04 writer; required for conflict-detector rule 6
+last_synced_body_sha: null # STORY-010-04 writer; sha256 of body at last sync
 PROPOSAL-{ID}: {Initiative Name}
 1. Initiative & Context
 1.1 Objective

package/templates/cleargate-planning/.cleargate/templates/sprint_context.md

@@ -0,0 +1,42 @@
+---
+sprint_id: "S-NN"
+created_at: "YYYY-MM-DDTHH:MM:SSZ"
+last_updated: "YYYY-MM-DDTHH:MM:SSZ"
+---
+
+# Sprint Context
+
+Per-sprint audit artefact. Populated at sprint init (M1 planning) and re-touched after each story merges. Referenced from every Developer/QA/Architect task brief so all agents start from the same baseline.
+
+## Locked Versions
+
+Frozen dependency versions for this sprint. Orchestrator populates from `package.json` snapshots at sprint init; Developers must not upgrade these mid-sprint without an explicit CR.
+
+| Package | Version |
+|---------|---------|
+| Node    | `>=24.0.0` |
+| TypeScript | `^5.8.0` |
+| (add rows per workspace below) |  |
+
+## Cross-Cutting Rules
+
+Sprint-wide architecture rules and UI/API tokens that every story must honour. Populated from the parent Epic's `<architecture_rules>` block.
+
+1. (rule 1)
+2. (rule 2)
+3. (rule 3)
+
+## Active FLASHCARD Tags
+
+FLASHCARD tags that appear in any story's `<agent_context>` for this sprint. Auto-populated by grepping `.cleargate/FLASHCARD.md` at sprint init. Agents: grep the flashcard file for each tag listed here before starting work.
+
+- `#tag1` — one-line summary of the most recent card
+- `#tag2` — one-line summary
+
+## Adjacent Implementations (Reuse First)
+
+Exported helpers and modules from already-merged stories in this sprint. The Architect updates this section after each story merges. Developers check here before writing new helpers — if the module already exists, import it; duplication is a kick-back criterion.
+
+| Story | Module / Export | Path |
+|-------|----------------|------|
+| (populated as stories merge) | | |