cleargate 0.8.2 → 0.10.0

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

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * sprint_trends.mjs — Sprint trends stub (full implementation deferred to CR-027)
+ *
+ * Usage: node sprint_trends.mjs <sprint-id>
+ *
+ * Counts sibling Completed sprints and appends a placeholder Trends section
+ * to the current sprint's improvement-suggestions.md.
+ *
+ * Test seams:
+ *   CLEARGATE_SPRINT_DIR=<path>      — override sprint dir resolution
+ *   CLEARGATE_SPRINT_RUNS_DIR=<path> — override .cleargate/sprint-runs/ root for sibling counting
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+function main() {
+  const sprintId = process.argv[2];
+  if (!sprintId) {
+    process.stderr.write('Usage: node sprint_trends.mjs <sprint-id>\n');
+    process.exit(2);
+  }
+
+  const sprintDir = process.env.CLEARGATE_SPRINT_DIR
+    ? path.resolve(process.env.CLEARGATE_SPRINT_DIR)
+    : path.join(REPO_ROOT, '.cleargate', 'sprint-runs', sprintId);
+
+  const sprintRunsDir = process.env.CLEARGATE_SPRINT_RUNS_DIR
+    ? path.resolve(process.env.CLEARGATE_SPRINT_RUNS_DIR)
+    : path.dirname(sprintDir);
+
+  // Count sibling sprint dirs whose state.json has sprint_status === 'Completed'
+  let completedCount = 0;
+  if (fs.existsSync(sprintRunsDir)) {
+    for (const entry of fs.readdirSync(sprintRunsDir)) {
+      if (entry === path.basename(sprintDir)) continue;
+      const siblingState = path.join(sprintRunsDir, entry, 'state.json');
+      if (!fs.existsSync(siblingState)) continue;
+      try {
+        const state = JSON.parse(fs.readFileSync(siblingState, 'utf8'));
+        if (state.sprint_status === 'Completed') completedCount++;
+      } catch { /* skip malformed state.json */ }
+    }
+  }
+
+  const suggestionsFile = path.join(sprintDir, 'improvement-suggestions.md');
+  const trendsSection = `\n## Trends\n\nTrends: ${completedCount} closed sprints visible — full analysis deferred to CR-027.\n`;
+
+  if (!fs.existsSync(suggestionsFile)) {
+    const header = `# Improvement Suggestions — ${sprintId}\n\n`;
+    const tmpFile = `${suggestionsFile}.tmp.${process.pid}`;
+    fs.writeFileSync(tmpFile, header + trendsSection, 'utf8');
+    fs.renameSync(tmpFile, suggestionsFile);
+  } else {
+    const existing = fs.readFileSync(suggestionsFile, 'utf8');
+    const tmpFile = `${suggestionsFile}.tmp.${process.pid}`;
+    fs.writeFileSync(tmpFile, existing.trimEnd() + trendsSection, 'utf8');
+    fs.renameSync(tmpFile, suggestionsFile);
+  }
+
+  process.stdout.write(
+    `sprint_trends: stub — full implementation deferred to CR-027 (counted ${completedCount} closed sprints).\n`
+  );
+}
+
+main();

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

@@ -3,6 +3,8 @@
  * suggest_improvements.mjs — Generate stable improvement suggestions from REPORT.md
  *
  * Usage: node suggest_improvements.mjs <sprint-id>
+ *        node suggest_improvements.mjs <sprint-id> --skill-candidates
+ *        node suggest_improvements.mjs <sprint-id> --flashcard-cleanup
  *
  * Reads:
  *   - .cleargate/sprint-runs/<id>/REPORT.md §5 Framework Self-Assessment tables
@@ -10,7 +12,9 @@
  *
  * Emits:
  *   - .cleargate/sprint-runs/<id>/improvement-suggestions.md
- *     with stable SUG-<sprint>-<n> IDs
+ *     with stable SUG-<sprint>-<n> IDs (default mode)
+ *     or appends ## Skill Creation Candidates (--skill-candidates mode)
+ *     or appends ## FLASHCARD Cleanup Candidates (--flashcard-cleanup mode)
  *
  * Append-only idempotency (R5):
  *   - IDs are derived from a stable hash of (category, title) tuple
@@ -19,12 +23,18 @@
  *
  * Note: "section" as used in §5 table extraction refers to the Framework Self-Assessment
  * subsections: Templates, Handoffs, Skills, Process, Tooling.
+ *
+ * Test seams (CR-022 M6):
+ *   CLEARGATE_FLASHCARD_PATH=<path>   — override .cleargate/FLASHCARD.md path
+ *   CLEARGATE_FLASHCARD_LOOKBACK=<N>  — override 3-sprint lookback window (default 3)
+ *   CLEARGATE_SPRINT_RUNS_DIR=<path>  — override .cleargate/sprint-runs/ root for sibling lookups
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
+import { reportFilename } from './lib/report-filename.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
@@ -91,15 +101,20 @@ function parseSelfAssessment(content) {
 }
 
 /**
- * Parse existing improvement-suggestions.md to extract already-captured SUG IDs.
+ * Parse existing improvement-suggestions.md to extract already-captured SUG and CAND IDs.
  * @param {string} content
- * @returns {Set<string>} Set of SUG IDs
+ * @returns {Set<string>} Set of SUG/CAND IDs
  */
 function parseExistingIds(content) {
   const ids = new Set();
-  // Match SUG-<sprint>-<n> patterns
-  const matches = content.matchAll(/SUG-[A-Z0-9-]+-\d+/g);
-  for (const m of matches) {
+  // Match SUG-<sprint>-<n> patterns (default mode)
+  const sugMatches = content.matchAll(/SUG-[A-Z0-9-]+-\d+/g);
+  for (const m of sugMatches) {
+    ids.add(m[0]);
+  }
+  // Match CAND-<sprint>-[SF]<n> patterns (--skill-candidates / --flashcard-cleanup modes)
+  const candMatches = content.matchAll(/CAND-[A-Z0-9-]+-[SF]\d+/g);
+  for (const m of candMatches) {
     ids.add(m[0]);
   }
   return ids;
@@ -116,14 +131,328 @@ function atomicWrite(filePath, content) {
   fs.renameSync(tmpFile, filePath);
 }
 
+/**
+ * Scan token-ledger.jsonl and FLASHCARD.md for skill creation candidates.
+ * Appends or replaces the "## Skill Creation Candidates" section in improvement-suggestions.md.
+ * @param {string} sprintId
+ * @param {string} sprintDir
+ * @param {string} suggestionsFile
+ */
+function scanSkillCandidates(sprintId, sprintDir, suggestionsFile) {
+  const flashcardPath = process.env.CLEARGATE_FLASHCARD_PATH
+    ? path.resolve(process.env.CLEARGATE_FLASHCARD_PATH)
+    : 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 */ }
+    }
+  }
+
+  // Find tuples repeated ≥3×
+  const repeatedTuples = [...tupleCounts.entries()].filter(([, count]) => count >= 3);
+
+  // Grep FLASHCARD.md for "also do" patterns
+  const alsoDoMatches = [];
+  if (fs.existsSync(flashcardPath)) {
+    const fcContent = fs.readFileSync(flashcardPath, 'utf8');
+    const lines = fcContent.split('\n');
+    for (const line of lines) {
+      if (/remember to also|also do X|also need to/i.test(line)) {
+        alsoDoMatches.push(line.trim());
+      }
+    }
+  }
+
+  // Read existing suggestions file content
+  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`;
+
+  // Build the candidates
+  const candidates = [];
+  let candN = 1;
+  for (const [key] 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' });
+      candN++;
+    }
+  }
+  for (const line of alsoDoMatches) {
+    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 });
+      candN++;
+    }
+  }
+
+  // Build the section content
+  const sectionLines = [
+    '## Skill Creation Candidates',
+    '',
+    '<!-- generated-by: suggest_improvements.mjs --skill-candidates -->',
+    '',
+  ];
+
+  if (candidates.length === 0) {
+    sectionLines.push('_No candidates detected this sprint._');
+    sectionLines.push('');
+  } else {
+    for (const c of candidates) {
+      sectionLines.push(`### ${c.candId}: ${c.source === 'ledger' ? `${c.workItemId} × ${c.agentType}` : 'flashcard pattern'}`);
+      sectionLines.push(`<!-- hash:${c.hash} -->`);
+      sectionLines.push('');
+      if (c.source === 'ledger') {
+        sectionLines.push(`**Pattern detected:** ${c.workItemId} × ${c.agentType} repeated ≥3× in token-ledger`);
+      } else {
+        sectionLines.push(`**Pattern detected:** "also do" pattern in FLASHCARD.md`);
+        sectionLines.push(`**Source line:** \`${c.line}\``);
+      }
+      sectionLines.push(`**Proposed skill:** \`.claude/skills/<slug>/SKILL.md\``);
+      sectionLines.push('');
+      sectionLines.push('---');
+      sectionLines.push('');
+    }
+  }
+
+  const sectionContent = sectionLines.join('\n');
+  // Anchored heading regex — strict match, no trailing text
+  const headingRe = /^## Skill Creation Candidates$/m;
+
+  let finalContent;
+  if (headingRe.test(existingContent)) {
+    // Replace existing section (splice out old, append new)
+    const nextHeadingRe = /^## /m;
+    const headingIdx = existingContent.search(headingRe);
+    const afterHeading = existingContent.slice(headingIdx + existingContent.match(headingRe)[0].length);
+    const nextMatch = afterHeading.search(/^## /m);
+    if (nextMatch === -1) {
+      finalContent = existingContent.slice(0, headingIdx).trimEnd() + '\n\n' + sectionContent;
+    } else {
+      finalContent = existingContent.slice(0, headingIdx).trimEnd() + '\n\n' + sectionContent + '\n' + afterHeading.slice(nextMatch);
+    }
+    void nextHeadingRe;
+  } else {
+    finalContent = existingContent.trimEnd() + '\n\n' + sectionContent;
+  }
+
+  atomicWrite(suggestionsFile, finalContent);
+  process.stdout.write(`suggest_improvements: skill-candidates section written to ${suggestionsFile}\n`);
+}
+
+/**
+ * Scan FLASHCARD.md for cleanup candidates (stale / superseded / resolved).
+ * Appends or replaces the "## FLASHCARD Cleanup Candidates" section in improvement-suggestions.md.
+ * @param {string} sprintId
+ * @param {string} sprintDir
+ * @param {string} suggestionsFile
+ */
+function scanFlashcardCleanup(sprintId, sprintDir, suggestionsFile) {
+  const flashcardPath = process.env.CLEARGATE_FLASHCARD_PATH
+    ? path.resolve(process.env.CLEARGATE_FLASHCARD_PATH)
+    : path.join(REPO_ROOT, '.cleargate', 'FLASHCARD.md');
+
+  const lookback = parseInt(process.env.CLEARGATE_FLASHCARD_LOOKBACK ?? '3', 10);
+  const sprintRunsDir = process.env.CLEARGATE_SPRINT_RUNS_DIR
+    ? path.resolve(process.env.CLEARGATE_SPRINT_RUNS_DIR)
+    : path.dirname(sprintDir);
+
+  if (!fs.existsSync(flashcardPath)) {
+    process.stderr.write(`suggest_improvements --flashcard-cleanup: FLASHCARD.md not found at ${flashcardPath}, skipping\n`);
+    return;
+  }
+
+  const fcContent = fs.readFileSync(flashcardPath, 'utf8');
+  // Parse entries: YYYY-MM-DD · #tag1 #tag2 · lesson
+  const entryRe = /^(\d{4}-\d{2}-\d{2})\s+·\s+(.*?)\s+·\s+(.+)$/;
+  const entries = fcContent.split('\n').filter(l => entryRe.test(l.trim()));
+
+  // Determine lookback sprint dirs (numerical extraction from sprintId)
+  const numMatch = sprintId.match(/(\d+)$/);
+  const currentNum = numMatch ? parseInt(numMatch[1], 10) : null;
+  const sprintPrefix = numMatch ? sprintId.replace(/\d+$/, '') : null;
+
+  // Collect prior sprint REPORT.md content for "resolved" detection
+  const priorReportContent = [];
+  if (currentNum !== null && sprintPrefix !== null) {
+    for (let i = 1; i <= lookback; i++) {
+      const priorId = `${sprintPrefix}${currentNum - i}`;
+      const priorDir = path.join(sprintRunsDir, priorId);
+      if (!fs.existsSync(priorDir)) continue;
+      try {
+        const rFile = reportFilename(priorDir, priorId, { forRead: true });
+        if (fs.existsSync(rFile)) {
+          priorReportContent.push(fs.readFileSync(rFile, 'utf8'));
+        }
+      } catch { /* skip missing */ }
+    }
+  }
+
+  // Collect prior sprint dirs for stale detection
+  const priorSprintDirs = [];
+  if (currentNum !== null && sprintPrefix !== null) {
+    for (let i = 1; i <= lookback; i++) {
+      const priorId = `${sprintPrefix}${currentNum - i}`;
+      const priorDir = path.join(sprintRunsDir, priorId);
+      if (fs.existsSync(priorDir)) priorSprintDirs.push(priorDir);
+    }
+  }
+
+  /** @type {{ entry: string, date: string, tags: string, lesson: string, category: 'stale'|'superseded'|'resolved', reason: string }[]} */
+  const candidates = [];
+  const processedHashes = new Set();
+
+  for (const rawEntry of entries) {
+    const m = rawEntry.trim().match(entryRe);
+    if (!m) continue;
+    const [, date, tags, lesson] = m;
+    const entry = rawEntry.trim();
+    const hashKey = `flashcard|${entry.slice(0, 80)}`;
+    const hash = stableHash(hashKey);
+    if (processedHashes.has(hash)) continue;
+    processedHashes.add(hash);
+
+    // Extract first keyword from lesson (first word-run, stripping punctuation)
+    const keyword = lesson.split(/\s+/)[0].replace(/[^a-zA-Z0-9_-]/g, '').toLowerCase();
+    if (!keyword) continue;
+
+    // Check "resolved": keyword appears in §6 Tooling "Resolved" of a prior REPORT.md
+    let resolved = false;
+    for (const rc of priorReportContent) {
+      const resolvedSection = rc.match(/##\s*§6[^\n]*\n([\s\S]*?)(?=##\s*§|$)/);
+      if (resolvedSection && resolvedSection[1].toLowerCase().includes(keyword)) {
+        resolved = true;
+        break;
+      }
+    }
+    if (resolved) {
+      candidates.push({ entry, date, tags, lesson, category: 'resolved', reason: 'keyword found in a prior §6 Tooling section' });
+      continue;
+    }
+
+    // Check "stale": zero grep hits for keyword across prior sprint dirs
+    if (priorSprintDirs.length > 0) {
+      let hitCount = 0;
+      for (const priorDir of priorSprintDirs) {
+        try {
+          const files = fs.readdirSync(priorDir);
+          for (const f of files) {
+            const fPath = path.join(priorDir, f);
+            if (fs.statSync(fPath).isFile()) {
+              const content = fs.readFileSync(fPath, 'utf8');
+              if (content.toLowerCase().includes(keyword)) { hitCount++; break; }
+            }
+          }
+        } catch { /* skip unreadable dirs */ }
+      }
+      if (hitCount === 0) {
+        candidates.push({ entry, date, tags, lesson, category: 'stale', reason: `stale: zero grep hits across last ${priorSprintDirs.length} sprint dir(s)` });
+        continue;
+      }
+    }
+  }
+
+  // Read existing suggestions file content
+  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`;
+
+  // Build section
+  const sectionLines = [
+    '## FLASHCARD Cleanup Candidates',
+    '',
+    '<!-- generated-by: suggest_improvements.mjs --flashcard-cleanup -->',
+    '',
+  ];
+
+  // Filter out already-captured candidates
+  const newCandidates = candidates.filter(c => {
+    const hash = stableHash(`flashcard|${c.entry.slice(0, 80)}`);
+    return !existingContent.includes(`<!-- hash:${hash} -->`);
+  });
+
+  if (newCandidates.length === 0) {
+    sectionLines.push('_No candidates detected this sprint._');
+    sectionLines.push('');
+  } else {
+    newCandidates.forEach((c, i) => {
+      const candId = `CAND-${sprintId}-F${String(i + 1).padStart(2, '0')}`;
+      const hash = stableHash(`flashcard|${c.entry.slice(0, 80)}`);
+      sectionLines.push(`### ${candId}: ${c.lesson.slice(0, 60)}`);
+      sectionLines.push(`<!-- hash:${hash} -->`);
+      sectionLines.push('');
+      sectionLines.push(`**Category:** ${c.category}`);
+      sectionLines.push(`**Reason:** ${c.reason}`);
+      sectionLines.push(`**Original entry:** \`${c.entry}\``);
+      sectionLines.push('**Suggested action:** approve to remove via `cleargate flashcard prune` (run /improve)');
+      sectionLines.push('');
+      sectionLines.push('---');
+      sectionLines.push('');
+    });
+  }
+
+  const sectionContent = sectionLines.join('\n');
+  // Anchored heading regex — strict match, no trailing text
+  const headingRe = /^## FLASHCARD Cleanup Candidates$/m;
+
+  let finalContent;
+  if (headingRe.test(existingContent)) {
+    const headingIdx = existingContent.search(headingRe);
+    const afterHeading = existingContent.slice(headingIdx + existingContent.match(headingRe)[0].length);
+    const nextMatch = afterHeading.search(/^## /m);
+    if (nextMatch === -1) {
+      finalContent = existingContent.slice(0, headingIdx).trimEnd() + '\n\n' + sectionContent;
+    } else {
+      finalContent = existingContent.slice(0, headingIdx).trimEnd() + '\n\n' + sectionContent + '\n' + afterHeading.slice(nextMatch);
+    }
+  } else {
+    finalContent = existingContent.trimEnd() + '\n\n' + sectionContent;
+  }
+
+  atomicWrite(suggestionsFile, finalContent);
+  process.stdout.write(`suggest_improvements: flashcard-cleanup section written to ${suggestionsFile}\n`);
+}
+
 function main() {
   const args = process.argv.slice(2);
   if (args.length < 1) {
-    process.stderr.write('Usage: node suggest_improvements.mjs <sprint-id>\n');
+    process.stderr.write('Usage: node suggest_improvements.mjs <sprint-id> [--skill-candidates | --flashcard-cleanup]\n');
+    process.exit(2);
+  }
+
+  // Flag-aware parse: detect flags first, then extract sprintId from positional args.
+  // Sprint IDs match ^SPRINT-\d+$ so they never start with '--'; no collision possible.
+  const skillCandidatesMode = args.includes('--skill-candidates');
+  const flashcardCleanupMode = args.includes('--flashcard-cleanup');
+
+  if (skillCandidatesMode && flashcardCleanupMode) {
+    process.stderr.write('Error: --skill-candidates and --flashcard-cleanup are mutually exclusive\n');
+    process.exit(2);
+  }
+
+  const sprintId = args.find(a => !a.startsWith('--'));
+  if (!sprintId) {
+    process.stderr.write('Usage: node suggest_improvements.mjs <sprint-id> [--skill-candidates | --flashcard-cleanup]\n');
     process.exit(2);
   }
 
-  const sprintId = args[0];
   const sprintDir = process.env.CLEARGATE_SPRINT_DIR
     ? path.resolve(process.env.CLEARGATE_SPRINT_DIR)
     : path.join(REPO_ROOT, '.cleargate', 'sprint-runs', sprintId);
@@ -133,13 +462,26 @@ function main() {
     process.exit(1);
   }
 
-  const reportFile = path.join(sprintDir, 'REPORT.md');
+  const reportFile = reportFilename(sprintDir, sprintId, { forRead: true });
   const suggestionsFile = path.join(sprintDir, 'improvement-suggestions.md');
 
-  if (!fs.existsSync(reportFile)) {
-    process.stderr.write(`Error: REPORT.md not found at ${reportFile}\n`);
-    process.stderr.write('Run the Reporter agent first to generate the report.\n');
-    process.exit(1);
+  // Default mode requires REPORT.md; flag-driven modes do not.
+  if (!skillCandidatesMode && !flashcardCleanupMode) {
+    if (!fs.existsSync(reportFile)) {
+      process.stderr.write(`Error: report file not found at ${reportFile}\n`);
+      process.stderr.write('Run the Reporter agent first to generate the report.\n');
+      process.exit(1);
+    }
+  }
+
+  // Route flag-driven modes before default processing
+  if (skillCandidatesMode) {
+    scanSkillCandidates(sprintId, sprintDir, suggestionsFile);
+    return;
+  }
+  if (flashcardCleanupMode) {
+    scanFlashcardCleanup(sprintId, sprintDir, suggestionsFile);
+    return;
   }
 
   const reportContent = fs.readFileSync(reportFile, 'utf8');

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 §18 and the agent output-shape
+# the gate contract documented in protocol §4 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 §18 + output-shape fields)
+# This script validates the contract (protocol §4 + 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 §18 exists with the correct heading
-#   (d) §18 specifies the approve/reject processing rule
-#   (e) §18 specifies the worktree creation gate
+#   (c) protocol.md §4 exists with the correct heading
+#   (d) §4 specifies the approve/reject processing rule
+#   (e) §4 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 §18 heading exists
+# (c) protocol.md §4 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) §18 specifies approve + reject processing
+# (d) §4 specifies approve + reject processing
 if grep -q "Approve" "$PROTOCOL_MD" && grep -q "Reject" "$PROTOCOL_MD"; then
-  pass "protocol §18 documents Approve/Reject processing rule"
+  pass "protocol §4 documents Approve/Reject processing rule"
 else
-  fail "protocol §18 missing Approve/Reject processing rule"
+  fail "protocol §4 missing Approve/Reject processing rule"
 fi
 
-# (e) §18 specifies the worktree creation gate
+# (e) §4 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 §18 documents worktree creation gate"
+  pass "protocol §4 documents worktree creation gate"
 else
-  fail "protocol §18 missing worktree creation gate rule"
+  fail "protocol §4 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 §18
-if grep -q "protocol §18\|§18" "$DEV_MD"; then
-  pass "developer.md references protocol §18"
+# (g) developer.md references protocol §4
+if grep -q "protocol §4\|§4" "$DEV_MD"; then
+  pass "developer.md references protocol §4"
 else
-  fail "developer.md does not reference protocol §18"
+  fail "developer.md does not reference protocol §4"
 fi
 
-# (h) qa.md references protocol §18
-if grep -q "protocol §18\|§18" "$QA_MD"; then
-  pass "qa.md references protocol §18"
+# (h) qa.md references protocol §4
+if grep -q "protocol §4\|§4" "$QA_MD"; then
+  pass "qa.md references protocol §4"
 else
-  fail "qa.md does not reference protocol §18"
+  fail "qa.md does not reference protocol §4"
 fi
 
 # (i) three-surface diff: live developer.md vs mirror