cloving 1.2.0 → 1.3.0

package/templates/develop/develop/turn.ts

@@ -0,0 +1,67 @@
+import type { ProtectedResult } from "cloving/workflows";
+import { protectedEffect } from "cloving/workflows/steps/protected-effect";
+
+export interface DevelopTurnInput {
+  readonly cycleId: string;
+  readonly repository: string;
+  readonly ticket?: string;
+  readonly prompt?: string;
+  readonly round: number;
+  readonly feedback: {
+    readonly reason: string;
+    readonly output: string;
+    readonly remaining: readonly string[];
+  } | null;
+}
+
+function turnPrompt(input: DevelopTurnInput): string {
+  if (!Number.isSafeInteger(input.round) || input.round < 1 || input.round > 4)
+    throw new Error("invalid-development-round");
+  const task = input.ticket ?? input.prompt;
+  if (
+    (input.ticket !== undefined && input.prompt !== undefined) ||
+    typeof task !== "string" ||
+    task.trim() === ""
+  )
+    throw new Error("invalid-development-task");
+  const prompt = [
+    "Implement the task in this worktree, on its current branch.",
+    `The main checkout at ${input.repository} is read-only.`,
+    "Read AGENTS.md and CLAUDE.md. Use TDD: observe the intended test failure before implementing each behavior.",
+    "Run the repository checks, commit the changes, then run npm run check:clean if the repository provides it.",
+    "Do not push, publish, deploy, or switch branches.",
+    "The branch will become a public pull request. Keep local paths out of tracked files and commit messages.",
+    "Report the changes and check results. Finish with Ticket status: complete or Ticket status: partial. For partial work, precede the status with Remaining: and one unfinished item per '- ' line.",
+    "",
+    "Task:",
+    task,
+  ].join("\n");
+  if (input.feedback === null) return prompt;
+  return [
+    prompt,
+    "",
+    `This is fix round ${String(input.round)}. Address ${input.feedback.reason}, then commit the fix.`,
+    "Reassess every unfinished item and retain unresolved items in the next Remaining: list:",
+    input.feedback.remaining.map((item) => `- ${item}`).join("\n"),
+    "",
+    "Output from the previous result:",
+    input.feedback.output,
+  ].join("\n");
+}
+
+export async function developTurn(
+  input: DevelopTurnInput,
+): Promise<ProtectedResult> {
+  return await protectedEffect({
+    scope: {
+      phase: "implement",
+      operation: "claude-turn",
+      round: input.round,
+    },
+    capability: "claude",
+    method: "run-turn",
+    target: input.cycleId,
+    payload: turnPrompt(input),
+    units: 1,
+  });
+}

package/templates/develop/develop.declaration.json

@@ -0,0 +1,24 @@
+{
+  "workflow": {
+    "workflowId": "develop",
+    "effectLimit": 27,
+    "capabilities": ["claude", "github"],
+    "queue": true,
+    "input": {
+      "maximumBytes": 65536,
+      "fields": { "ticket": { "type": "ticket" } }
+    }
+  },
+  "methods": {
+    "claude": ["run-turn"],
+    "github": [
+      "prepare",
+      "label",
+      "open-pr",
+      "wait-review",
+      "merge",
+      "close-issue",
+      "partial-issue"
+    ]
+  }
+}

package/templates/develop/develop.test.ts

@@ -0,0 +1,287 @@
+import { flowTests } from "./develop/flow-tests.ts";
+import { refusalTests } from "./develop/refusal-tests.ts";
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { fakeStepBridge } from "cloving/workflows/testing";
+import { developTurn } from "./develop/turn.ts";
+import { reviewPartial } from "./develop/partial.ts";
+import { queuePartial } from "./develop/queue-partial.ts";
+
+for (const scenario of flowTests.concat(refusalTests))
+  await test(scenario.name, scenario.run);
+
+await test("CLV-221 invalid partial rounds never dispatch an effect or open a question", async () => {
+  using bridge = fakeStepBridge({});
+  for (const round of [0, -1, 1.5, 5, NaN, Infinity]) {
+    const input = {
+      cycleId: "run-1",
+      round,
+      issue: { owner: "acme", repository: "demo", number: 42 },
+      pullRequest: 7,
+      remaining: ["Test."],
+    };
+    await assert.rejects(queuePartial(input), {
+      message: "invalid-development-round",
+    });
+    await assert.rejects(reviewPartial(input), {
+      message: "invalid-development-round",
+    });
+  }
+  assert.deepEqual(bridge.requests, []);
+});
+
+await test("CLV-221 partial questions use distinct rounds and stop after three fixes", async () => {
+  using bridge = fakeStepBridge({
+    decisions: [
+      { decision: "answered", answer: "First fix." },
+      { decision: "answered", answer: "Second fix." },
+      { decision: "answered", answer: "Third fix." },
+    ],
+  });
+  for (const round of [1, 2, 3]) {
+    assert.equal(
+      typeof (await reviewPartial({
+        cycleId: "run-1",
+        round,
+        remaining: ["Test."],
+      })),
+      "string",
+    );
+  }
+  assert.equal(
+    await reviewPartial({
+      cycleId: "run-1",
+      round: 4,
+      remaining: ["Test."],
+    }),
+    null,
+  );
+  assert.deepEqual(
+    bridge.requests.map((request) => {
+      assert.equal(request[0], "waitForDecision");
+      return request[1].gateId;
+    }),
+    ["partial:run-1:1", "partial:run-1:2", "partial:run-1:3"],
+  );
+});
+
+await test("CLV-221 partial work stops without an explicit nonempty answer", async () => {
+  for (const decision of [
+    { decision: "answered" as const, answer: " \n" },
+    { decision: "answered" as const, answer: null },
+    { decision: "denied" as const, answer: "Do not continue." },
+    { decision: "expired" as const, answer: "Stale feedback." },
+    { decision: "approved" as const, answer: "Unexpected approval." },
+  ]) {
+    using bridge = fakeStepBridge({ decisions: [decision] });
+    assert.equal(
+      await reviewPartial({ cycleId: "run-1", round: 2, remaining: ["Test."] }),
+      null,
+    );
+    assert.equal(bridge.requests.length, 1);
+    assert.equal(bridge.requests[0]?.[0], "waitForDecision");
+  }
+});
+
+await test("CLV-221 a person chooses the next fix for partial work", async () => {
+  using bridge = fakeStepBridge({
+    decisions: [{ decision: "answered", answer: "  Add recovery first.\n" }],
+  });
+  const feedback = await reviewPartial({
+    cycleId: "run-1",
+    round: 1,
+    remaining: ["Add recovery.", "Verify restart."],
+  });
+  assert.equal(feedback, "  Add recovery first.\n");
+  assert.equal(bridge.requests.length, 1);
+  const request = bridge.requests[0];
+  assert.ok(request && request[0] === "waitForDecision");
+  assert.equal(request[1].gateId, "partial:run-1:1");
+  assert.equal(request[1].kind, "question");
+  assert.match(request[1].prompt, /- Add recovery\.\n- Verify restart\./);
+  assert.match(request[1].prompt, /empty answer to stop/);
+});
+
+await test("CLV-221 queued partial work records the merged pull request and remaining items", async () => {
+  const completed = {
+    kind: "completed" as const,
+    operationId: "partial-update",
+    receipt: null,
+    result: JSON.stringify({ number: 42, ticketStatus: "partial" }),
+  };
+  using bridge = fakeStepBridge({
+    effects: { "github partial-issue": [completed] },
+  });
+  const result = await queuePartial({
+    cycleId: "run-1",
+    round: 2,
+    issue: { owner: "acme", repository: "demo", number: 42 },
+    pullRequest: 7,
+    remaining: ["Add recovery.", "Verify restart."],
+  });
+  assert.deepEqual(result, completed);
+  assert.deepEqual(bridge.requests, [
+    [
+      "effect",
+      {
+        scope: {
+          phase: "pull-request",
+          operation: "github-partial-issue",
+          round: 2,
+        },
+        capability: "github",
+        method: "partial-issue",
+        target: "run-1",
+        units: 1,
+        payload: JSON.stringify({
+          owner: "acme",
+          repository: "demo",
+          number: 42,
+          pullRequest: 7,
+          remaining: ["Add recovery.", "Verify restart."],
+        }),
+      },
+    ],
+  ]);
+});
+
+await test("CLV-221 queued partial work preserves broker failures and budget refusals", async () => {
+  const input = {
+    cycleId: "run-1",
+    round: 4,
+    issue: { owner: "acme", repository: "demo", number: 42 },
+    pullRequest: 7,
+    remaining: ["Add recovery."],
+  };
+  for (const kind of [
+    "failed",
+    "stopped",
+    "blocked",
+    "cancelled",
+    "refused",
+    "unavailable",
+  ] as const) {
+    const failure = { kind, operationId: "update", reason: "update-failed" };
+    using bridge = fakeStepBridge({
+      effects: { "github partial-issue": [failure] },
+    });
+    assert.deepEqual(await queuePartial(input), failure);
+    assert.equal(bridge.requests.length, 1);
+  }
+  using bridge = fakeStepBridge({ effectLimit: 0 });
+  assert.deepEqual(await queuePartial(input), {
+    kind: "refused",
+    reason: "budget-exhausted",
+  });
+  assert.equal(bridge.spent, 0);
+});
+
+await test("CLV-221 the template develops a ticket through the public step bridge", async () => {
+  const completed = {
+    kind: "completed" as const,
+    operationId: "turn-1",
+    receipt: null,
+    result: JSON.stringify({ summary: "Implemented the ticket." }),
+  };
+  using bridge = fakeStepBridge({ turn: completed });
+  const result = await developTurn({
+    cycleId: "run-1",
+    repository: "main-checkout",
+    ticket: "# Fix the counter\n\nPreserve its value after restart.",
+    round: 1,
+    feedback: null,
+  });
+  assert.deepEqual(result, completed);
+  assert.equal(bridge.requests.length, 1);
+  const request = bridge.requests[0];
+  assert.ok(request && request[0] === "effect");
+  assert.deepEqual(request[1].scope, {
+    phase: "implement",
+    operation: "claude-turn",
+    round: 1,
+  });
+  assert.equal(request[1].capability, "claude");
+  assert.equal(request[1].method, "run-turn");
+  assert.equal(request[1].target, "run-1");
+  assert.equal(request[1].units, 1);
+  assert.match(request[1].payload, /Preserve its value after restart\./);
+  assert.match(request[1].payload, /main-checkout/);
+  assert.match(request[1].payload, /Do not push/);
+});
+
+await test("CLV-221 task text reaches the development turn without a ticket lookup", async () => {
+  using bridge = fakeStepBridge({});
+  await developTurn({
+    cycleId: "text-run",
+    repository: "main-checkout",
+    prompt: "Add an export for the parser.",
+    round: 1,
+    feedback: null,
+  });
+  assert.equal(bridge.requests.length, 1);
+  const request = bridge.requests[0];
+  assert.ok(request && request[0] === "effect");
+  assert.equal(request[1].method, "run-turn");
+  assert.match(request[1].payload, /Add an export for the parser\./);
+});
+
+for (const reason of ["check-failed", "merge-conflict", "ci-failed"]) {
+  await test(`CLV-221 a fix turn receives the full ${reason} output`, async () => {
+    const output =
+      "First diagnostic\n\n  expected: 4\n  actual: 3\nLast diagnostic\n";
+    using bridge = fakeStepBridge({});
+    await developTurn({
+      cycleId: "run-1",
+      repository: "main-checkout",
+      ticket: "Fix the counter.",
+      round: 2,
+      feedback: { reason, output, remaining: ["Add the restart test."] },
+    });
+    const request = bridge.requests[0];
+    assert.ok(request && request[0] === "effect");
+    assert.equal(request[1].scope.round, 2);
+    assert.match(request[1].payload, /Fix the counter\./);
+    assert.ok(request[1].payload.includes(reason));
+    assert.ok(request[1].payload.endsWith(output));
+    assert.match(request[1].payload, /- Add the restart test\./);
+    assert.match(request[1].payload, /round 2/);
+  });
+}
+
+await test("CLV-221 invalid turn inputs never dispatch a worker", async () => {
+  using bridge = fakeStepBridge({});
+  const common = {
+    cycleId: "run-1",
+    repository: "main-checkout",
+    round: 1,
+    feedback: null,
+  };
+  for (const task of [
+    {},
+    { ticket: "" },
+    { prompt: " \n" },
+    { ticket: "Ticket", prompt: "Task" },
+  ])
+    await assert.rejects(developTurn({ ...common, ...task }), {
+      message: "invalid-development-task",
+    });
+  for (const round of [0, -1, 1.5, 5, NaN, Infinity])
+    await assert.rejects(developTurn({ ...common, ticket: "Ticket", round }), {
+      message: "invalid-development-round",
+    });
+  assert.deepEqual(bridge.requests, []);
+});
+
+await test("CLV-221 the last allowed fix turn preserves a broker refusal", async () => {
+  using bridge = fakeStepBridge({ effectLimit: 0 });
+  const result = await developTurn({
+    cycleId: "run-1",
+    repository: "main-checkout",
+    ticket: "Fix the counter.",
+    round: 4,
+    feedback: { reason: "check-failed", output: "", remaining: [] },
+  });
+  assert.deepEqual(result, { kind: "refused", reason: "budget-exhausted" });
+  assert.equal(bridge.requests.length, 1);
+  assert.equal(bridge.spent, 0);
+});

package/templates/develop/develop.ts

@@ -0,0 +1,30 @@
+import type { CycleOutcome } from "cloving/workflows";
+import {
+  ticketInput,
+  type DevelopInput,
+  type DevelopFeedback,
+} from "./develop/report.ts";
+import { preparePull, labelTicket } from "./develop/pull.ts";
+import { developRound } from "./develop/round.ts";
+
+export async function develop(request: DevelopInput): Promise<CycleOutcome> {
+  "use workflow";
+  const input = ticketInput(request);
+  await preparePull(input.cycleId);
+  await labelTicket(input, { key: "start", round: 1 });
+  let endingRound = 1;
+  let feedback: DevelopFeedback | null = null;
+  let outcome: CycleOutcome | null = null;
+  for (let round = 1; round <= 4; round += 1) {
+    if (outcome === null) {
+      endingRound = round;
+      const next = await developRound({ input, round, feedback });
+      if ("kind" in next) outcome = next;
+      else feedback = next;
+    }
+  }
+  if (outcome === null) throw new Error("development-round-limit");
+  if (outcome.kind === "blocked")
+    await labelTicket(input, { key: "blocked", round: endingRound });
+  return outcome;
+}

package/templates/develop/template.json

@@ -0,0 +1,153 @@
+{
+  "version": 1,
+  "name": "develop",
+  "summary": "Develop a ticket or task with explicit choices for selection, acceptance, merge and partial work. The first option at each point is the hands-off default.",
+  "points": [
+    {
+      "id": "input",
+      "question": "What should the workflow develop?",
+      "options": [
+        {
+          "id": "ticket",
+          "label": "A ticket",
+          "summary": "Resolve a ticket through the configured ticket command.",
+          "change": "In develop.declaration.json, set workflow.input.fields to { \"ticket\": { \"type\": \"ticket\" } }. In develop.ts use ticketInput(request) from develop/report.ts to pass the resolved ticket text to the turn.",
+          "requires": {},
+          "needs": ["ticket-command"]
+        },
+        {
+          "id": "task-text",
+          "label": "A task text",
+          "summary": "Develop the submitted prompt without a ticket lookup.",
+          "change": "In develop.declaration.json, set workflow.input.fields to { \"prompt\": { \"type\": \"string\" } }. In develop.ts replace ticketInput with promptInput in the import and call. promptInput(request) passes the submitted text without a ticket lookup.",
+          "requires": {
+            "select": ["person"],
+            "partial": ["person"]
+          },
+          "needs": []
+        }
+      ]
+    },
+    {
+      "id": "select",
+      "question": "Who selects the next ticket or task?",
+      "options": [
+        {
+          "id": "queue",
+          "label": "The queue",
+          "summary": "Select a ready ticket through the configured next-ticket command.",
+          "change": "In develop.declaration.json, set workflow.queue to true (\"queue\": true).",
+          "requires": {
+            "input": ["ticket"]
+          },
+          "needs": ["next-command", "queue-interval"]
+        },
+        {
+          "id": "person",
+          "label": "A person",
+          "summary": "A person submits the ticket or task when starting a run.",
+          "change": "In develop.declaration.json, remove the workflow.queue field.",
+          "requires": {},
+          "needs": []
+        }
+      ]
+    },
+    {
+      "id": "accept",
+      "question": "Who accepts the developed work?",
+      "options": [
+        {
+          "id": "greptile",
+          "label": "Greptile at 5/5",
+          "summary": "Open or update the pull request and wait for Greptile to accept its commit at 5/5.",
+          "change": "In develop/accept.ts call reviewByAgent({ subject, reviewer: { kind: \"greptile\" } }). develop/round.ts opens or updates the pull request first and passes its immutable commit and target as subject. Declare github wait-review.",
+          "requires": {
+            "merge": ["person", "green"]
+          },
+          "needs": ["gh-login", "github-origin", "greptile-review"]
+        },
+        {
+          "id": "person",
+          "label": "A person",
+          "summary": "Wait for a person's approval of the immutable commit. Denial with feedback requests another bounded turn.",
+          "change": "In develop/accept.ts replace the import and call with reviewByPerson({ subject }). Remove reviewer and github wait-review from the declaration. develop/local.ts already uses reviewByPerson with the clean full commit from the worker report and the run target.",
+          "requires": {},
+          "needs": []
+        },
+        {
+          "id": "turn",
+          "label": "A review turn",
+          "summary": "Run the review profile and require its explicit accept verdict.",
+          "change": "In develop/accept.ts call reviewByAgent({ subject, reviewer: { kind: \"turn\", profile: \"review\" } }). For local merge replace reviewByPerson in develop/local.ts with that same call and its import. Declare claude run-turn:review and configure the review profile. Remove github wait-review from the declaration.",
+          "requires": {},
+          "needs": ["default-harness"]
+        }
+      ]
+    },
+    {
+      "id": "merge",
+      "question": "Who merges the accepted work?",
+      "options": [
+        {
+          "id": "green",
+          "label": "Cloving after the checks",
+          "summary": "Open or update a pull request and merge after acceptance, the beforeMerge check and CI. Pass result.output into a fix turn on failure.",
+          "change": "Call mergeWhenGreen({ pull, check: \"beforeMerge\" }) after acceptance. Use the pull returned by opening the pull request. Give the result.output to the next fix turn.",
+          "requires": {},
+          "needs": ["gh-login", "github-origin", "check-command"]
+        },
+        {
+          "id": "person",
+          "label": "A person approves Cloving's merge",
+          "summary": "Open or update a pull request, wait for merge approval, then run the beforeMerge check and CI before merging.",
+          "change": "In develop/round.ts replace the mergeWhenGreen import and call with mergeByPerson({ pull, check: \"beforeMerge\", round }). Use the pull returned by openPull. repair passes the result.output unchanged to the next fix turn.",
+          "requires": {},
+          "needs": ["gh-login", "github-origin", "check-command"]
+        },
+        {
+          "id": "local",
+          "label": "A person merges the local branch",
+          "summary": "Leave the accepted branch for a person to merge by hand. Do not push or open a pull request.",
+          "change": "In develop.ts import localRound as developRound from develop/local.ts. Remove the develop/pull.ts import, preparePull, both labelTicket calls and endingRound. The local round reviews the worker report commit, then returns the local branch outcome. Declare only claude capabilities and run-turn methods; include run-turn:review when selected. Do not push or open a pull request.",
+          "requires": {
+            "accept": ["person", "turn"],
+            "partial": ["person"]
+          },
+          "needs": []
+        }
+      ]
+    },
+    {
+      "id": "partial",
+      "question": "What happens when the work is partial?",
+      "options": [
+        {
+          "id": "queue",
+          "label": "Return the ticket to the queue",
+          "summary": "After merging partial work, record the remaining work and set cloving: ready for the first two partial runs. Set cloving: blocked from the third. Stop a run after three fix rounds.",
+          "change": "After a merged result, call protectedEffect with capability: \"github\", method: \"partial-issue\", and a payload containing owner, repository, number, pullRequest and remaining. Use an explicit scope with phase, operation and round. The GitHub worker records the partial run and applies ready or blocked.",
+          "requires": {
+            "input": ["ticket"],
+            "select": ["queue"],
+            "merge": ["person", "green"]
+          },
+          "needs": [
+            "gh-login",
+            "github-origin",
+            "ticket-command",
+            "next-command",
+            "queue-interval"
+          ]
+        },
+        {
+          "id": "person",
+          "label": "A person decides",
+          "summary": "Ask what to do with partial work. Use the answer as feedback for a bounded continuation, or stop and leave it for the person.",
+          "change": "For a pull-request workflow, in develop/round.ts import partialChoice from develop/partial-choice.ts. Immediately after developReport, call partialChoice({ input, round, report }) and return any non-null result. develop/local.ts already does this. The helper calls waitForDecision({ gateId: partialGateId, kind: \"question\", prompt: partialQuestion }); an explicit answer feeds the next bounded turn and an empty answer stops.",
+          "requires": {},
+          "needs": []
+        }
+      ]
+    }
+  ]
+}

package/dist/src/chats/analysis-batches.d.ts

@@ -1,42 +0,0 @@
-import type { AnalysisResult } from "./analysis-contract.ts";
-import { type AnalysisSnapshot } from "./analysis-input.ts";
-import { type AnalysisBatchContext } from "./analysis-prompt.ts";
-export interface AnalysisBatchPosition {
-    readonly nextRecordIndex: number;
-    readonly completedBatchCount: number;
-    readonly previousResult: AnalysisResult | null;
-}
-export interface AnalysisBatch {
-    readonly kind: "batch";
-    readonly batchIndex: number;
-    readonly firstRecordIndex: number;
-    readonly nextRecordIndex: number;
-    readonly totalRecords: number;
-    readonly snapshot: AnalysisSnapshot;
-    readonly prompt: string;
-    readonly launchBytes: number;
-    readonly adapterDocument: string;
-    readonly context: AnalysisBatchContext;
-}
-export type AnalysisBatchPreparation = AnalysisBatch | {
-    readonly kind: "refused";
-    readonly code: "analysis-input-refused" | "analysis-too-large" | "analysis-batch-limit";
-};
-export declare const analysisCaptureBytes = 52428800;
-export declare function analysisBatchData(batch: AnalysisBatch, capture: {
-    readonly digest: string;
-    readonly snapshot?: AnalysisSnapshot;
-}): {
-    snapshot: AnalysisSnapshot;
-    context?: never;
-    batch?: never;
-} | {
-    snapshot: AnalysisSnapshot;
-    context: AnalysisBatchContext;
-    batch: {
-        batchIndex: number;
-        nextRecordIndex: number;
-        capturedDigest: string;
-    };
-};
-export declare function prepareAnalysisBatch(snapshot: AnalysisSnapshot, position: AnalysisBatchPosition): AnalysisBatchPreparation;