cloving 1.3.0 → 1.5.0

package/templates/idea-to-issue/template.json

@@ -0,0 +1,81 @@
+{
+  "version": 1,
+  "name": "idea-to-issue",
+  "summary": "Research an idea, check its draft, post a private-text-checked issue and choose what happens next. The first option at every point is the default.",
+  "points": [
+    {
+      "id": "review",
+      "question": "Who checks the draft?",
+      "options": [
+        {
+          "id": "turn",
+          "label": "A review turn corrects the draft",
+          "summary": "Compare the research with the code and correct the draft file.",
+          "change": "Keep reviewByTurn as checkDraft in idea-to-issue.ts.",
+          "requires": {},
+          "needs": ["default-harness"]
+        },
+        {
+          "id": "person",
+          "label": "I read the draft",
+          "summary": "Capture the draft through a protected effect and show its text to reviewByPerson. Post only if the captured digest still matches.",
+          "change": "Import reviewDraftByPerson as checkDraft from idea-to-issue/review.ts in idea-to-issue.ts. Add capture-draft to methods.github. Set selection.review to person in idea-to-issue/scenarios.ts.",
+          "requires": {},
+          "needs": []
+        }
+      ]
+    },
+    {
+      "id": "post",
+      "question": "Who approves posting the issue?",
+      "options": [
+        {
+          "id": "privacy",
+          "label": "Post after the privacy check",
+          "summary": "Post after the existing privacy check; retain any digest from a person review.",
+          "change": "Keep postAfterPrivacy as postDraft in idea-to-issue.ts. Configure privateTexts with at least one nonblank item.",
+          "requires": {},
+          "needs": ["gh-login", "github-origin", "private-texts"]
+        },
+        {
+          "id": "person",
+          "label": "I approve the post",
+          "summary": "Capture and show the draft in an approval gate before the checked post. Preserve both reviewed digests when both gates are selected.",
+          "change": "Import postByPerson as postDraft from idea-to-issue/post-person.ts in idea-to-issue.ts. Add capture-draft to methods.github. Set selection.post to person in idea-to-issue/scenarios.ts. Configure privateTexts with at least one nonblank item.",
+          "requires": {},
+          "needs": ["gh-login", "github-origin", "private-texts"]
+        }
+      ]
+    },
+    {
+      "id": "next",
+      "question": "What happens to the posted issue?",
+      "options": [
+        {
+          "id": "develop",
+          "label": "Hand the issue to develop",
+          "summary": "Start the repository-declared develop workflow. If starting it fails, put the issue in the queue.",
+          "change": "Keep handoffIssue as nextIssue in idea-to-issue.ts. Set targetWorkflow in idea-to-issue/next.ts and workflow.handoffs in idea-to-issue.declaration.json to the same repository-declared workflow ID. The default is develop.",
+          "requires": {},
+          "needs": ["gh-login", "github-origin"]
+        },
+        {
+          "id": "queue",
+          "label": "Put the issue in the queue",
+          "summary": "Add cloving: ready without starting a develop workflow.",
+          "change": "Import queueIssue as nextIssue from idea-to-issue/queue.ts in idea-to-issue.ts. Set workflow.handoffs to [] and selection.next to queue in idea-to-issue/scenarios.ts. No develop workflow is required.",
+          "requires": {},
+          "needs": ["gh-login", "github-origin"]
+        },
+        {
+          "id": "nothing",
+          "label": "Do nothing",
+          "summary": "Leave the posted issue for a person.",
+          "change": "Import leaveIssue as nextIssue from idea-to-issue/leave.ts in idea-to-issue.ts. Set workflow.handoffs to [], remove label from methods.github and set selection.next to nothing in idea-to-issue/scenarios.ts. No develop workflow is required.",
+          "requires": {},
+          "needs": []
+        }
+      ]
+    }
+  ]
+}

package/templates/review-day/README.md

@@ -0,0 +1,97 @@
+# Review day
+
+Copy the template into your private workflow folder, named by `workflows.folder`,
+with `cloving templates copy review-day`. This operator step happens outside the
+application repository. Inspect `cloving templates show review-day --json`, choose
+the two options, apply their import and declaration edits, update `selection` in
+`review-day/scenarios.ts`, then run `cloving workflows test review-day`.
+
+The default schedule runs every 86400 seconds with `{}` input. The scheduler
+skips a slot while the review runs, including its decision and child-run waits.
+Use the scheduled copy as the single daily reviewer; avoid starting parallel
+manual copies. A failed command or invalid JSON blocks the run before any turn,
+report or issue. Unavailable metrics stay unavailable, never zero.
+
+Set `CLOVING_COMMANDS` to JSON argv arrays for these three read-only commands:
+
+```json
+{
+  "report": [
+    "<absolute-cloving-executable>",
+    "report",
+    "--since",
+    "24",
+    "--json"
+  ],
+  "reviews": [
+    "<absolute-gh-executable>",
+    "issue",
+    "list",
+    "--state",
+    "all",
+    "--label",
+    "cloving: review",
+    "--limit",
+    "7",
+    "--json",
+    "number,url,body,createdAt"
+  ],
+  "improvements": ["<absolute-improvements-wrapper>"]
+}
+```
+
+Replace the executable placeholders with absolute paths (`command -v cloving`,
+`command -v gh`, and your wrapper's absolute path). Bare executable names are
+refused by command configuration.
+
+`report` runs `cloving report --since 24 --json`. `reviews` supplies the last seven
+review issues as an array, newest first. `improvements` must read all open issues
+with `cloving: improvement` and return an array with `number`, `url`, `body` and
+the stable `loop` identifier for each issue. Use a local read-only wrapper to
+extract that identifier from its body; include the metric, before measurement,
+change date, check date and after evidence in the body. Missing loop identifiers
+prevent further proposals until clarified. Never truncate the open-issue list.
+
+Before enabling the schedule, add a turn profile for this workflow with
+`maxBudgetUsd` and read-only `allowedTools`. Configure a
+Claude profile `reviewDay` with `workflows: ["review-day"]`, `maxBudgetUsd: 1` and
+`allowedTools: ["Read", "Glob", "Grep"]`. Change the turn helper's method and its
+declaration entry from `run-turn` to `run-turn:reviewDay` to use that profile.
+The default unprofiled method does not apply the named profile's budget. The two
+turns return JSON in their final summary; they need no write or shell tools.
+Set the budget to your chosen per-turn limit.
+Both turns must keep their complete serialized JSON within 12000 characters,
+including escaping, below the worker's 16000-character summary limit. Condense
+repeated prose while retaining every required section, evidence link and removal
+reason. Oversized or incomplete JSON blocks the run before posting.
+
+After the turns, including a failed turn or invalid report, `github discard`
+removes this run's temporary worktree and branch before posting or waiting for a
+decision. Failed cleanup blocks the run. Retain `github` in capabilities and
+`discard` in methods for all options, including `post.result` with `next.nothing`.
+
+Analyze and critique use the same nine rules and all three command outputs.
+Critique is a separate turn. It removes unsupported claims, lists removals,
+compares every open improvement before and after its change, and gives keep,
+reverse or continue at the check date. The workflow also removes proposals
+without evidence or for a loop with an open improvement, caps the list at three,
+and refuses additions or rewrites by the critique. The report has the fixed
+Facts, Went well, Went badly, The constraint, Improvements in progress, Proposals,
+Watch list and Removed by the critique sections.
+
+Posting requires nonblank `privateTexts` and uses the existing privacy check on
+the exact rendered report. `post.result` keeps the `report` field in the durable
+SDK run return value. `cloving status` shows completion metadata and does not
+display that field.
+With proposals, one question accepts a single number or `none`. A denial, expiry
+or ambiguous answer starts no child. `next.nothing` records the choice and stops.
+
+For `next.idea`, copy `idea-to-issue` into the same private workflow folder and
+select its **next.nothing** option. Its default starts development and its queue
+option adds `cloving: ready`; neither is suitable for review proposals. The child
+must only write the ticket, keep the proposal's evidence, loop, metric and check
+date, and leave queue selection to the operator. The review reads the issue
+number from its `issue-N` outcome after `waitForRun`, then adds only
+`cloving: improvement` to that new issue. Earlier issues and labels stay untouched.
+A later review reports the verdict; applying or reversing a change remains an
+operator decision.

package/templates/review-day/review-day/critique.ts

@@ -0,0 +1,58 @@
+import type { ReviewFacts } from "./facts.ts";
+import type { Proposal, ReviewReport } from "./report.ts";
+
+function removal(
+  proposal: Proposal,
+  context: {
+    readonly draft: ReviewReport;
+    readonly facts: ReviewFacts;
+    readonly accepted: readonly Proposal[];
+  },
+): string | null {
+  const original = context.draft.proposals.find(
+    (item) => item.id === proposal.id,
+  );
+  if (JSON.stringify(original) !== JSON.stringify(proposal))
+    return "not an unchanged analyzed proposal";
+  if (
+    proposal.evidence.length === 0 ||
+    proposal.evidence.some((link) => !/^https?:\/\/\S+$/.test(link))
+  )
+    return "missing evidence";
+  if (
+    context.facts.improvements.some(
+      (issue) =>
+        typeof issue["loop"] !== "string" ||
+        issue["loop"].trim() === "" ||
+        issue["loop"].trim() === proposal.loop.trim(),
+    )
+  )
+    return "open improvement";
+  if (context.accepted.some((item) => item.id === proposal.id))
+    return "duplicate proposal";
+  return context.accepted.length >= 3 ? "three proposal limit" : null;
+}
+
+export function enforceCritique(
+  draft: ReviewReport,
+  review: {
+    readonly critique: ReviewReport;
+    readonly facts: ReviewFacts;
+  },
+): ReviewReport {
+  const proposals: Proposal[] = [];
+  const removed = review.critique.removed.slice();
+  for (const proposal of review.critique.proposals) {
+    const reason = removal(proposal, {
+      draft,
+      facts: review.facts,
+      accepted: proposals,
+    });
+    if (reason === null) proposals.push(proposal);
+    else removed.push(`${proposal.id}: ${reason}`);
+  }
+  for (const proposal of draft.proposals)
+    if (!review.critique.proposals.some((item) => item.id === proposal.id))
+      removed.push(`${proposal.id}: removed by critique`);
+  return Object.assign({}, review.critique, { proposals, removed });
+}

package/templates/review-day/review-day/decision.ts

@@ -0,0 +1,29 @@
+import { waitForDecision } from "cloving/workflows/steps/wait-for-decision";
+import type { ReviewInput } from "./facts.ts";
+import { proposalText, type Proposal } from "./report.ts";
+
+export async function chooseProposal(
+  input: ReviewInput,
+  proposals: readonly Proposal[],
+): Promise<Proposal | null> {
+  if (proposals.length === 0) return null;
+  const result = await waitForDecision({
+    gateId: `review-day:${input.cycleId}`,
+    kind: "question",
+    prompt: [
+      "Approve at most one proposal: answer its number, or none. This authorizes only an idea-to-issue handoff, never a code or settings change.",
+    ]
+      .concat(
+        proposals.map(
+          (proposal, index) =>
+            `${String(index + 1)}. ${proposalText(proposal)}`,
+        ),
+      )
+      .join("\n\n"),
+  });
+  if (!["approved", "answered"].includes(result.decision)) return null;
+  const answer = result.answer?.trim() ?? "";
+  return /^[1-3]$/.test(answer)
+    ? (proposals.at(Number(answer) - 1) ?? null)
+    : null;
+}

package/templates/review-day/review-day/facts.ts

@@ -0,0 +1,69 @@
+import type { ProtectedResult } from "cloving/workflows";
+import { runCommand } from "cloving/workflows/steps/run-command";
+
+export interface ReviewInput {
+  readonly cycleId: string;
+  readonly input: Readonly<Record<string, never>>;
+}
+
+export function effectText(result: ProtectedResult): string {
+  if (result.kind !== "completed")
+    throw new Error(result.reason ?? result.kind);
+  if (result.result === null) throw new Error("missing-review-result");
+  return result.result;
+}
+
+export function fields(value: unknown): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    throw new Error("invalid-review-facts");
+  return Object.fromEntries(Object.entries(value));
+}
+
+function commandJson(result: ProtectedResult): unknown {
+  const text = effectText(result);
+  try {
+    const value: unknown = JSON.parse(text);
+    return value;
+  } catch {
+    throw new Error("invalid-review-facts");
+  }
+}
+
+function issues(value: unknown): readonly Record<string, unknown>[] {
+  if (!Array.isArray(value)) throw new Error("invalid-review-facts");
+  return value.map((issue: unknown) => fields(issue));
+}
+
+export async function reviewFacts() {
+  const input: Readonly<Record<string, never>> = {};
+  const report = fields(
+    commandJson(
+      await runCommand({
+        scope: { phase: "review-day", operation: "report", round: 1 },
+        name: "report",
+        input: input,
+      }),
+    ),
+  );
+  const reviews = issues(
+    commandJson(
+      await runCommand({
+        scope: { phase: "review-day", operation: "reviews", round: 1 },
+        name: "reviews",
+        input: input,
+      }),
+    ),
+  );
+  const improvements = issues(
+    commandJson(
+      await runCommand({
+        scope: { phase: "review-day", operation: "improvements", round: 1 },
+        name: "improvements",
+        input: input,
+      }),
+    ),
+  );
+  return { report, reviews, improvements };
+}
+
+export type ReviewFacts = Awaited<ReturnType<typeof reviewFacts>>;

package/templates/review-day/review-day/label.ts

@@ -0,0 +1,29 @@
+import { protectedEffect } from "cloving/workflows/steps/protected-effect";
+import { effectText, type ReviewInput } from "./facts.ts";
+
+export async function labelIssue(
+  input: ReviewInput,
+  issue: { readonly number: number; readonly label: string },
+) {
+  effectText(
+    await protectedEffect({
+      capability: "github",
+      method: "label",
+      target: input.cycleId,
+      units: 1,
+      scope: {
+        phase: "review-day",
+        operation:
+          issue.label === "cloving: review"
+            ? "label-review"
+            : "label-improvement",
+        round: 1,
+      },
+      payload: JSON.stringify({
+        number: issue.number,
+        add: [issue.label],
+        remove: [],
+      }),
+    }),
+  );
+}

package/templates/review-day/review-day/next.ts

@@ -0,0 +1,28 @@
+import { handoff } from "cloving/workflows/steps/handoff";
+import { waitForRun } from "cloving/workflows/steps/wait-for-run";
+import type { ReviewInput } from "./facts.ts";
+import { proposalText, type Proposal } from "./report.ts";
+import { labelIssue } from "./label.ts";
+
+export async function handoffProposal(
+  input: ReviewInput,
+  proposal: Proposal,
+): Promise<void> {
+  const runId = await handoff({
+    workflowId: "idea-to-issue",
+    input: { idea: proposalText(proposal) },
+  });
+  const outcome = await waitForRun({ runId, maximumWaitSeconds: 86400 });
+  const match =
+    outcome.promotionId === null
+      ? null
+      : /^issue-([1-9]\d*)$/.exec(outcome.promotionId);
+  const number = Number(match?.[1]);
+  if (
+    outcome.kind !== "handoff_requested" ||
+    !Number.isSafeInteger(number) ||
+    number < 1
+  )
+    throw new Error("improvement-issue-missing");
+  await labelIssue(input, { number, label: "cloving: improvement" });
+}

package/templates/review-day/review-day/post.ts

@@ -0,0 +1,27 @@
+import { protectedEffect } from "cloving/workflows/steps/protected-effect";
+import { effectText, fields, type ReviewInput } from "./facts.ts";
+import { labelIssue } from "./label.ts";
+
+export async function postAfterPrivacy(
+  input: ReviewInput,
+  report: string,
+): Promise<void> {
+  const result = fields(
+    JSON.parse(
+      effectText(
+        await protectedEffect({
+          capability: "github",
+          method: "create-issue",
+          target: input.cycleId,
+          units: 1,
+          scope: { phase: "review-day", operation: "post", round: 1 },
+          payload: JSON.stringify({ text: report }),
+        }),
+      ),
+    ),
+  );
+  const number = result["number"];
+  if (typeof number !== "number" || !Number.isSafeInteger(number) || number < 1)
+    throw new Error("invalid-review-issue");
+  await labelIssue(input, { number, label: "cloving: review" });
+}

package/templates/review-day/review-day/report.ts

@@ -0,0 +1,98 @@
+import { fields } from "./facts.ts";
+
+export interface Proposal {
+  readonly id: string;
+  readonly loop: string;
+  readonly text: string;
+  readonly evidence: readonly string[];
+}
+
+export interface ReviewReport {
+  readonly facts: string;
+  readonly wentWell: string;
+  readonly wentBadly: string;
+  readonly constraint: string;
+  readonly improvementsInProgress: string;
+  readonly proposals: readonly Proposal[];
+  readonly watchList: string;
+  readonly removed: readonly string[];
+}
+
+function text(value: unknown): string {
+  if (typeof value !== "string" || value.trim() === "")
+    throw new Error("invalid-review-report");
+  return value;
+}
+
+function texts(value: unknown): readonly string[] {
+  if (!Array.isArray(value)) throw new Error("invalid-review-report");
+  return value.map((item: unknown) => text(item));
+}
+
+function proposal(value: unknown): Proposal {
+  const item = fields(value);
+  return {
+    id: text(item["id"]),
+    loop: text(item["loop"]),
+    text: text(item["text"]),
+    evidence: texts(item["evidence"]),
+  };
+}
+
+export function proposalText(proposal: Proposal): string {
+  const heading = `Loop: ${proposal.loop}\n\n`;
+  const missing = proposal.evidence.filter(
+    (link) => !proposal.text.includes(link),
+  );
+  const links =
+    missing.length === 0
+      ? ""
+      : "\n\nEvidence:\n" + missing.map((link) => `- ${link}`).join("\n");
+  return (
+    (proposal.text.startsWith(heading)
+      ? proposal.text
+      : heading + proposal.text) + links
+  );
+}
+
+export function parseReport(value: unknown): ReviewReport {
+  const item = fields(value);
+  const proposals = item["proposals"];
+  if (!Array.isArray(proposals)) throw new Error("invalid-review-report");
+  return {
+    facts: text(item["facts"]),
+    wentWell: text(item["wentWell"]),
+    wentBadly: text(item["wentBadly"]),
+    constraint: text(item["constraint"]),
+    improvementsInProgress: text(item["improvementsInProgress"]),
+    proposals: proposals.map((item: unknown) => proposal(item)),
+    watchList: text(item["watchList"]),
+    removed: texts(item["removed"]),
+  };
+}
+
+export function renderReport(report: ReviewReport): string {
+  const sections: readonly (readonly [string, string])[] = [
+    ["Facts", report.facts],
+    ["Went well", report.wentWell],
+    ["Went badly", report.wentBadly],
+    ["The constraint", report.constraint],
+    ["Improvements in progress", report.improvementsInProgress],
+    [
+      "Proposals",
+      report.proposals
+        .map(
+          (proposal, index) =>
+            `${String(index + 1)}. ${proposalText(proposal)}`,
+        )
+        .join("\n\n") || "None.",
+    ],
+    ["Watch list", report.watchList],
+    ["Removed by the critique", report.removed.join("\n\n") || "None."],
+  ];
+  const text =
+    "# Daily loop review\n\n" +
+    sections.map(([heading, body]) => `## ${heading}\n\n${body}`).join("\n\n");
+  if (text.length > 65536) throw new Error("review-report-too-large");
+  return text;
+}

package/templates/review-day/review-day/rules.ts

@@ -0,0 +1,12 @@
+export const reviewRules = [
+  "Real changes only: a problem must be marked outside its 7-day band or stay on one side of the median for 3 days or more. A value inside the band gets no proposal. Unavailable or short history is not zero or evidence of a problem.",
+  "One constraint: name the one step that limits throughput most, with its share of wait time or lost runs. Address that step first; use it better before adding capacity.",
+  "Paired metrics: read merged tickets with reverted or reopened work and main CI failures; busy lanes with flaky failures and fix rounds; faster CI with escaped faults. Never improve a value at the cost of its quality pair.",
+  "Evidence: each problem needs 2 or more occurrences in the window or a trend over 7 days, with links to runs, pull requests or CI jobs derived from the facts. Put a single event on the watch list. Remove claims without evidence; never invent values, links or trends.",
+  "At most 3 proposals. Each text contains the problem and evidence, a hypothesis, one change and its expected effect, a metric and a check date 3 to 7 days later, cost, how to reverse it and the result that shows failure. Prefer small reversible changes.",
+  "One change for each loop at a time: no proposal for a loop with an open improvement. If an open improvement's loop is unknown, propose no changes until it is identified.",
+  "Keep what works: list what went well and must not break.",
+  "Utilization: never propose keeping lanes, CI runners or the host busy above about 80% of the time.",
+  "The system, not a person: describe the system condition that allowed the problem; do not blame individuals.",
+  "Improvements in progress: for every open improvement compare its metric before and after the change, and at its check date give the verdict keep, reverse or continue with evidence. Unknown measurements mean continue, never a fabricated success.",
+];

package/templates/review-day/review-day/scenarios.ts

@@ -0,0 +1,76 @@
+import type { ScenarioRequest } from "cloving/workflows/testing";
+
+export const selection = { post: "privacy", next: "idea" };
+export const input = { cycleId: "review-1", input: {} };
+export const report = {
+  facts:
+    "| Metric | Value | Median | Band | Mark |\n| --- | --- | --- | --- | --- |\n| merge minutes | 30 | 10 | 5–15 | outside |",
+  wentWell: "Main CI passed; preserve that quality.",
+  wentBadly: "Merge checks waited twice.",
+  constraint: "Merge checks account for 70% of wait time.",
+  improvementsInProgress: "None.",
+  proposals: [],
+  watchList: "One escaped fault; watch it.",
+  removed: [],
+};
+
+export const proposal = {
+  id: "merge-time",
+  loop: "merge",
+  text: "Loop: merge\n\nMerge checks timed out twice: https://github.com/acme/demo/actions/runs/10 and https://github.com/acme/demo/actions/runs/11. Hypothesis: the time limit is too short. One change: give the local merge check time factor 3. Expected effect: fewer timeouts; preserve main CI first-pass share. Check merge timeouts on 2026-11-06 (five days later). Cost: longer waits on real faults. Reverse by restoring factor 1. Failure: timeouts persist or main CI first-pass share drops.",
+  evidence: [
+    "https://github.com/acme/demo/actions/runs/10",
+    "https://github.com/acme/demo/actions/runs/11",
+  ],
+};
+
+export function completed(value: unknown = {}) {
+  return {
+    kind: "completed" as const,
+    operationId: "operation",
+    receipt: null,
+    result: JSON.stringify(value),
+  };
+}
+
+export function effects() {
+  return {
+    "command run:report": [
+      completed({ metrics: { mergeMinutes: { value: 30, mark: "outside" } } }),
+    ],
+    "command run:reviews": [completed([])],
+    "command run:improvements": [completed([])],
+    "claude run-turn": [
+      completed({ summary: JSON.stringify(report) }),
+      completed({ summary: JSON.stringify(report) }),
+    ],
+    "github create-issue": [
+      completed({ number: 9, url: "https://github.com/acme/demo/issues/9" }),
+    ],
+    "github discard": [completed()],
+    "github label": [completed(), completed()],
+  };
+}
+
+export function methods(requests: readonly ScenarioRequest[]) {
+  return requests.map((request) =>
+    request[0] === "effect" ? request[1].method : request[0],
+  );
+}
+
+export function proposalEffects() {
+  const draft = {
+    ...report,
+    proposals: [
+      { ...proposal, id: "first", text: "First measured change." },
+      proposal,
+    ],
+  };
+  return {
+    ...effects(),
+    "claude run-turn": [
+      completed({ summary: JSON.stringify(draft) }),
+      completed({ summary: JSON.stringify(draft) }),
+    ],
+  };
+}