cleargate 0.10.0 → 0.11.0

package/dist/templates/cleargate-planning/.cleargate/scripts/run_script.sh

@@ -1,123 +1,209 @@
 #!/usr/bin/env bash
-# run_script.sh — Wrapper that captures stdout/stderr separately and prints a
-# structured diagnostic block on non-zero exit.
-# Usage: run_script.sh <script-name> [args...]
-# Supported extensions: .mjs (runs via node), .sh (runs via bash)
+# run_script.sh — Arbitrary-command wrapper that captures stdout/stderr independently
+# and writes a structured JSON incident file on non-zero exit.
+#
+# Interface: bash run_script.sh <command> [args...]
+#   <command>  — any executable on PATH (e.g. node, bash, sh, true, false)
+#   [args...]  — forwarded to the command unchanged
+#
+# Example (node script):
+#   bash run_script.sh node .cleargate/scripts/update_state.mjs STORY-01 Done
+# Example (bash script):
+#   bash run_script.sh bash .cleargate/scripts/pre_gate_runner.sh qa .worktrees/X sprint/S-01
+#
+# On success (exit 0): stdout+stderr are passed through; no incident file written.
+# On failure (exit ≠ 0): stdout+stderr are passed through AND a JSON incident is
+#   written to .cleargate/sprint-runs/<active-sprint>/.script-incidents/<ts>-<hash>.json
+#
+# Self-exemption: if RUN_SCRIPT_ACTIVE=1 is already set, the wrapper is already
+# running — do not nest. Execute the command directly to avoid infinite recursion.
+# This guard implements the self-exempt contract documented in SKILL.md §C.x.
+#
+# Env vars read:
+#   ORCHESTRATOR_PROJECT_DIR  — project root override (falls back to CLAUDE_PROJECT_DIR,
+#                               then to git rev-parse --show-toplevel, then script dir ancestor)
+#   AGENT_TYPE                — populates incident JSON agent_type field (null if empty)
+#   WORK_ITEM_ID              — populates incident JSON work_item_id field (null if empty)
+#   RUN_SCRIPT_ACTIVE         — self-exemption guard (set to 1 by this wrapper)
+
 set -euo pipefail
 
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# ---------------------------------------------------------------------------
+# Self-exemption guard — do not wrap recursively
+# ---------------------------------------------------------------------------
+if [[ "${RUN_SCRIPT_ACTIVE:-}" == "1" ]]; then
+  # Already inside a wrapper invocation; pass through directly, no JSON capture
+  exec "$@"
+fi
 
 # ---------------------------------------------------------------------------
 # Usage guard
 # ---------------------------------------------------------------------------
 if [[ $# -lt 1 ]]; then
-  echo "Usage: run_script.sh <script-name> [args...]" >&2
+  echo "Usage: bash run_script.sh <command> [args...]" >&2
   exit 2
 fi
 
-SCRIPT_NAME="$1"
-shift
-SCRIPT_ARGS=()
-if [[ $# -gt 0 ]]; then
-  SCRIPT_ARGS=("$@")
-fi
-
 # ---------------------------------------------------------------------------
-# Resolve path — script may be an absolute path or relative to SCRIPT_DIR
+# Resolve project root for incident file path
 # ---------------------------------------------------------------------------
-if [[ "$SCRIPT_NAME" == /* ]]; then
-  SCRIPT_PATH="$SCRIPT_NAME"
-else
-  SCRIPT_PATH="${SCRIPT_DIR}/${SCRIPT_NAME}"
-fi
+_resolve_project_root() {
+  # Priority: ORCHESTRATOR_PROJECT_DIR → CLAUDE_PROJECT_DIR → git toplevel → script dir ancestor
+  if [[ -n "${ORCHESTRATOR_PROJECT_DIR:-}" ]]; then
+    echo "$ORCHESTRATOR_PROJECT_DIR"
+    return
+  fi
+  if [[ -n "${CLAUDE_PROJECT_DIR:-}" ]]; then
+    echo "$CLAUDE_PROJECT_DIR"
+    return
+  fi
+  if _root=$(git rev-parse --show-toplevel 2>/dev/null); then
+    echo "$_root"
+    return
+  fi
+  # Fallback: assume run_script.sh lives in <repo>/.cleargate/scripts/
+  echo "$(cd "$(dirname "${BASH_SOURCE[0]}")" && cd ../.. && pwd)"
+}
 
-# ---------------------------------------------------------------------------
-# Extension routing
-# ---------------------------------------------------------------------------
-EXT="${SCRIPT_NAME##*.}"
-case "$EXT" in
-  mjs)  RUNNER="node" ;;
-  sh)   RUNNER="bash" ;;
-  *)
-    echo "unsupported extension: .${EXT}" >&2
-    exit 2
-    ;;
-esac
+PROJECT_ROOT="$(_resolve_project_root)"
+SPRINT_RUNS_DIR="${PROJECT_ROOT}/.cleargate/sprint-runs"
+ACTIVE_FILE="${SPRINT_RUNS_DIR}/.active"
 
-# ---------------------------------------------------------------------------
-# Check script exists
-# ---------------------------------------------------------------------------
-if [[ ! -f "$SCRIPT_PATH" ]]; then
-  echo "run_script.sh: script not found: ${SCRIPT_PATH}" >&2
-  exit 2
+# Determine sprint incident dir
+if [[ -f "$ACTIVE_FILE" ]]; then
+  SPRINT_ID="$(cat "$ACTIVE_FILE" | tr -d '[:space:]')"
+  INCIDENTS_DIR="${SPRINT_RUNS_DIR}/${SPRINT_ID}/.script-incidents"
+else
+  # No active sprint sentinel → write to _off-sprint bucket
+  INCIDENTS_DIR="${SPRINT_RUNS_DIR}/_off-sprint/.script-incidents"
 fi
 
 # ---------------------------------------------------------------------------
 # Capture stdout + stderr to temp files
 # ---------------------------------------------------------------------------
-STDOUT_FILE="$(mktemp)"
-STDERR_FILE="$(mktemp)"
-trap 'rm -f "$STDOUT_FILE" "$STDERR_FILE"' EXIT
+STDOUT_TMP="$(mktemp)"
+STDERR_TMP="$(mktemp)"
+trap 'rm -f "$STDOUT_TMP" "$STDERR_TMP"' EXIT
+
+# Mark self as active before running the wrapped command
+export RUN_SCRIPT_ACTIVE=1
 
 EXIT_CODE=0
-if [[ ${#SCRIPT_ARGS[@]} -gt 0 ]]; then
-  "$RUNNER" "$SCRIPT_PATH" "${SCRIPT_ARGS[@]}" > "$STDOUT_FILE" 2> "$STDERR_FILE" || EXIT_CODE=$?
-else
-  "$RUNNER" "$SCRIPT_PATH" > "$STDOUT_FILE" 2> "$STDERR_FILE" || EXIT_CODE=$?
-fi
+"$@" >"$STDOUT_TMP" 2>"$STDERR_TMP" || EXIT_CODE=$?
 
 # ---------------------------------------------------------------------------
-# On success: pass through and exit 0
+# Always pass through stdout + stderr to the caller
+# ---------------------------------------------------------------------------
+cat "$STDOUT_TMP"
+cat "$STDERR_TMP" >&2
+
+# ---------------------------------------------------------------------------
+# On success: nothing more to do
 # ---------------------------------------------------------------------------
 if [[ $EXIT_CODE -eq 0 ]]; then
-  cat "$STDOUT_FILE"
-  cat "$STDERR_FILE" >&2
   exit 0
 fi
 
 # ---------------------------------------------------------------------------
-# On failure: pass stdout through, then print structured diagnostic to stderr
+# On failure: write structured JSON incident file
 # ---------------------------------------------------------------------------
-cat "$STDOUT_FILE"
-
-# Root-cause heuristic (6-branch)
-STDERR_CONTENT="$(cat "$STDERR_FILE")"
-ROOT_CAUSE="unknown error"
-SUGGESTED_FIX="check the script output above for details"
-
-if echo "$STDERR_CONTENT" | grep -q "state\.json not found"; then
-  ROOT_CAUSE="state.json not found — sprint may not be initialized"
-  SUGGESTED_FIX="run: node .cleargate/scripts/init_sprint.mjs <sprint-id> --stories <ids>"
-elif echo "$STDERR_CONTENT" | grep -qi "ENOENT"; then
-  ROOT_CAUSE="missing file (ENOENT)"
-  SUGGESTED_FIX="verify all required files exist at the expected paths"
-elif echo "$STDERR_CONTENT" | grep -qi "EACCES"; then
-  ROOT_CAUSE="permission denied (EACCES)"
-  SUGGESTED_FIX="chmod 755 the target file or directory"
-elif echo "$STDERR_CONTENT" | grep -qi "SyntaxError"; then
-  ROOT_CAUSE="JavaScript syntax error"
-  SUGGESTED_FIX="fix the syntax error in the script; run: node --check <file>"
-elif echo "$STDERR_CONTENT" | grep -qi "Cannot find module"; then
-  ROOT_CAUSE="missing module (import resolution failure)"
-  SUGGESTED_FIX="run npm install in the relevant package directory"
-elif echo "$STDERR_CONTENT" | grep -qi "command not found"; then
-  ROOT_CAUSE="required command not found on PATH"
-  SUGGESTED_FIX="install the missing tool or add it to PATH"
+MAX_BYTES=4096
+TRUNCATION_SUFFIX="... [truncated]"
+
+_truncate_stream() {
+  # Byte-correct truncation: use head -c for POSIX byte-count (not bash ${var:0:N}
+  # which is char-index — wrong for UTF-8 multi-byte input).
+  # Trade-off: output may end with a partial multi-byte char boundary; downstream
+  # Node.js JSON.stringify escapes the partial sequence, producing valid JSON.
+  local file="$1"
+  local file_bytes
+  file_bytes="$(wc -c < "$file")"
+  if [[ $file_bytes -le $MAX_BYTES ]]; then
+    # File fits within budget — emit as-is (no suffix)
+    head -c "$MAX_BYTES" "$file"
+  else
+    # Truncation occurred — emit first MAX_BYTES bytes then TRUNCATION_SUFFIX
+    printf '%s' "$(head -c "$MAX_BYTES" "$file")${TRUNCATION_SUFFIX}"
+  fi
+}
+
+STDOUT_CAPTURED="$(_truncate_stream "$STDOUT_TMP")"
+STDERR_CAPTURED="$(_truncate_stream "$STDERR_TMP")"
+
+# Build filename: <ts>-<hash>.json
+TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+TS_FILE="$(date -u +%Y%m%dT%H%M%SZ)"
+# Hash the full command string (first arg + all args)
+HASH="$(printf '%s' "$*" | shasum -a 1 | cut -c1-12)"
+INCIDENT_FILE="${INCIDENTS_DIR}/${TS_FILE}-${HASH}.json"
+
+# Ensure incident directory exists
+mkdir -p "$INCIDENTS_DIR"
+
+# Collect context
+COMMAND="$1"
+shift
+ARGS_JSON="["
+FIRST=1
+for ARG in "$@"; do
+  if [[ $FIRST -eq 1 ]]; then
+    FIRST=0
+  else
+    ARGS_JSON="${ARGS_JSON},"
+  fi
+  # JSON-escape the arg: replace \ with \\, " with \", newlines with \n
+  ARG_ESCAPED="${ARG//\\/\\\\}"
+  ARG_ESCAPED="${ARG_ESCAPED//\"/\\\"}"
+  ARG_ESCAPED="${ARG_ESCAPED//$'\n'/\\n}"
+  ARGS_JSON="${ARGS_JSON}\"${ARG_ESCAPED}\""
+done
+ARGS_JSON="${ARGS_JSON}]"
+
+CWD="$(pwd)"
+
+# Encode agent_type + work_item_id (null if empty)
+AGENT_TYPE_VAL="${AGENT_TYPE:-}"
+WORK_ITEM_ID_VAL="${WORK_ITEM_ID:-}"
+
+if [[ -z "$AGENT_TYPE_VAL" ]]; then
+  AGENT_TYPE_JSON="null"
+else
+  AGENT_TYPE_JSON="\"${AGENT_TYPE_VAL}\""
 fi
 
+if [[ -z "$WORK_ITEM_ID_VAL" ]]; then
+  WORK_ITEM_ID_JSON="null"
+else
+  WORK_ITEM_ID_JSON="\"${WORK_ITEM_ID_VAL}\""
+fi
+
+# JSON-encode captured streams (escape backslash, double-quote, and newlines)
+_json_str() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\"/\\\"}"
+  s="${s//$'\n'/\\n}"
+  s="${s//$'\r'/\\r}"
+  printf '%s' "$s"
+}
+
+STDOUT_JSON="$(_json_str "$STDOUT_CAPTURED")"
+STDERR_JSON="$(_json_str "$STDERR_CAPTURED")"
+COMMAND_JSON="$(_json_str "$COMMAND")"
+CWD_JSON="$(_json_str "$CWD")"
+
+cat > "$INCIDENT_FILE" <<JSON
 {
-  echo ""
-  echo "## Script Incident"
-  echo "Script:     ${SCRIPT_NAME}"
-  echo "Runner:     ${RUNNER}"
-  echo "Exit code:  ${EXIT_CODE}"
-  echo ""
-  echo "### First 10 lines of stderr:"
-  echo "$STDERR_CONTENT" | head -10
-  echo ""
-  echo "Root cause: ${ROOT_CAUSE}"
-  echo "Suggested fix: ${SUGGESTED_FIX}"
-  echo "## End Incident"
-} >&2
+  "ts": "${TS}",
+  "command": "${COMMAND_JSON}",
+  "args": ${ARGS_JSON},
+  "cwd": "${CWD_JSON}",
+  "exit_code": ${EXIT_CODE},
+  "stdout": "${STDOUT_JSON}",
+  "stderr": "${STDERR_JSON}",
+  "agent_type": ${AGENT_TYPE_JSON},
+  "work_item_id": ${WORK_ITEM_ID_JSON}
+}
+JSON
 
 exit $EXIT_CODE

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

@@ -131,8 +131,73 @@ function atomicWrite(filePath, content) {
   fs.renameSync(tmpFile, filePath);
 }
 
+/**
+ * Read all ledger entries from a token-ledger.jsonl file.
+ * @param {string} ledgerPath
+ * @returns {{ work_item_id: string, agent_type: string, session_id?: string, sprint_id?: string }[]}
+ */
+function readLedgerEntries(ledgerPath) {
+  if (!fs.existsSync(ledgerPath)) return [];
+  const lines = fs.readFileSync(ledgerPath, 'utf8').split('\n').filter(l => l.trim());
+  const entries = [];
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+      if (entry.work_item_id && entry.agent_type) {
+        entries.push({
+          work_item_id: entry.work_item_id,
+          agent_type: entry.agent_type,
+          session_id: entry.session_id ?? '',
+          sprint_id: entry.sprint_id ?? '',
+        });
+      }
+    } catch { /* skip malformed lines */ }
+  }
+  return entries;
+}
+
+/**
+ * Check if a (work_item_id|agent_type) bucket is a session-attribution artifact.
+ *
+ * Session-shared filter (CR-056): When multiple Architect (or other agent) dispatches run
+ * within the same session, the token ledger attributes them all to the same bucket keyed
+ * by the first-merged work_item_id. The canonical example is "CR-045 × architect" in
+ * SPRINT-23/SPRINT-24 — all 17 entries share the SAME session_id 48aa90c9-..., making
+ * them one session mis-attributed as 17 distinct repeats.
+ *
+ * Rule: session-attribution artifact if ALL entries with a known session_id share the
+ * SAME session_id (i.e., exactly 1 distinct session across all entries). When multiple
+ * distinct sessions are present, there is genuine independent repetition.
+ *
+ * Known false-positive class: "CR-045 × architect" — 17 entries, 1 session UUID.
+ *
+ * @param {{ session_id?: string }[]} entries all entries for this bucket (across sprints)
+ * @returns {boolean} true if bucket should be filtered as session-shared artifact
+ */
+function isSessionShared(entries) {
+  if (entries.length < 3) return false;
+  const distinctSessions = new Set(
+    entries.map(e => e.session_id ?? '').filter(s => s !== '')
+  );
+  // If exactly 1 distinct session accounts for all entries, this is a session-attribution artifact
+  return distinctSessions.size === 1;
+}
+
 /**
  * Scan token-ledger.jsonl and FLASHCARD.md for skill creation candidates.
+ *
+ * Heuristic (CR-056 tightened):
+ *   1. Session-shared filter: if ≥2 of ≥3 entries for a bucket share the same
+ *      session_id → skip (token-attribution artifact, not a real recurring pattern).
+ *      Known false-positive class: "CR-045 × architect" from SPRINT-23/SPRINT-24 —
+ *      all 17 entries share session_id 48aa90c9-... (session-shared).
+ *   2. Cross-sprint aggregation: collect entries from the current sprint's ledger PLUS
+ *      prior sprints' ledgers (via CLEARGATE_SPRINT_RUNS_DIR). Count ≥3× total across
+ *      ≥2 distinct sprints.
+ *   3. Cross-sprint dedup: if the candidate's hash already appears in any prior sprint's
+ *      improvement-suggestions.md → surface as seen_in: [...] instead of re-flagging.
+ *   4. Threshold raised to "≥3× across ≥2 distinct sprints AND not session-shared".
+ *
  * Appends or replaces the "## Skill Creation Candidates" section in improvement-suggestions.md.
  * @param {string} sprintId
  * @param {string} sprintDir
@@ -144,24 +209,72 @@ function scanSkillCandidates(sprintId, sprintDir, suggestionsFile) {
     : path.join(REPO_ROOT, '.cleargate', 'FLASHCARD.md');
   const ledgerPath = path.join(sprintDir, 'token-ledger.jsonl');
 
-  // Count repeated (work_item_id, agent_type) tuples from token-ledger.jsonl
-  /** @type {Map<string, number>} */
-  const tupleCounts = new Map();
-  if (fs.existsSync(ledgerPath)) {
-    const lines = fs.readFileSync(ledgerPath, 'utf8').split('\n').filter(l => l.trim());
-    for (const line of lines) {
-      try {
-        const entry = JSON.parse(line);
-        if (entry.work_item_id && entry.agent_type) {
-          const key = `${entry.work_item_id}|${entry.agent_type}`;
-          tupleCounts.set(key, (tupleCounts.get(key) ?? 0) + 1);
-        }
-      } catch { /* skip malformed lines */ }
+  // Resolve sprint-runs root (used for cross-sprint lookback)
+  const sprintRunsDir = process.env.CLEARGATE_SPRINT_RUNS_DIR
+    ? path.resolve(process.env.CLEARGATE_SPRINT_RUNS_DIR)
+    : path.dirname(sprintDir);
+
+  // ── Step 1: collect all ledger entries across current + prior sprints ─────────
+  // Collect from current sprint
+  const currentEntries = readLedgerEntries(ledgerPath);
+
+  // Collect from prior sprints (all sprint dirs except current)
+  const allPriorEntries = [];
+  const priorSuggestionsContents = [];
+  if (fs.existsSync(sprintRunsDir)) {
+    let priorDirs;
+    try {
+      priorDirs = fs.readdirSync(sprintRunsDir)
+        .filter(name => name !== sprintId && !name.startsWith('.'))
+        .map(name => path.join(sprintRunsDir, name))
+        .filter(p => {
+          try { return fs.statSync(p).isDirectory(); } catch { return false; }
+        });
+    } catch { priorDirs = []; }
+
+    for (const priorDir of priorDirs) {
+      const priorLedger = path.join(priorDir, 'token-ledger.jsonl');
+      const entries = readLedgerEntries(priorLedger);
+      allPriorEntries.push(...entries);
+
+      // Collect prior improvement-suggestions.md for cross-sprint dedup
+      const priorSuggFile = path.join(priorDir, 'improvement-suggestions.md');
+      if (fs.existsSync(priorSuggFile)) {
+        try {
+          priorSuggestionsContents.push(fs.readFileSync(priorSuggFile, 'utf8'));
+        } catch { /* skip unreadable */ }
+      }
     }
   }
 
-  // Find tuples repeated ≥3×
-  const repeatedTuples = [...tupleCounts.entries()].filter(([, count]) => count >= 3);
+  // ── Step 2: build cross-sprint bucket map ────────────────────────────────────
+  // Map: key (work_item_id|agent_type) → { entries: [...], sprintIds: Set<string> }
+  /** @type {Map<string, { entries: { session_id?: string, sprint_id?: string }[], sprintIds: Set<string> }>} */
+  const buckets = new Map();
+
+  for (const e of currentEntries) {
+    const key = `${e.work_item_id}|${e.agent_type}`;
+    if (!buckets.has(key)) buckets.set(key, { entries: [], sprintIds: new Set() });
+    const b = buckets.get(key);
+    b.entries.push(e);
+    b.sprintIds.add(sprintId);
+  }
+  for (const e of allPriorEntries) {
+    const key = `${e.work_item_id}|${e.agent_type}`;
+    if (!buckets.has(key)) buckets.set(key, { entries: [], sprintIds: new Set() });
+    const b = buckets.get(key);
+    b.entries.push(e);
+    if (e.sprint_id) b.sprintIds.add(e.sprint_id);
+  }
+
+  // ── Step 3: apply heuristic filters ──────────────────────────────────────────
+  // Threshold: ≥3× total AND ≥2 distinct sprints AND NOT session-shared
+  const repeatedTuples = [...buckets.entries()].filter(([, b]) => {
+    if (b.entries.length < 3) return false;
+    if (b.sprintIds.size < 2) return false;
+    if (isSessionShared(b.entries)) return false;
+    return true;
+  });
 
   // Grep FLASHCARD.md for "also do" patterns
   const alsoDoMatches = [];
@@ -175,21 +288,35 @@ function scanSkillCandidates(sprintId, sprintDir, suggestionsFile) {
     }
   }
 
-  // Read existing suggestions file content
+  // Read existing suggestions file content (current sprint)
   let existingContent = fs.existsSync(suggestionsFile)
     ? fs.readFileSync(suggestionsFile, 'utf8')
     : `# Improvement Suggestions — ${sprintId}\n\nGenerated by \`suggest_improvements.mjs\`. Append-only; IDs are stable.\nVocabulary: Templates | Handoffs | Skills | Process | Tooling\n\n---\n\n`;
 
+  /**
+   * Check if a hash already appears in current sprint's suggestions OR any prior sprint's.
+   * @param {string} hash
+   * @returns {boolean}
+   */
+  function hashAlreadySeen(hash) {
+    const marker = `<!-- hash:${hash} -->`;
+    if (existingContent.includes(marker)) return true;
+    for (const priorContent of priorSuggestionsContents) {
+      if (priorContent.includes(marker)) return true;
+    }
+    return false;
+  }
+
   // Build the candidates
   const candidates = [];
   let candN = 1;
-  for (const [key] of repeatedTuples) {
+  for (const [key, bucket] of repeatedTuples) {
     const [workItemId, agentType] = key.split('|');
     const candId = `CAND-${sprintId}-S${String(candN).padStart(2, '0')}`;
     const hashKey = `skill|${key}`;
     const hash = stableHash(hashKey);
-    if (!existingContent.includes(`<!-- hash:${hash} -->`)) {
-      candidates.push({ candId, hash, workItemId, agentType, source: 'ledger' });
+    if (!hashAlreadySeen(hash)) {
+      candidates.push({ candId, hash, workItemId, agentType, source: 'ledger', sprintIds: bucket.sprintIds });
       candN++;
     }
   }
@@ -197,8 +324,8 @@ function scanSkillCandidates(sprintId, sprintDir, suggestionsFile) {
     const candId = `CAND-${sprintId}-S${String(candN).padStart(2, '0')}`;
     const hashKey = `skill|flashcard|${line.slice(0, 60)}`;
     const hash = stableHash(hashKey);
-    if (!existingContent.includes(`<!-- hash:${hash} -->`)) {
-      candidates.push({ candId, hash, workItemId: null, agentType: null, source: 'flashcard', line });
+    if (!hashAlreadySeen(hash)) {
+      candidates.push({ candId, hash, workItemId: null, agentType: null, source: 'flashcard', line, sprintIds: new Set() });
       candN++;
     }
   }
@@ -220,7 +347,8 @@ function scanSkillCandidates(sprintId, sprintDir, suggestionsFile) {
       sectionLines.push(`<!-- hash:${c.hash} -->`);
       sectionLines.push('');
       if (c.source === 'ledger') {
-        sectionLines.push(`**Pattern detected:** ${c.workItemId} × ${c.agentType} repeated ≥3× in token-ledger`);
+        const sprintList = c.sprintIds ? [...c.sprintIds].sort().join(', ') : sprintId;
+        sectionLines.push(`**Pattern detected:** ${c.workItemId} × ${c.agentType} repeated ≥3× across ≥2 distinct sprints (${sprintList})`);
       } else {
         sectionLines.push(`**Pattern detected:** "also do" pattern in FLASHCARD.md`);
         sectionLines.push(`**Source line:** \`${c.line}\``);

package/dist/templates/cleargate-planning/.cleargate/scripts/test/test_flashcard_gate.sh

@@ -4,7 +4,7 @@
 #
 # Strategy: grep-based. Creates a synthetic dev-report fixture with
 # flashcards_flagged, simulates a mock worktree-creation step, and asserts
-# the gate contract documented in protocol §4 and the agent output-shape
+# the gate contract documented in protocol §18 and the agent output-shape
 # blocks in developer.md + qa.md.
 #
 # Usage: bash .cleargate/scripts/test/test_flashcard_gate.sh
@@ -30,14 +30,14 @@ fail() { echo "FAIL: $1"; FAIL=$((FAIL + 1)); }
 #   And upon approval each card is appended to .cleargate/FLASHCARD.md
 #   And only then does worktree creation proceed
 #
-# This script validates the contract (protocol §4 + output-shape fields)
+# This script validates the contract (protocol §18 + output-shape fields)
 # that makes the scenario enforceable. The gate logic itself is orchestrator-
 # out-of-band (v1: informational; v2: mandatory). The test therefore checks:
 #   (a) developer.md output-shape contains flashcards_flagged field
 #   (b) qa.md output-shape contains flashcards_flagged field
-#   (c) protocol.md §4 exists with the correct heading
-#   (d) §4 specifies the approve/reject processing rule
-#   (e) §4 specifies the worktree creation gate
+#   (c) protocol.md §18 exists with the correct heading
+#   (d) §18 specifies the approve/reject processing rule
+#   (e) §18 specifies the worktree creation gate
 #   (f) live vs mirror diff is empty for all three files
 
 DEV_MD="$REPO_ROOT/.claude/agents/developer.md"
@@ -62,25 +62,25 @@ else
   fail "qa.md missing flashcards_flagged field in output-shape"
 fi
 
-# (c) protocol.md §4 heading exists
+# (c) protocol.md §18 heading exists
 if grep -q "^## 18. Immediate Flashcard Gate (v2)" "$PROTOCOL_MD"; then
   pass "protocol.md contains ## 18. Immediate Flashcard Gate (v2)"
 else
   fail "protocol.md missing ## 18. Immediate Flashcard Gate (v2)"
 fi
 
-# (d) §4 specifies approve + reject processing
+# (d) §18 specifies approve + reject processing
 if grep -q "Approve" "$PROTOCOL_MD" && grep -q "Reject" "$PROTOCOL_MD"; then
-  pass "protocol §4 documents Approve/Reject processing rule"
+  pass "protocol §18 documents Approve/Reject processing rule"
 else
-  fail "protocol §4 missing Approve/Reject processing rule"
+  fail "protocol §18 missing Approve/Reject processing rule"
 fi
 
-# (e) §4 specifies the worktree creation gate
+# (e) §18 specifies the worktree creation gate
 if grep -q "Worktree creation gate\|worktree creation gate\|MUST NOT.*worktree\|worktree.*MUST NOT" "$PROTOCOL_MD"; then
-  pass "protocol §4 documents worktree creation gate"
+  pass "protocol §18 documents worktree creation gate"
 else
-  fail "protocol §4 missing worktree creation gate rule"
+  fail "protocol §18 missing worktree creation gate rule"
 fi
 
 # (f) qa.md says QA list is additive to Developer's
@@ -90,18 +90,18 @@ else
   fail "qa.md missing note that flashcards_flagged is additive"
 fi
 
-# (g) developer.md references protocol §4
-if grep -q "protocol §4\|§4" "$DEV_MD"; then
-  pass "developer.md references protocol §4"
+# (g) developer.md references protocol §18
+if grep -q "protocol §18\|§18" "$DEV_MD"; then
+  pass "developer.md references protocol §18"
 else
-  fail "developer.md does not reference protocol §4"
+  fail "developer.md does not reference protocol §18"
 fi
 
-# (h) qa.md references protocol §4
-if grep -q "protocol §4\|§4" "$QA_MD"; then
-  pass "qa.md references protocol §4"
+# (h) qa.md references protocol §18
+if grep -q "protocol §18\|§18" "$QA_MD"; then
+  pass "qa.md references protocol §18"
 else
-  fail "qa.md does not reference protocol §4"
+  fail "qa.md does not reference protocol §18"
 fi
 
 # (i) three-surface diff: live developer.md vs mirror