feat: implement ralph loop CI gating

Implement CI-gating spec compliance for Ralph loop with persisted ciStatus state, prompt gating context, CI fix tracking, lint warning aggregation, and CI blocked notifications.\n\nAlso add CI status summaries to GitHub evaluation comments, apply required tracking issue labels, add unit tests for CI-gating helpers, and update IMPLEMENTATION_PLAN.md with completed task notes and validation outcomes.\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Addono

IMPLEMENTATION_PLAN.md

@@ -212,3 +212,18 @@ This plan lists prioritized tasks required to bring the implementation into full
     - Added a shared helper to clamp evaluation timeout to a safe 180s–600s window, using loop timeout config as the source of truth.
     - Evaluation now retries once when the SDK reports a `session.idle` timeout, reducing transient fallback-score failures.
     - Validation run after this change: `typecheck`, `lint` (warnings only), `test`, and `npm audit --production` all pass; audit reports 0 vulnerabilities.
+
+## 17. Ralph Loop CI Gating and Reporting Compliance
+- **Task:** Implement CI status persistence, prompt gating, and CI visibility/reporting in the Ralph loop. **[COMPLETE]**
+  - **Spec:** CI-gating/spec.md (CI Status Tracking, CI Gating Logic, CI Fix Tracking, GitHub Reporting, Lint Warning Accumulation), Ralph-loop/spec.md (GitHub issue labels)
+  - **Files:** ralph-loop.ts, src/ralph/ci-gating.ts (new), test/unit/ralph/ci-gating.test.ts (new)
+  - **Tests:** test/unit/ralph/ci-gating.test.ts
+  - **Dependencies:** Task 16
+  - **Notes:**
+    - Targets low-scoring checklist areas around spec compliance/code quality by implementing missing `ciStatus` state fields and CI gating behavior required by `ci-gating/spec.md`.
+    - Added full CI check execution per iteration (`build`, `test`, `lint`), persisted result fields (`passed`, status breakdown, errors, timestamps), and CI-broken fix tracking (`ciBrokenSince`, `ciFixAttempts`, `ciLastFixAttempt`).
+    - Added build-prompt CI context injection (`✅ pass`, `⚠️ lint warnings`, `❌ blocking failures`) so red CI explicitly blocks feature work and partial CI is highlighted.
+    - Added CI status summaries to GitHub fitness comments and CI-blocked issue notifications (`🚨 CI BLOCKED at Iteration N`) with failure details.
+    - Added lint warning aggregation (top rules/files) and threshold warning log when warnings exceed 20.
+    - Tracking issue creation now includes required labels: `ralph-loop`, `automated`.
+    - Validation run after this change: `npm run typecheck`, `npm run lint`, `npm test`, and `npm audit --production` all pass; audit reports 0 vulnerabilities.

ralph-loop.ts

@@ -12,6 +12,16 @@ import {
   isSessionIdleTimeoutError,
   resolveEvaluationTimeoutMs,
 } from "./src/ralph/evaluation.ts";
+import {
+  deriveCiStatus,
+  generateCiBlockedComment,
+  generateCiCommentSummary,
+  generateCiPromptContext,
+  isCiBroken,
+  normalizeCiStatus,
+  type CiStatus,
+  type CommandCheckResult,
+} from "./src/ralph/ci-gating.ts";
 
 // --- Types ---
 
@@ -59,6 +69,11 @@ interface RalphState {
   currentModel: string;
   trackingIssueNumber: number | null;
   evaluations: Evaluation[];
+  ciStatus: CiStatus;
+  ciBrokenSince: number | null;
+  ciFixAttempts: number;
+  ciLastFixAttempt: number | null;
+  ciLastBlockedNotification: number | null;
 }
 
 type Mode = "plan" | "build";
@@ -74,19 +89,54 @@ async function loadConfig(): Promise<RalphConfig> {
   return JSON.parse(raw) as RalphConfig;
 }
 
-async function loadState(): Promise<RalphState> {
-  if (existsSync(STATE_FILE)) {
-    const raw = await readFile(STATE_FILE, "utf-8");
-    return JSON.parse(raw) as RalphState;
-  }
+function defaultState(): RalphState {
   return {
     currentIteration: 0,
     currentModel: "",
     trackingIssueNumber: null,
     evaluations: [],
+    ciStatus: normalizeCiStatus(undefined),
+    ciBrokenSince: null,
+    ciFixAttempts: 0,
+    ciLastFixAttempt: null,
+    ciLastBlockedNotification: null,
   };
 }
 
+async function loadState(): Promise<RalphState> {
+  if (existsSync(STATE_FILE)) {
+    const raw = await readFile(STATE_FILE, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<RalphState>;
+    return {
+      currentIteration:
+        typeof parsed.currentIteration === "number" ? parsed.currentIteration : 0,
+      currentModel:
+        typeof parsed.currentModel === "string" ? parsed.currentModel : "",
+      trackingIssueNumber:
+        typeof parsed.trackingIssueNumber === "number"
+          ? parsed.trackingIssueNumber
+          : null,
+      evaluations: Array.isArray(parsed.evaluations)
+        ? (parsed.evaluations as Evaluation[])
+        : [],
+      ciStatus: normalizeCiStatus(parsed.ciStatus),
+      ciBrokenSince:
+        typeof parsed.ciBrokenSince === "number" ? parsed.ciBrokenSince : null,
+      ciFixAttempts:
+        typeof parsed.ciFixAttempts === "number" ? parsed.ciFixAttempts : 0,
+      ciLastFixAttempt:
+        typeof parsed.ciLastFixAttempt === "number"
+          ? parsed.ciLastFixAttempt
+          : null,
+      ciLastBlockedNotification:
+        typeof parsed.ciLastBlockedNotification === "number"
+          ? parsed.ciLastBlockedNotification
+          : null,
+    };
+  }
+  return defaultState();
+}
+
 async function saveState(state: RalphState): Promise<void> {
   await writeFile(STATE_FILE, JSON.stringify(state, null, 2));
 }
@@ -150,7 +200,7 @@ function selectModel(
 
 // --- Fitness evaluation ---
 
-function runCommand(cmd: string): { success: boolean; output: string } {
+function runCommand(cmd: string): CommandCheckResult {
   try {
     const output = execSync(cmd, {
       encoding: "utf-8",
@@ -167,6 +217,63 @@ function runCommand(cmd: string): { success: boolean; output: string } {
   }
 }
 
+function runCiCheck(iteration: number, state: RalphState): void {
+  const buildResult = runCommand("npm run build 2>&1");
+  const testResult = runCommand("npm test 2>&1");
+  const lintResult = runCommand("npm run lint 2>&1");
+  const { status, lintSummary } = deriveCiStatus(
+    buildResult,
+    testResult,
+    lintResult,
+  );
+  state.ciStatus = status;
+
+  if (status.lintStatus === "warnings") {
+    log(
+      `CI warnings: ${status.lintWarningCount ?? 0} warnings (build/test passing)`,
+      "WARN",
+    );
+    if ((status.lintWarningCount ?? 0) > 20) {
+      log(
+        `[Lint Warning] Threshold exceeded: ${status.lintWarningCount} > 20`,
+        "WARN",
+      );
+    }
+    if (lintSummary.topRules.length > 0 || lintSummary.topFiles.length > 0) {
+      const ruleSummary = lintSummary.topRules.join(", ");
+      const fileSummary = lintSummary.topFiles.join(", ");
+      log(
+        `Lint warning details:\nTop rules: ${ruleSummary || "none"}\nTop files: ${fileSummary || "none"}`,
+        "WARN",
+      );
+    }
+  }
+
+  const wasBroken = state.ciBrokenSince !== null;
+  const nowBroken = isCiBroken(status);
+
+  if (nowBroken) {
+    if (state.ciBrokenSince === null) {
+      state.ciBrokenSince = iteration;
+    }
+    state.ciFixAttempts += 1;
+    state.ciLastFixAttempt = iteration;
+    return;
+  }
+
+  if (wasBroken && state.ciBrokenSince !== null) {
+    const brokenIterations = iteration - state.ciBrokenSince;
+    log(
+      `[CI Recovery] Fixed after ${brokenIterations} iterations and ${state.ciFixAttempts} attempts`,
+      "INFO",
+    );
+    state.ciBrokenSince = null;
+    state.ciFixAttempts = 0;
+    state.ciLastFixAttempt = iteration;
+    state.ciLastBlockedNotification = null;
+  }
+}
+
 async function collectSpecFiles(): Promise<string> {
   const specs: string[] = [];
   // Scan all subdirectories under openspec/specs/ automatically
@@ -382,6 +489,7 @@ function generateCommentBody(
   iteration: number,
   model: string,
   scores: FitnessScores,
+  ciStatus: CiStatus,
 ): string {
   // Sort checklist ascending by score so regressions surface first
   const sortedChecklist = [...(scores.checklist ?? [])].sort(
@@ -413,6 +521,7 @@ function generateCommentBody(
 | **Aggregate** | **${scores.aggregate}/100** |
 
 **Model**: ${model}
+**CI**: ${generateCiCommentSummary(ciStatus)}
 
 ${accordion}
 
@@ -478,7 +587,8 @@ async function postToGitHub(
     if (!state.trackingIssueNumber) {
       const result = execSync(
         `gh issue create --repo "${config.trackingRepo}" ` +
-          `--title "[Ralph Loop] Fitness Tracking"`,
+          `--title "[Ralph Loop] Fitness Tracking" ` +
+          `--label "ralph-loop" --label "automated"`,
         { encoding: "utf-8", timeout: 30_000 },
       );
       const match = result.match(/\/issues\/(\d+)/);
@@ -490,7 +600,7 @@ async function postToGitHub(
 
     if (state.trackingIssueNumber) {
       // Post per-evaluation comment (uses --body-file to preserve newlines)
-      const comment = generateCommentBody(iteration, model, scores);
+      const comment = generateCommentBody(iteration, model, scores, state.ciStatus);
       ghWithBodyFile(
         `gh issue comment ${state.trackingIssueNumber} --repo "${config.trackingRepo}"`,
         comment,
@@ -512,6 +622,33 @@ async function postToGitHub(
   }
 }
 
+async function postCiBlockedNotification(
+  state: RalphState,
+  config: RalphConfig,
+  iteration: number,
+): Promise<void> {
+  if (
+    !config.trackingRepo ||
+    !state.trackingIssueNumber ||
+    !isCiBroken(state.ciStatus) ||
+    state.ciLastBlockedNotification === iteration
+  ) {
+    return;
+  }
+
+  try {
+    const body = generateCiBlockedComment(iteration, state.ciStatus);
+    ghWithBodyFile(
+      `gh issue comment ${state.trackingIssueNumber} --repo "${config.trackingRepo}"`,
+      body,
+      true,
+    );
+    state.ciLastBlockedNotification = iteration;
+  } catch (err) {
+    log(`Failed to post CI blocked notification: ${err}`, "ERROR");
+  }
+}
+
 // --- Tool event formatting ---
 
 /**
@@ -743,10 +880,11 @@ async function ralphLoop(mode: Mode, maxIterationsOverride?: number) {
     for (let i = startIteration; i <= endIteration; i++) {
       if (shuttingDown) break;
 
+      const ciContext = generateCiPromptContext(state.ciStatus);
       const improvementContext = generateImprovementContext(state.evaluations);
-      const prompt = improvementContext
-        ? `${basePrompt}\n${improvementContext}`
-        : basePrompt;
+      const prompt = [basePrompt, ciContext, improvementContext]
+        .filter((v) => v.trim() !== "")
+        .join("\n");
 
       const lastEval = state.evaluations[state.evaluations.length - 1];
       const scoreHint = lastEval
@@ -757,6 +895,9 @@ async function ralphLoop(mode: Mode, maxIterationsOverride?: number) {
         const worstItem = [...lastEval.scores.checklist].sort((a, b) => a.score - b.score)[0]!;
         log(`Target this iteration: [${worstItem.score}/100] ${worstItem.requirement}`, "ITER");
       }
+      if (isCiBroken(state.ciStatus)) {
+        await postCiBlockedNotification(state, config, i);
+      }
 
       const session = await client.createSession({
         model: state.currentModel,
@@ -802,6 +943,7 @@ async function ralphLoop(mode: Mode, maxIterationsOverride?: number) {
       log(`Iteration ${i} complete in ${elapsed}s | Tools used: ${toolSummary || "none"}`, "ITER");
 
       state.currentIteration = i;
+      runCiCheck(i, state);
 
       // Fitness evaluation every N iterations
       if (i % config.evaluationInterval === 0) {