ccgx-workflow 2.4.1 → 2.5.0

package/templates/hooks/ccg-stop-gate.cjs

@@ -35,6 +35,18 @@ const ACTIVE_STATUSES = new Set(['queued', 'running']);
 const MAX_STATE_FILE_BYTES = 64 * 1024;
 const MAX_REPORT_JOBS = 5; // truncate to keep additionalContext tight
 
+// ── Quality soft-feedback (P0-1) ────────────────────────────────────────
+// On Stop we additionally surface unconverged quality state so the model
+// does not silently end the turn mid-Ralph-loop / mid-UAT. Soft feedback
+// only — same warn-don't-block semantics as the background-task scan.
+const FIX_LOG_RELATIVE = path.join('.context', 'fix-log.jsonl');
+const UAT_SUBDIR = path.join('.context', 'uat');
+const MAX_FIXLOG_TAIL_BYTES = 16 * 1024; // tail-read only (~130 JSONL lines)
+const MAX_UAT_FRONTMATTER_BYTES = 8 * 1024; // head-read per UAT.md
+const MAX_UAT_DIRS = 10; // bounded scan of .context/uat/<task-id>/
+const QUALITY_FRESHNESS_MS = 24 * 60 * 60 * 1000; // stale records stop nagging after 24h
+const MAX_REPORT_QUALITY = 5;
+
 function readInput() {
   let raw = '';
   try {
@@ -91,6 +103,173 @@ function scanCcgJobs(cwd) {
   return active;
 }
 
+// ── Quality soft-feedback scanners (P0-1) ───────────────────────────────
+
+// Bounded tail read: never touch more than `maxBytes` no matter how big the
+// file is. When the read starts mid-file, the first (partial) line is dropped.
+// Any failure → null.
+function readFileTail(filePath, maxBytes) {
+  let fd = null;
+  try {
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile() || stat.size === 0) return null;
+    const readBytes = Math.min(stat.size, maxBytes);
+    const position = Math.max(0, stat.size - readBytes);
+    fd = fs.openSync(filePath, 'r');
+    const buf = Buffer.alloc(readBytes);
+    const bytesRead = fs.readSync(fd, buf, 0, readBytes, position);
+    let text = buf.toString('utf-8', 0, bytesRead);
+    if (position > 0) {
+      const nl = text.indexOf('\n');
+      text = nl === -1 ? '' : text.slice(nl + 1);
+    }
+    return text;
+  }
+  catch {
+    return null;
+  }
+  finally {
+    if (fd !== null) {
+      try { fs.closeSync(fd); }
+      catch { /* ignore */ }
+    }
+  }
+}
+
+// Bounded head read (for UAT.md frontmatter). Any failure → null.
+function readFileHead(filePath, maxBytes) {
+  let fd = null;
+  try {
+    fd = fs.openSync(filePath, 'r');
+    const buf = Buffer.alloc(maxBytes);
+    const bytesRead = fs.readSync(fd, buf, 0, maxBytes, 0);
+    return buf.toString('utf-8', 0, bytesRead);
+  }
+  catch {
+    return null;
+  }
+  finally {
+    if (fd !== null) {
+      try { fs.closeSync(fd); }
+      catch { /* ignore */ }
+    }
+  }
+}
+
+// Scan .context/fix-log.jsonl (RFC-8 schema, consumed read-only) for an
+// unconverged Ralph loop: the highest-round 'review' entry still has
+// critical > 0 and is fresher than QUALITY_FRESHNESS_MS. Returns
+// { round, critical, warning, info, ts, lastFixStatus } or null.
+// Parsing mirrors readFixLog tolerance: bad lines are skipped; duplicate
+// rounds → last entry wins (same as convergeHistoryFromLog).
+function scanFixLogUnresolved(cwd, nowMs) {
+  const tail = readFileTail(path.join(cwd, FIX_LOG_RELATIVE), MAX_FIXLOG_TAIL_BYTES);
+  if (tail === null) return null;
+  const reviewByRound = new Map();
+  const fixStatusByRound = new Map();
+  for (const line of tail.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let entry;
+    try {
+      entry = JSON.parse(trimmed);
+    }
+    catch {
+      continue; // malformed line — skip, never throw
+    }
+    if (!entry || typeof entry !== 'object') continue;
+    if (typeof entry.round !== 'number' || !Number.isInteger(entry.round) || entry.round < 1) continue;
+    if (entry.kind === 'review') {
+      const f = entry.findings;
+      if (!f || typeof f !== 'object'
+        || typeof f.critical !== 'number' || typeof f.warning !== 'number' || typeof f.info !== 'number') {
+        continue;
+      }
+      reviewByRound.set(entry.round, {
+        round: entry.round,
+        critical: f.critical,
+        warning: f.warning,
+        info: f.info,
+        ts: typeof entry.ts === 'string' ? entry.ts : '',
+      });
+    }
+    else if (entry.kind === 'fix' && typeof entry.status === 'string') {
+      fixStatusByRound.set(entry.round, entry.status);
+    }
+  }
+  if (reviewByRound.size === 0) return null;
+  let maxRound = 0;
+  for (const r of reviewByRound.keys()) {
+    if (r > maxRound) maxRound = r;
+  }
+  const last = reviewByRound.get(maxRound);
+  // critical === 0 means converged for soft-feedback purposes (Warnings do
+  // not nag — matches the --fix pass-through semantics).
+  if (!(last.critical > 0)) return null;
+  const tsMs = Date.parse(last.ts);
+  if (!Number.isFinite(tsMs) || nowMs - tsMs >= QUALITY_FRESHNESS_MS) return null;
+  return {
+    round: last.round,
+    critical: last.critical,
+    warning: last.warning,
+    info: last.info,
+    ts: last.ts,
+    lastFixStatus: fixStatusByRound.has(maxRound) ? fixStatusByRound.get(maxRound) : null,
+  };
+}
+
+// Scan .context/uat/<task-id>/UAT.md frontmatter (uat-session.ts schema,
+// consumed read-only via regex — fields anchored: status / severity /
+// symptom) for open gaps. Freshness uses file mtime (gap entries carry no
+// timestamp). Returns [{ taskId, openCount, topSeverity, sampleSymptom }].
+function scanUatGaps(cwd, nowMs) {
+  const uatDir = path.join(cwd, UAT_SUBDIR);
+  let entries;
+  try {
+    entries = fs.readdirSync(uatDir, { withFileTypes: true });
+  }
+  catch {
+    return [];
+  }
+  const severityRank = { critical: 4, high: 3, medium: 2, low: 1 };
+  const results = [];
+  const dirs = entries.filter((e) => e.isDirectory()).slice(0, MAX_UAT_DIRS);
+  for (const dir of dirs) {
+    const uatFile = path.join(uatDir, dir.name, 'UAT.md');
+    let stat;
+    try {
+      stat = fs.statSync(uatFile);
+    }
+    catch {
+      continue;
+    }
+    if (!stat.isFile()) continue;
+    if (nowMs - stat.mtimeMs >= QUALITY_FRESHNESS_MS) continue;
+    const head = readFileHead(uatFile, MAX_UAT_FRONTMATTER_BYTES);
+    if (head === null) continue;
+    const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(head);
+    if (!fm) continue;
+    const gapLines = fm[1].match(/-\s*\{[^}]*status:\s*open[^}]*\}/g) || [];
+    if (gapLines.length === 0) continue;
+    let topSeverity = 'low';
+    let sampleSymptom = null;
+    for (const g of gapLines) {
+      const sev = /severity:\s*(critical|high|medium|low)/.exec(g);
+      const sevName = sev ? sev[1] : 'low';
+      if (severityRank[sevName] > severityRank[topSeverity]) topSeverity = sevName;
+      if (sampleSymptom === null) {
+        const sym = /symptom:\s*(?:"([^"]{1,80})|([^,}]{1,80}))/.exec(g);
+        if (sym) {
+          const text = (sym[1] || sym[2] || '').trim().slice(0, 80);
+          if (text) sampleSymptom = text;
+        }
+      }
+    }
+    results.push({ taskId: dir.name, openCount: gapLines.length, topSeverity, sampleSymptom });
+  }
+  return results;
+}
+
 // Normalize harness-supplied background_tasks (field shape added in CC 2.1.145).
 // Shape is best-effort: we accept either an array of strings (task ids) or an
 // array of objects with at minimum a `task_id` or `id` field.
@@ -133,21 +312,50 @@ function mergeTasks(ccgJobs, harnessTasks) {
   return merged;
 }
 
-function composeWarning(eventName, tasks) {
-  const limited = tasks.slice(0, MAX_REPORT_JOBS);
-  const omitted = tasks.length - limited.length;
+// Third param is optional ({ fixLog, uatGaps }) — legacy 2-arg calls keep
+// the exact pre-P0-1 output.
+function composeWarning(eventName, tasks, quality) {
+  const q = quality || {};
+  const fixLog = q.fixLog || null;
+  const uatGaps = Array.isArray(q.uatGaps) ? q.uatGaps : [];
   const lines = ['<ccg-stop-gate>'];
-  lines.push(`⚠️ ${tasks.length} background task(s) still active at ${eventName}.`);
-  lines.push('Do not declare the user-facing work "complete" until these settle.');
-  lines.push('Options: tell the user "background X is still running, check /ccg:status <id>", or wait and re-summarize.');
-  lines.push('');
-  for (const t of limited) {
-    const phase = t.phase ? ` phase=${t.phase}` : '';
-    const summary = t.summary ? ` — ${t.summary}` : '';
-    lines.push(`- ${t.jobId} [${t.status}, ${t.sourcedFrom}]${phase}${summary}`);
-  }
-  if (omitted > 0) {
-    lines.push(`- ... ${omitted} more (truncated)`);
+  if (tasks.length > 0) {
+    const limited = tasks.slice(0, MAX_REPORT_JOBS);
+    const omitted = tasks.length - limited.length;
+    lines.push(`⚠️ ${tasks.length} background task(s) still active at ${eventName}.`);
+    lines.push('Do not declare the user-facing work "complete" until these settle.');
+    lines.push('Options: tell the user "background X is still running, check /ccg:status <id>", or wait and re-summarize.');
+    lines.push('');
+    for (const t of limited) {
+      const phase = t.phase ? ` phase=${t.phase}` : '';
+      const summary = t.summary ? ` — ${t.summary}` : '';
+      lines.push(`- ${t.jobId} [${t.status}, ${t.sourcedFrom}]${phase}${summary}`);
+    }
+    if (omitted > 0) {
+      lines.push(`- ... ${omitted} more (truncated)`);
+    }
+  }
+  if (fixLog || uatGaps.length > 0) {
+    if (tasks.length > 0) lines.push('');
+    lines.push('🔁 Unconverged quality issues (soft feedback — do not silently end the turn):');
+    if (fixLog) {
+      const fixNote = fixLog.lastFixStatus ? ` (last fix: ${fixLog.lastFixStatus})` : '';
+      if (fixLog.lastFixStatus === 'escalated') {
+        lines.push(`- fix-log round ${fixLog.round}/3: ${fixLog.critical} Critical still open${fixNote} — escalated, awaiting user decision; do not auto-resume.`);
+      }
+      else {
+        lines.push(`- fix-log round ${fixLog.round}/3: ${fixLog.critical} Critical still open${fixNote}. If a /ccg:review --fix Ralph loop is in flight, continue the next round automatically; if escalated/aborted, tell the user explicitly.`);
+      }
+    }
+    const limitedGaps = uatGaps.slice(0, MAX_REPORT_QUALITY);
+    for (const g of limitedGaps) {
+      const symptom = g.sampleSymptom ? ` — "${g.sampleSymptom}"` : '';
+      lines.push(`- UAT ${g.taskId}: ${g.openCount} open gap(s), top severity ${g.topSeverity}${symptom}. Resume /ccg:verify-work or surface to the user.`);
+    }
+    if (uatGaps.length > limitedGaps.length) {
+      lines.push(`- ... ${uatGaps.length - limitedGaps.length} more UAT task(s) with open gaps (truncated)`);
+    }
+    lines.push('If the user explicitly asked to stop, just acknowledge these instead of resuming.');
   }
   lines.push('</ccg-stop-gate>');
   return lines.join('\n');
@@ -173,16 +381,29 @@ function main() {
   const harnessTasks = normalizeHarnessTasks(input);
   const merged = mergeTasks(ccgJobs, harnessTasks);
 
-  if (merged.length === 0) {
+  // Quality soft-feedback only fires on Stop. SubagentStop fires between
+  // code-fixer rounds where un-cleared Criticals are the expected state —
+  // scanning there would be pure noise.
+  const isStop = eventName === 'Stop';
+  const quality = isStop
+    ? { fixLog: scanFixLogUnresolved(cwd, Date.now()), uatGaps: scanUatGaps(cwd, Date.now()) }
+    : { fixLog: null, uatGaps: [] };
+  const hasQuality = quality.fixLog !== null || quality.uatGaps.length > 0;
+
+  if (merged.length === 0 && !hasQuality) {
     process.exit(0);
     return;
   }
 
+  // Stop / SubagentStop hook schema does NOT accept `hookSpecificOutput` —
+  // that field is reserved for PreToolUse / UserPromptSubmit / PostToolUse /
+  // PostToolBatch. The valid top-level fields for Stop are `continue`,
+  // `suppressOutput`, `stopReason`, `decision`, `reason`, `systemMessage`,
+  // `terminalSequence`. We use `systemMessage` to surface the warning to the
+  // model without setting `decision` (which would force the model to keep
+  // working — wrong tool for "warn, don't block" semantics).
   process.stdout.write(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: eventName,
-      additionalContext: composeWarning(eventName, merged),
-    },
+    systemMessage: composeWarning(eventName, merged, quality),
   }));
   process.exit(0);
 }
@@ -199,4 +420,12 @@ module.exports = {
   detectEvent,
   ACTIVE_STATUSES,
   MAX_REPORT_JOBS,
+  // Quality soft-feedback (P0-1)
+  readFileTail,
+  readFileHead,
+  scanFixLogUnresolved,
+  scanUatGaps,
+  QUALITY_FRESHNESS_MS,
+  MAX_FIXLOG_TAIL_BYTES,
+  MAX_UAT_DIRS,
 };