cloving 1.2.0 → 1.4.0

package/templates/develop/develop/flow-tests.ts

@@ -0,0 +1,394 @@
+import assert from "node:assert/strict";
+import { fakeStepBridge } from "cloving/workflows/testing";
+import { develop } from "../develop.ts";
+import { commit, input, completed, effects } from "./scenarios.ts";
+
+export interface FlowTest {
+  readonly name: string;
+  readonly run: () => void | Promise<void>;
+}
+export const flowTests: FlowTest[] = [];
+
+flowTests.push({
+  name: "CLV-221 a worker error blocks the ticket before propagating",
+  run: async () => {
+    using bridge = fakeStepBridge({
+      effects: {
+        ...effects(),
+        "claude run-turn": [
+          {
+            kind: "failed",
+            operationId: "failed-operation",
+            reason: "worker-failed",
+          },
+        ],
+      },
+    });
+    await assert.rejects(develop(input), { message: "worker-failed" });
+    assert.equal(
+      bridge.requests.filter(
+        (request) => request[0] === "effect" && request[1].method === "label",
+      ).length,
+      2,
+    );
+    const last = bridge.requests.at(-1);
+    assert.ok(last && last[0] === "effect");
+    assert.match(last[1].payload, /cloving: blocked/);
+  },
+});
+
+flowTests.push({
+  name: "CLV-221 a terminal merge failure moves the selected ticket out of the queue",
+  run: async () => {
+    using bridge = fakeStepBridge({
+      effects: {
+        ...effects(),
+        "github merge": [
+          completed({ reason: "ci-pending", output: "Waiting for CI." }),
+        ],
+      },
+    });
+    assert.equal((await develop(input)).kind, "blocked");
+    const labels = bridge.requests.filter(
+      (request) => request[0] === "effect" && request[1].method === "label",
+    );
+    assert.equal(labels.length, 2);
+    assert.deepEqual(
+      labels.map((request) => {
+        assert.ok(request[0] === "effect");
+        return {
+          scope: request[1].scope,
+          payload: JSON.parse(request[1].payload) as unknown,
+        };
+      }),
+      [
+        {
+          scope: {
+            phase: "pull-request",
+            operation: "github-label",
+            round: 1,
+            key: "start",
+          },
+          payload: {
+            owner: "acme",
+            repository: "demo",
+            number: 42,
+            add: ["cloving: in progress"],
+            remove: ["cloving: ready", "cloving: blocked"],
+          },
+        },
+        {
+          scope: {
+            phase: "pull-request",
+            operation: "github-label",
+            round: 1,
+            key: "blocked",
+          },
+          payload: {
+            owner: "acme",
+            repository: "demo",
+            number: 42,
+            add: ["cloving: blocked"],
+            remove: ["cloving: in progress"],
+          },
+        },
+      ],
+    );
+  },
+});
+
+flowTests.push({
+  name: "CLV-221 private worker diagnostics stay out of the public pull request",
+  run: async () => {
+    using bridge = fakeStepBridge({
+      effects: {
+        ...effects(),
+        "claude run-turn": [
+          completed({
+            summary:
+              "Internal diagnostics: private-check-output\nTicket status: complete",
+          }),
+        ],
+      },
+    });
+    await develop(input);
+    const opened = bridge.requests.find(
+      (request) => request[0] === "effect" && request[1].method === "open-pr",
+    );
+    assert.ok(opened && opened[0] === "effect");
+    assert.deepEqual(JSON.parse(opened[1].payload), {
+      title: "Fix the counter",
+      body: "Refs acme/demo#42\n\nCloving made this change for the ticket 42.",
+    });
+    assert.doesNotMatch(opened[1].payload, /private-check-output/);
+  },
+});
+
+flowTests.push({
+  name: "CLV-221 the default workflow merges only a reviewed pull after the checks",
+  run: async () => {
+    using bridge = fakeStepBridge({ effects: effects(), effectLimit: 27 });
+    assert.deepEqual(await develop(input), {
+      kind: "handoff_requested",
+      cycleId: input.cycleId,
+      promotionId: "pull-request-7",
+      ticketStatus: "complete",
+    });
+    assert.deepEqual(
+      bridge.requests.map((request) => {
+        assert.ok(request[0] === "effect");
+        return request[1].method;
+      }),
+      [
+        "prepare",
+        "label",
+        "run-turn",
+        "open-pr",
+        "wait-review",
+        "merge",
+        "close-issue",
+      ],
+    );
+    const merge = bridge.requests[5];
+    assert.ok(merge && merge[0] === "effect");
+    assert.deepEqual(JSON.parse(merge[1].payload), {
+      number: 7,
+      commit,
+      check: "beforeMerge",
+    });
+  },
+});
+
+for (const reason of ["check-failed", "merge-conflict", "ci-failed"]) {
+  flowTests.push({
+    name: `CLV-221 a ${reason} fix receives the merge output and is reviewed again`,
+    run: async () => {
+      const scenario = effects();
+      const output =
+        "First diagnostic\n  expected: 4\n  actual: 3\nLast diagnostic\n";
+      for (const key of [
+        "claude run-turn",
+        "github open-pr",
+        "github wait-review",
+      ] as const)
+        scenario[key] = [...scenario[key], ...scenario[key]];
+      scenario["github merge"] = [
+        completed({ reason, output }),
+        ...scenario["github merge"],
+      ];
+      using bridge = fakeStepBridge({ effects: scenario });
+      assert.equal((await develop(input)).kind, "handoff_requested");
+      const turns = bridge.requests.filter(
+        (request) =>
+          request[0] === "effect" && request[1].method === "run-turn",
+      );
+      assert.equal(turns.length, 2);
+      const fix = turns[1];
+      assert.ok(fix && fix[0] === "effect");
+      assert.ok(fix[1].payload.endsWith(output));
+      assert.ok(fix[1].payload.includes(reason));
+      const merges = bridge.requests.filter(
+        (request) => request[0] === "effect" && request[1].method === "merge",
+      );
+      assert.deepEqual(
+        merges.map((request) => {
+          assert.ok(request[0] === "effect");
+          return request[1].scope.round;
+        }),
+        [1, 2],
+      );
+      assert.equal(
+        bridge.requests.filter(
+          (request) =>
+            request[0] === "effect" && request[1].method === "wait-review",
+        ).length,
+        2,
+      );
+    },
+  });
+}
+
+flowTests.push({
+  name: "CLV-221 Greptile below 5/5 cannot merge and exhausts three review fixes",
+  run: async () => {
+    const scenario = effects();
+    for (const key of ["claude run-turn", "github open-pr"] as const)
+      scenario[key] = Array.from({ length: 4 }, () => scenario[key][0]).filter(
+        (value) => value !== undefined,
+      );
+    scenario["github wait-review"] = Array.from({ length: 4 }, () =>
+      completed({
+        number: 7,
+        commit,
+        score: 4,
+        summary: "Add recovery.",
+        findings: [],
+      }),
+    );
+    using bridge = fakeStepBridge({ effects: scenario });
+    assert.deepEqual(await develop(input), {
+      kind: "blocked",
+      cycleId: input.cycleId,
+      reason: "review-changes",
+      evidenceId: "review",
+    });
+    assert.equal(
+      bridge.requests.filter(
+        (request) =>
+          request[0] === "effect" && request[1].method === "run-turn",
+      ).length,
+      4,
+    );
+    assert.equal(
+      bridge.requests.some(
+        (request) => request[0] === "effect" && request[1].method === "merge",
+      ),
+      false,
+    );
+  },
+});
+
+for (const [reason, merge] of [
+  [
+    "ci-pending",
+    completed({ reason: "ci-pending", output: "Check prerequisites." }),
+  ],
+  [
+    "check-not-configured",
+    {
+      kind: "failed",
+      operationId: "failed-operation",
+      reason: "check-not-configured",
+    },
+  ],
+] as const) {
+  flowTests.push({
+    name: `CLV-221 ${reason} stops without another worker turn`,
+    run: async () => {
+      using bridge = fakeStepBridge({
+        effects: { ...effects(), "github merge": [merge] },
+      });
+      assert.equal((await develop(input)).kind, "blocked");
+      assert.equal(bridge.requests.length, 7);
+    },
+  });
+}
+
+flowTests.push({
+  name: "CLV-221 a merged issue update failure stays visible",
+  run: async () => {
+    using bridge = fakeStepBridge({
+      effects: {
+        ...effects(),
+        "github close-issue": [
+          {
+            kind: "failed",
+            operationId: "failed-operation",
+            reason: "offline",
+          },
+        ],
+      },
+    });
+    assert.deepEqual(await develop(input), {
+      kind: "handoff_requested",
+      cycleId: input.cycleId,
+      promotionId: "pull-request-7",
+      ticketStatus: "complete",
+      issueUpdate: "failed",
+    });
+    assert.equal(bridge.requests.length, 7);
+  },
+});
+
+flowTests.push({
+  name: "CLV-221 a non-GitHub ticket needs no issue update",
+  run: async () => {
+    using bridge = fakeStepBridge({ effects: effects() });
+    assert.equal(
+      (
+        await develop({
+          ...input,
+          input: { ticket: { id: "42", text: "Fix the counter." } },
+        })
+      ).kind,
+      "handoff_requested",
+    );
+    assert.equal(bridge.requests.length, 5);
+  },
+});
+
+flowTests.push({
+  name: "CLV-221 broker failure stops before the worker runs",
+  run: async () => {
+    using bridge = fakeStepBridge({ effectLimit: 0 });
+    await assert.rejects(develop(input), { message: "budget-exhausted" });
+    assert.equal(bridge.requests.length, 1);
+  },
+});
+
+flowTests.push({
+  name: "CLV-221 partial work is queued only after its reviewed pull merges",
+  run: async () => {
+    const scenario = effects();
+    scenario["claude run-turn"] = [
+      completed({
+        summary: "Remaining:\n- Add recovery.\nTicket status: partial",
+      }),
+    ];
+    using bridge = fakeStepBridge({
+      effects: {
+        ...scenario,
+        "github partial-issue": [completed({ ticketStatus: "partial" })],
+      },
+    });
+    assert.deepEqual(await develop(input), {
+      kind: "handoff_requested",
+      cycleId: input.cycleId,
+      promotionId: "pull-request-7",
+      ticketStatus: "partial",
+    });
+    const request = bridge.requests.at(-1);
+    assert.ok(request && request[0] === "effect");
+    assert.equal(request[1].method, "partial-issue");
+    assert.deepEqual(JSON.parse(request[1].payload), {
+      owner: "acme",
+      repository: "demo",
+      number: 42,
+      pullRequest: 7,
+      remaining: ["Add recovery."],
+    });
+  },
+});
+
+flowTests.push({
+  name: "the develop turns keep fail-closed checks and operator steps out of the remaining list",
+  run: async () => {
+    const scenario = effects();
+    for (const key of [
+      "claude run-turn",
+      "github open-pr",
+      "github wait-review",
+    ] as const)
+      scenario[key] = [...scenario[key], ...scenario[key]];
+    scenario["github merge"] = [
+      completed({ reason: "check-failed", output: "Check output.\n" }),
+      ...scenario["github merge"],
+    ];
+    using bridge = fakeStepBridge({ effects: scenario });
+    await develop(input);
+    const payloads = bridge.requests.flatMap((request) =>
+      request[0] === "effect" && request[1].method === "run-turn"
+        ? [request[1].payload]
+        : [],
+    );
+    for (const sentence of [
+      "List as remaining only work that the task asks for.",
+      "A check that the repository keeps fail-closed on purpose is not remaining work.",
+      "A step that the task gives to the operator is not remaining work.",
+    ])
+      assert.ok(payloads[0]?.includes(sentence), sentence);
+    assert.ok(
+      payloads[1]?.includes("Drop an item that the task does not ask for"),
+    );
+  },
+});

package/templates/develop/develop/local.ts

@@ -0,0 +1,40 @@
+import type { CycleOutcome } from "cloving/workflows";
+import {
+  developReport,
+  repair,
+  type DevelopState,
+  type DevelopFeedback,
+} from "./report.ts";
+import { reviewByPerson } from "cloving/workflows/steps/review-by-person";
+import { partialChoice } from "./partial-choice.ts";
+
+export async function localRound(
+  state: DevelopState,
+): Promise<CycleOutcome | DevelopFeedback> {
+  const { input, round } = state;
+  const report = await developReport(state);
+  const partial = await partialChoice({ input, round, report });
+  if (partial !== null) return partial;
+  if (
+    !report.clean ||
+    report.commit === null ||
+    !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(report.commit)
+  )
+    throw new Error("invalid-local-commit");
+  const review = await reviewByPerson({
+    subject: { target: input.cycleId, commit: report.commit },
+  });
+  if (!review.accepted)
+    return repair({
+      cycleId: input.cycleId,
+      round,
+      report,
+      result: { reason: "review-changes", output: review.feedback },
+    });
+  return {
+    kind: "handoff_requested",
+    cycleId: input.cycleId,
+    promotionId: `local-${report.commit}`,
+    ticketStatus: report.status.kind,
+  };
+}

package/templates/develop/develop/option-tests.ts

@@ -0,0 +1,174 @@
+import assert from "node:assert/strict";
+import {
+  fakeStepBridge,
+  type ScenarioRequest,
+} from "cloving/workflows/testing";
+import { develop } from "../develop.ts";
+import { commit, input, completed, effects, selection } from "./scenarios.ts";
+
+const taskText =
+  "Develop the submitted task text.\n\nGitHub issue: acme/demo#42 (open)";
+
+function requestInput() {
+  return selection.input === "ticket"
+    ? input
+    : {
+        cycleId: input.cycleId,
+        repository: input.repository,
+        input: { prompt: taskText },
+      };
+}
+
+function scenarioEffects() {
+  return {
+    ...effects(),
+    "claude run-turn": [
+      completed({
+        summary: "Done.\nTicket status: complete",
+        commit,
+        uncommitted: [],
+      }),
+    ],
+    "claude run-turn:review": [
+      completed({ summary: "Reviewed.", reviewVerdict: "accept" }),
+    ],
+    "github partial-issue": [completed({ ticketStatus: "partial" })],
+  };
+}
+
+function completeCalls(): string[] {
+  const review: Readonly<Record<string, string>> = {
+    greptile: "wait-review",
+    person: "approval",
+    turn: "run-turn:review",
+  };
+  const acceptance = ["run-turn", review[selection.accept] ?? "unknown-review"];
+  if (selection.merge === "local") return acceptance;
+  return ["prepare"].concat(
+    selection.input === "ticket" ? ["label"] : [],
+    ["run-turn", "open-pr", review[selection.accept] ?? "unknown-review"],
+    selection.merge === "person" ? ["approval", "merge"] : ["merge"],
+    selection.input === "ticket" ? ["close-issue"] : [],
+  );
+}
+
+const approved = { decision: "approved" as const, answer: null };
+
+function callName(request: ScenarioRequest): string {
+  if (request[0] === "effect") return request[1].method;
+  if (request[0] === "waitForDecision") return request[1].kind;
+  return request[0];
+}
+
+export const optionTests = [
+  {
+    name: "CLV-221 the selected complete configuration reviews and delivers its commit",
+    run: async () => {
+      using bridge = fakeStepBridge({
+        effects: scenarioEffects(),
+        decisions: [approved, approved],
+        effectLimit: 27,
+      });
+      assert.deepEqual(await develop(requestInput()), {
+        kind: "handoff_requested",
+        cycleId: input.cycleId,
+        promotionId:
+          selection.merge === "local" ? `local-${commit}` : "pull-request-7",
+        ticketStatus: "complete",
+      });
+      assert.deepEqual(bridge.requests.map(callName), completeCalls());
+      const gates = bridge.requests.filter(
+        (request) => request[0] === "waitForDecision",
+      );
+      for (const gate of gates) assert.ok(gate[1].prompt.includes(commit));
+      const turns = bridge.requests.filter(
+        (request) =>
+          request[0] === "effect" && request[1].method === "run-turn",
+      );
+      assert.equal(turns.length, 1);
+      assert.ok(
+        turns.every(
+          (turn) =>
+            turn[0] === "effect" &&
+            turn[1].payload.includes(
+              selection.input === "ticket" ? input.input.ticket.text : taskText,
+            ),
+        ),
+      );
+      const merges = bridge.requests.filter(
+        (request) => request[0] === "effect" && request[1].method === "merge",
+      );
+      assert.deepEqual(
+        merges.map((request) =>
+          request[0] === "effect" ? request[1].payload : null,
+        ),
+        selection.merge === "local"
+          ? []
+          : [JSON.stringify({ number: 7, commit, check: "beforeMerge" })],
+      );
+    },
+  },
+  {
+    name: "CLV-221 the selected partial policy records work or asks for a bounded continuation",
+    run: async () => {
+      const scenario = scenarioEffects();
+      const partial = completed({
+        summary: "Remaining:\n- Add recovery.\nTicket status: partial",
+        commit,
+        uncommitted: [],
+      });
+      scenario["claude run-turn"] =
+        selection.partial === "queue"
+          ? [partial]
+          : [partial, ...scenario["claude run-turn"]];
+      const decisions =
+        selection.partial === "person"
+          ? [
+              {
+                decision: "answered" as const,
+                answer: "Preserve the result and add recovery.",
+              },
+              approved,
+              approved,
+            ]
+          : [approved, approved];
+      using bridge = fakeStepBridge({ effects: scenario, decisions });
+      assert.equal((await develop(requestInput())).kind, "handoff_requested");
+      const turns = bridge.requests.filter(
+        (request) =>
+          request[0] === "effect" && request[1].method === "run-turn",
+      );
+      assert.equal(turns.length, selection.partial === "queue" ? 1 : 2);
+      assert.deepEqual(
+        turns
+          .slice(1)
+          .map(
+            (fix) =>
+              fix[0] === "effect" &&
+              fix[1].payload.endsWith(
+                "Preserve the result and add recovery.",
+              ) &&
+              fix[1].payload.includes("- Add recovery."),
+          ),
+        selection.partial === "person" ? [true] : [],
+      );
+      const questions = bridge.requests.filter(
+        (request) =>
+          request[0] === "waitForDecision" && request[1].kind === "question",
+      );
+      assert.equal(questions.length, Number(selection.partial === "person"));
+      assert.ok(
+        questions.every(
+          (request) =>
+            request[0] === "waitForDecision" &&
+            request[1].prompt.includes("- Add recovery."),
+        ),
+      );
+      const updates = bridge.requests.filter(
+        (request) =>
+          request[0] === "effect" && request[1].method === "partial-issue",
+      );
+      assert.equal(updates.length, Number(selection.partial === "queue"));
+    },
+  },
+];

package/templates/develop/develop/partial-choice.ts

@@ -0,0 +1,29 @@
+import type { CycleOutcome } from "cloving/workflows";
+import type { DevelopTask, DevelopReport, DevelopFeedback } from "./report.ts";
+import { reviewPartial } from "./partial.ts";
+
+export async function partialChoice(request: {
+  readonly input: DevelopTask;
+  readonly round: number;
+  readonly report: DevelopReport;
+}): Promise<CycleOutcome | DevelopFeedback | null> {
+  const { input, round, report } = request;
+  if (report.status.kind !== "partial") return null;
+  const answer = await reviewPartial({
+    cycleId: input.cycleId,
+    round,
+    remaining: report.status.remaining,
+  });
+  if (answer === null)
+    return {
+      kind: "blocked",
+      cycleId: input.cycleId,
+      reason: "partial-work",
+      evidenceId: `partial:${input.cycleId}:${String(round)}`,
+    };
+  return {
+    reason: "partial-work",
+    output: answer,
+    remaining: report.status.remaining,
+  };
+}

package/templates/develop/develop/partial.ts

@@ -0,0 +1,28 @@
+import { waitForDecision } from "cloving/workflows/steps/wait-for-decision";
+
+export interface PartialWorkInput {
+  readonly cycleId: string;
+  readonly round: number;
+  readonly remaining: readonly string[];
+}
+
+export async function reviewPartial(
+  input: PartialWorkInput,
+): Promise<string | null> {
+  if (!Number.isSafeInteger(input.round) || input.round < 1 || input.round > 4)
+    throw new Error("invalid-development-round");
+  if (input.round === 4) return null;
+  const decision = await waitForDecision({
+    gateId: `partial:${input.cycleId}:${String(input.round)}`,
+    kind: "question",
+    prompt: [
+      "Some work remains:",
+      input.remaining.map((item) => `- ${item}`).join("\n"),
+      "",
+      "Describe the next fix to continue, or submit an empty answer to stop.",
+    ].join("\n"),
+  });
+  if (decision.decision !== "answered" || decision.answer?.trim() === "")
+    return null;
+  return decision.answer;
+}