@jhlee0619/codexloop 0.1.0

package/schemas/loop-state.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://codexloop/loop-state.schema.json",
+  "title": "CodexLoop State",
+  "description": "Canonical shape of <repo>/.loop/state.json. This schema is documentation for human readers and for the state.mjs runtime; it is NOT passed to Codex via --output-schema.",
+  "type": "object",
+  "required": [
+    "version",
+    "loopId",
+    "status",
+    "mode",
+    "goal",
+    "budget",
+    "convergence",
+    "iterations"
+  ],
+  "properties": {
+    "version": { "type": "integer", "minimum": 1 },
+    "loopId": { "type": ["string", "null"] },
+    "status": {
+      "type": "string",
+      "enum": [
+        "idle",
+        "queued",
+        "running",
+        "paused",
+        "completed",
+        "failed",
+        "cancelled",
+        "crashed"
+      ]
+    },
+    "pid": { "type": ["integer", "null"] },
+    "mode": { "type": "string", "enum": ["interactive", "background", "dry-run"] },
+    "startedAt": { "type": ["string", "null"], "format": "date-time" },
+    "lastIterationAt": { "type": ["string", "null"], "format": "date-time" },
+    "completedAt": { "type": ["string", "null"], "format": "date-time" },
+    "goal": {
+      "type": "object",
+      "required": ["text", "acceptanceCriteria"],
+      "properties": {
+        "text": { "type": "string" },
+        "acceptanceCriteria": { "type": "array", "items": { "type": "string" } },
+        "seedCommit": { "type": ["string", "null"] },
+        "relevantGlobs": { "type": "array", "items": { "type": "string" } },
+        "testCmd": { "type": ["string", "null"] },
+        "lintCmd": { "type": ["string", "null"] },
+        "typeCmd": { "type": ["string", "null"] },
+        "goalHash": { "type": ["string", "null"] }
+      }
+    },
+    "budget": {
+      "type": "object",
+      "required": ["maxIterations", "maxElapsedMs", "maxCodexCalls", "consumed"],
+      "properties": {
+        "maxIterations": { "type": "integer", "minimum": 1 },
+        "maxElapsedMs": { "type": "integer", "minimum": 0 },
+        "maxCodexCalls": { "type": "integer", "minimum": 0 },
+        "consumed": {
+          "type": "object",
+          "properties": {
+            "iterations": { "type": "integer", "minimum": 0 },
+            "elapsedMs": { "type": "integer", "minimum": 0 },
+            "codexCalls": { "type": "integer", "minimum": 0 },
+            "startedAtMs": { "type": ["integer", "null"] }
+          }
+        }
+      }
+    },
+    "convergence": {
+      "type": "object",
+      "properties": {
+        "epsilon": { "type": "number", "minimum": 0 },
+        "stableWindow": { "type": "integer", "minimum": 1 },
+        "scoreHistory": { "type": "array", "items": { "type": "number" } },
+        "stalledSince": { "type": ["integer", "null"] }
+      }
+    },
+    "iterations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["index", "startedAt"],
+        "properties": {
+          "index": { "type": "integer", "minimum": 1 },
+          "startedAt": { "type": "string", "format": "date-time" },
+          "completedAt": { "type": ["string", "null"], "format": "date-time" },
+          "qualityScore": { "type": ["number", "null"] },
+          "qualityDelta": { "type": ["number", "null"] },
+          "acceptedProposalId": { "type": ["string", "null"] },
+          "stopReason": { "type": ["string", "null"] },
+          "error": { "type": ["string", "null"] }
+        }
+      }
+    },
+    "accepted": { "type": "array" },
+    "rejected": { "type": "array" },
+    "openIssues": { "type": "array" },
+    "openIssuesInitial": { "type": "integer", "minimum": 0 },
+    "stopReason": { "type": ["string", "null"] },
+    "error": { "type": ["object", "string", "null"] }
+  }
+}

package/schemas/proposal.schema.json

@@ -0,0 +1,74 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://codexloop/proposal.schema.json",
+  "title": "CodexLoop Proposal Set",
+  "description": "Structured JSON that Codex must return for the suggest step: ALWAYS at least two proposals. Passed to `codex exec --output-schema`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["proposals"],
+  "properties": {
+    "proposals": {
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 5,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "approach",
+          "patch",
+          "justification",
+          "estimatedRisk",
+          "estimatedImpact",
+          "filesTouched",
+          "modifiesTests"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9_-]*$",
+            "description": "Short stable id like 'a', 'b', 'c'."
+          },
+          "approach": {
+            "type": "string",
+            "description": "One-sentence summary of what this proposal does and why."
+          },
+          "patch": {
+            "type": "string",
+            "description": "Unified diff ready for `git apply`. If no code change is needed, use the empty string."
+          },
+          "justification": {
+            "type": "string",
+            "description": "Why this proposal addresses the open issues identified in evaluation."
+          },
+          "estimatedRisk": {
+            "type": "string",
+            "enum": ["low", "medium", "high"]
+          },
+          "estimatedImpact": {
+            "type": "string",
+            "enum": ["low", "medium", "high"]
+          },
+          "filesTouched": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "modifiesTests": {
+            "type": "boolean",
+            "description": "True if `patch` modifies, adds, or deletes any test file."
+          },
+          "testChangeJustification": {
+            "type": ["string", "null"],
+            "description": "REQUIRED (non-empty) when modifiesTests is true. Explain what the test change is and why it is not reward-hacking."
+          },
+          "reviewNotes": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Self-review notes: known shortcomings, assumptions, follow-ups."
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/ranking.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://codexloop/ranking.schema.json",
+  "title": "CodexLoop Ranking Output",
+  "description": "Structured JSON that Codex must return for the rank step. One 'judge' call compares all proposals against six dimensions.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["scores", "winner", "rejections"],
+  "properties": {
+    "scores": {
+      "type": "array",
+      "minItems": 2,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "proposalId",
+          "correctness",
+          "requirementSatisfaction",
+          "simplicity",
+          "maintainability",
+          "riskInverse",
+          "testability",
+          "weighted"
+        ],
+        "properties": {
+          "proposalId": { "type": "string" },
+          "correctness": { "type": "number", "minimum": 0, "maximum": 1 },
+          "requirementSatisfaction": { "type": "number", "minimum": 0, "maximum": 1 },
+          "simplicity": { "type": "number", "minimum": 0, "maximum": 1 },
+          "maintainability": { "type": "number", "minimum": 0, "maximum": 1 },
+          "riskInverse": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "description": "1 = very safe, 0 = extremely risky. Inverted so higher is always better."
+          },
+          "testability": { "type": "number", "minimum": 0, "maximum": 1 },
+          "weighted": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1,
+            "description": "The judge's own weighted sum. Runtime will re-compute from dimensional scores and override if they disagree."
+          },
+          "notes": { "type": "string" }
+        }
+      }
+    },
+    "winner": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "justification"],
+      "properties": {
+        "id": { "type": "string" },
+        "justification": {
+          "type": "string",
+          "description": "Why this proposal beats the alternatives on the dimensional rubric."
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "How confident the judge is in this pick."
+        }
+      }
+    },
+    "rejections": {
+      "type": "object",
+      "description": "Map of rejected proposal id to a concrete 'why not' reason.",
+      "additionalProperties": { "type": "string" }
+    },
+    "tiebreaker": {
+      "type": ["string", "null"],
+      "description": "If applied, a short explanation of the tiebreaker (correctness, risk, patch size)."
+    }
+  }
+}

package/scripts/lib/apply.mjs

@@ -0,0 +1,254 @@
+// Patch application with hard reward-hacking guards and atomic rollback.
+//
+// Preconditions: the target repo MUST be a git repo with a clean working tree
+// at the start of each iteration. `applyPatch` refuses to run if the working
+// tree has uncommitted changes so there is never any ambiguity about what the
+// iteration mutated.
+//
+// On success, the patch is applied and committed with a codexloop signature
+// message. On any failure (patch rejection, commit failure, reward-hacking
+// detection, or a later regression in validate), we `git reset --hard` back
+// to the recorded preSha and mark the iteration's apply record accordingly.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+import { runCommand } from "./process.mjs";
+
+const TEST_FILE_PATTERNS = [
+  /(^|\/)tests?\//i,
+  /(^|\/)__tests__\//i,
+  /(^|\/)spec\//i,
+  /\.test\.[a-zA-Z0-9]+$/,
+  /\.spec\.[a-zA-Z0-9]+$/,
+  /_test\.[a-zA-Z0-9]+$/
+];
+
+export function isTestPath(filePath) {
+  if (!filePath || typeof filePath !== "string") return false;
+  return TEST_FILE_PATTERNS.some((re) => re.test(filePath));
+}
+
+// Parse a unified diff looking for reward-hacking patterns.
+// Returns an array of findings; empty means the patch looks clean.
+export function scanPatchForRewardHacking(patch, proposal) {
+  const findings = [];
+  if (!patch || typeof patch !== "string") return findings;
+
+  // Missing justification when proposal claims to modify tests.
+  if (proposal?.modifiesTests === true) {
+    const justification = String(proposal.testChangeJustification ?? "").trim();
+    if (justification.length < 20) {
+      findings.push({
+        kind: "missing-test-justification",
+        severity: "high",
+        summary: "proposal.modifiesTests is true but testChangeJustification is missing or < 20 chars"
+      });
+    }
+  }
+
+  const lines = patch.split("\n");
+  let headerFileA = null;
+  let headerFileB = null;
+  let deletedFileMode = false;
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+
+    if (line.startsWith("diff --git ")) {
+      const match = line.match(/^diff --git a\/(.+?) b\/(.+)$/);
+      if (match) {
+        headerFileA = match[1];
+        headerFileB = match[2];
+        deletedFileMode = false;
+      }
+      continue;
+    }
+
+    if (line.startsWith("deleted file mode")) {
+      deletedFileMode = true;
+      if (headerFileA && isTestPath(headerFileA)) {
+        findings.push({
+          kind: "test-file-deleted",
+          severity: "critical",
+          file: headerFileA,
+          summary: `patch deletes test file ${headerFileA}`
+        });
+      }
+      continue;
+    }
+
+    if (line.startsWith("new file mode")) {
+      deletedFileMode = false;
+      continue;
+    }
+
+    // Skip/only/xit inside a test file hunk
+    if (
+      line.startsWith("+") &&
+      !line.startsWith("+++") &&
+      headerFileB &&
+      isTestPath(headerFileB)
+    ) {
+      if (
+        /\.(skip|only|xit|xdescribe|todo)\b/.test(line) ||
+        /\b(test|it|describe)\.skip\b/.test(line) ||
+        /\bxit\s*\(/.test(line) ||
+        /\bxdescribe\s*\(/.test(line)
+      ) {
+        findings.push({
+          kind: "test-disabled",
+          severity: "high",
+          file: headerFileB,
+          snippet: line.slice(1).trim().slice(0, 160),
+          summary: `patch adds test skip/only/xit in ${headerFileB}`
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+function getHead(cwd) {
+  const res = runCommand("git", ["rev-parse", "HEAD"], { cwd });
+  if (res.status !== 0) return null;
+  return res.stdout.trim() || null;
+}
+
+function workingTreeDirty(cwd) {
+  const res = runCommand("git", ["status", "--porcelain"], { cwd });
+  return res.status !== 0 || (res.stdout || "").trim().length > 0;
+}
+
+function hardReset(cwd, sha) {
+  if (!sha) return { ok: false, reason: "no-sha" };
+  const res = runCommand("git", ["reset", "--hard", sha], { cwd });
+  return { ok: res.status === 0, detail: (res.stderr || res.stdout || "").trim() };
+}
+
+export function rollbackToSha(cwd, sha) {
+  return hardReset(cwd, sha);
+}
+
+function buildCommitEnv() {
+  return {
+    ...process.env,
+    GIT_AUTHOR_NAME: process.env.GIT_AUTHOR_NAME ?? "CodexLoop",
+    GIT_AUTHOR_EMAIL: process.env.GIT_AUTHOR_EMAIL ?? "codexloop@local",
+    GIT_COMMITTER_NAME: process.env.GIT_COMMITTER_NAME ?? "CodexLoop",
+    GIT_COMMITTER_EMAIL: process.env.GIT_COMMITTER_EMAIL ?? "codexloop@local"
+  };
+}
+
+// Apply a proposal's patch to the target repo. Returns a structured record
+// the iteration layer records verbatim.
+export async function applyPatch({ cwd, proposal, iterationIndex }) {
+  const patch = proposal?.patch ?? "";
+  const record = {
+    applied: false,
+    empty: false,
+    filesTouched: Array.isArray(proposal?.filesTouched) ? [...proposal.filesTouched] : [],
+    preSha: null,
+    postSha: null,
+    hackingFindings: [],
+    conflicts: null,
+    error: null,
+    rolledBack: false
+  };
+
+  record.preSha = getHead(cwd);
+
+  record.hackingFindings = scanPatchForRewardHacking(patch, proposal);
+  const blocking = record.hackingFindings.find(
+    (f) =>
+      f.kind === "test-file-deleted" ||
+      f.kind === "test-disabled" ||
+      f.kind === "missing-test-justification"
+  );
+  if (blocking) {
+    record.error = `reward-hacking-guard:${blocking.kind}${blocking.file ? `:${blocking.file}` : ""}`;
+    return record;
+  }
+
+  if (!patch.trim()) {
+    record.empty = true;
+    return record;
+  }
+
+  if (workingTreeDirty(cwd)) {
+    const status = runCommand("git", ["status", "--porcelain"], { cwd });
+    record.error =
+      `working tree is not clean before apply: ${(status.stdout || "").trim().split("\n").slice(0, 5).join(" | ")}`;
+    return record;
+  }
+
+  const tmpPatch = path.join(
+    os.tmpdir(),
+    `codexloop-patch-${process.pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}.diff`
+  );
+  fs.writeFileSync(tmpPatch, patch.endsWith("\n") ? patch : `${patch}\n`, "utf8");
+
+  try {
+    const check = runCommand("git", ["apply", "--check", tmpPatch], { cwd });
+    if (check.status !== 0) {
+      record.conflicts = (check.stderr || check.stdout || "unknown conflict").trim();
+      record.error = `git apply --check failed: ${record.conflicts.slice(0, 300)}`;
+      return record;
+    }
+
+    const apply = runCommand("git", ["apply", tmpPatch], { cwd });
+    if (apply.status !== 0) {
+      record.error = `git apply failed: ${(apply.stderr || apply.stdout || "").trim().slice(0, 300)}`;
+      hardReset(cwd, record.preSha);
+      record.rolledBack = true;
+      return record;
+    }
+
+    const env = buildCommitEnv();
+    const addRes = runCommand("git", ["add", "-A"], { cwd, env });
+    if (addRes.status !== 0) {
+      record.error = `git add failed: ${(addRes.stderr || "").trim().slice(0, 300)}`;
+      hardReset(cwd, record.preSha);
+      record.rolledBack = true;
+      return record;
+    }
+
+    const commitMsg =
+      `cloop: iter ${iterationIndex} apply ${proposal?.id ?? "?"}`;
+    const commitRes = runCommand(
+      "git",
+      ["commit", "-m", commitMsg],
+      { cwd, env }
+    );
+    if (commitRes.status !== 0) {
+      record.error =
+        `git commit failed: ${(commitRes.stderr || commitRes.stdout || "").trim().slice(0, 400)}`;
+      hardReset(cwd, record.preSha);
+      record.rolledBack = true;
+      return record;
+    }
+
+    record.postSha = getHead(cwd);
+    record.applied = true;
+
+    if (record.filesTouched.length === 0 && record.preSha && record.postSha) {
+      const diffFiles = runCommand(
+        "git",
+        ["diff", "--name-only", `${record.preSha}..${record.postSha}`],
+        { cwd }
+      );
+      if (diffFiles.status === 0) {
+        record.filesTouched = (diffFiles.stdout || "")
+          .split("\n")
+          .map((l) => l.trim())
+          .filter(Boolean);
+      }
+    }
+
+    return record;
+  } finally {
+    try { fs.unlinkSync(tmpPatch); } catch {}
+  }
+}