cloving 1.3.0 → 1.4.0

package/dist/tools/workflow-candidate-source.js

@@ -1,7 +1,9 @@
+import { passiveCandidateModule, workflowShape, } from "./workflow-candidate-shape.js";
 import ts from "typescript";
 import { dirname, relative, sep } from "node:path";
 import { candidateProgram, resolvedSymbol, } from "./workflow-candidate-program.js";
-import { protectedEffectFact, passiveCandidateModule, unsupportedCandidateNode, workflowShape, } from "./workflow-candidate-syntax.js";
+import { protectedEffectFact, commandWaitCall, unsupportedCandidateNode, } from "./workflow-candidate-syntax.js";
+import { literalField } from "./workflow-candidate-fields.js";
 import { sourceEffectNodes } from "./workflow-source-effects.js";
 import { candidateEffectTotals } from "./workflow-candidate-counts.js";
 import { helperEffectTotals } from "./workflow-candidate-helper-counts.js";
@@ -32,11 +34,14 @@ function sourceFacts(symbols) {
     const { source } = symbols;
     const imports = [];
     const effects = [];
+    const commandWaits = [];
     const unsupportedForms = [];
     function visit(node) {
         const imported = sourceImport(node);
         if (imported)
             imports.push(imported);
+        if (ts.isCallExpression(node) && commandWaitCall(node, symbols))
+            commandWaits.push(literalField(node.arguments[0], "name"));
         const effect = protectedEffectFact(node, symbols);
         if (effect)
             effects.push(effect);
@@ -47,6 +52,7 @@ function sourceFacts(symbols) {
     visit(source);
     return {
         imports,
+        ...(commandWaits.length === 0 ? {} : { commandWaits }),
         effects,
         directEffects: sourceEffectNodes(source, {
             checker: symbols.checker,
@@ -99,6 +105,11 @@ export function analyzeWorkflowCandidate(text, installed = {}) {
             subpath: "cloving/workflows/steps/handoff",
             name: "handoff",
         }),
+        commandWaitSymbol: protectedHelper(modules, {
+            checker,
+            subpath: "cloving/workflows/steps/wait-for-command",
+            name: "waitForCommand",
+        }),
         commandSymbol: protectedHelper(modules, {
             checker,
             subpath: "cloving/workflows/steps/run-command",
@@ -154,6 +165,9 @@ function combineFacts(input) {
     const { localSources, facts } = input;
     return {
         localSources,
+        ...(facts.some((entry) => entry.commandWaits !== undefined)
+            ? { commandWaits: facts.flatMap((entry) => entry.commandWaits ?? []) }
+            : {}),
         imports: facts.flatMap((entry) => entry.imports),
         effects: facts.flatMap((entry) => entry.effects),
         directEffects: facts.flatMap((entry) => entry.directEffects),

package/dist/tools/workflow-candidate-syntax.d.ts

@@ -5,6 +5,7 @@ export interface CandidateSymbols {
     readonly source: ts.SourceFile;
     readonly protectedSymbol: ts.Symbol | undefined;
     readonly handoffSymbol: ts.Symbol | undefined;
+    readonly commandWaitSymbol?: ts.Symbol | undefined;
     readonly commandSymbol: ts.Symbol | undefined;
     readonly reviewSymbol: ts.Symbol | undefined;
     readonly mergeSymbols: readonly ts.Symbol[];
@@ -12,10 +13,9 @@ export interface CandidateSymbols {
 export declare function protectedCall(node: ts.Node, symbols: CandidateSymbols): node is ts.CallExpression;
 export declare function handoffCall(node: ts.CallExpression, symbols: CandidateSymbols): boolean;
 export declare function commandCall(node: ts.CallExpression, symbols: CandidateSymbols): boolean;
+export declare function commandWaitCall(node: ts.CallExpression, symbols: CandidateSymbols): boolean;
 export declare function reviewCall(node: ts.CallExpression, symbols: CandidateSymbols): boolean;
 export declare function helperCall(node: ts.CallExpression, symbols: CandidateSymbols): boolean;
 export declare function mergeCall(node: ts.CallExpression, symbols: CandidateSymbols): boolean;
 export declare function protectedEffectFact(node: ts.Node, symbols: CandidateSymbols): CandidateEffect | undefined;
 export declare function unsupportedCandidateNode(node: ts.Node, symbols: CandidateSymbols): boolean;
-export declare function workflowShape(source: ts.SourceFile): boolean;
-export declare function passiveCandidateModule(source: ts.SourceFile, kind?: "workflow" | "helper"): boolean;

package/dist/tools/workflow-candidate-syntax.js

@@ -1,7 +1,7 @@
 import ts from "typescript";
 import { resolvedSymbol } from "./workflow-candidate-program.js";
 import { referenceSymbol } from "./workflow-source-effects.js";
-import { invalidFields, literalField, propertyInitializer, } from "./workflow-candidate-fields.js";
+import { invalidFields, literalField, propertyInitializer, propertyName, } from "./workflow-candidate-fields.js";
 export function protectedCall(node, symbols) {
     if (!ts.isCallExpression(node) || !ts.isIdentifier(node.expression))
         return false;
@@ -11,6 +11,7 @@ export function protectedCall(node, symbols) {
             symbols.protectedSymbol,
             symbols.handoffSymbol,
             symbols.commandSymbol,
+            symbols.commandWaitSymbol,
             symbols.reviewSymbol,
             ...symbols.mergeSymbols,
         ].includes(symbol));
@@ -26,6 +27,10 @@ export function commandCall(node, symbols) {
     const symbol = symbols.commandSymbol;
     return symbol !== undefined && calledSymbol(node, symbols) === symbol;
 }
+export function commandWaitCall(node, symbols) {
+    const symbol = symbols.commandWaitSymbol;
+    return symbol !== undefined && calledSymbol(node, symbols) === symbol;
+}
 export function reviewCall(node, symbols) {
     const symbol = symbols.reviewSymbol;
     return symbol !== undefined && calledSymbol(node, symbols) === symbol;
@@ -40,7 +45,7 @@ export function mergeCall(node, symbols) {
 export function protectedEffectFact(node, symbols) {
     if (!protectedCall(node, symbols))
         return undefined;
-    if (handoffCall(node, symbols))
+    if (handoffCall(node, symbols) || commandWaitCall(node, symbols))
         return undefined;
     const argument = node.arguments[0];
     if (!argument || !ts.isObjectLiteralExpression(argument))
@@ -81,6 +86,7 @@ function escapedHelper(node, symbols) {
             symbols.protectedSymbol,
             symbols.handoffSymbol,
             symbols.commandSymbol,
+            symbols.commandWaitSymbol,
             symbols.reviewSymbol,
             ...symbols.mergeSymbols,
         ].includes(symbol))
@@ -115,9 +121,22 @@ function invalidRequest(node, symbols) {
         ? propertyInitializer(argument, "reviewer")
         : undefined;
     return (invalidFields(argument) ||
-        (reviewer !== undefined &&
-            ts.isObjectLiteralExpression(reviewer) &&
-            invalidFields(reviewer)));
+        invalidCommandWaitFields(node, symbols) ||
+        invalidReviewer(reviewer));
+}
+function invalidReviewer(reviewer) {
+    return (reviewer !== undefined &&
+        ts.isObjectLiteralExpression(reviewer) &&
+        invalidFields(reviewer));
+}
+function invalidCommandWaitFields(node, symbols) {
+    if (!commandWaitCall(node, symbols))
+        return false;
+    const argument = node.arguments[0];
+    return (!!argument &&
+        ts.isObjectLiteralExpression(argument) &&
+        argument.properties.some((entry) => entry.name &&
+            !["name", "input"].includes(propertyName(entry.name) ?? "")));
 }
 function workflowBodyCall(node) {
     let child = node;
@@ -172,92 +191,3 @@ export function unsupportedCandidateNode(node, symbols) {
     ];
     return checks.some(Boolean);
 }
-export function workflowShape(source) {
-    const exported = source.statements.filter((node) => ts.isFunctionDeclaration(node) &&
-        (ts.getModifiers(node) ?? []).some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword));
-    const candidate = exported[0];
-    if (exported.length !== 1 ||
-        !candidate ||
-        !ts.isFunctionDeclaration(candidate))
-        return false;
-    if (!workflowFunction(candidate))
-        return false;
-    const directives = [];
-    function visit(node) {
-        if (ts.isStringLiteral(node) && node.text === "use workflow")
-            directives.push(node);
-        ts.forEachChild(node, visit);
-    }
-    visit(source);
-    return directives.length === 1;
-}
-function workflowFunction(candidate) {
-    if (!candidate.name || !candidate.body || candidate.asteriskToken)
-        return false;
-    const modifiers = ts.getModifiers(candidate) ?? [];
-    if (!modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword) ||
-        modifiers.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword))
-        return false;
-    const first = candidate.body.statements[0];
-    return first !== undefined && workflowDirective(first);
-}
-function workflowDirective(node) {
-    return (ts.isExpressionStatement(node) &&
-        ts.isStringLiteral(node.expression) &&
-        node.expression.text === "use workflow");
-}
-function unwrappedInitializer(node) {
-    if (ts.isParenthesizedExpression(node) ||
-        ts.isAsExpression(node) ||
-        ts.isSatisfiesExpression(node) ||
-        ts.isTypeAssertionExpression(node))
-        return node.expression;
-    return undefined;
-}
-function passiveCompound(node) {
-    if (ts.isArrayLiteralExpression(node))
-        return node.elements.every((element) => ts.isOmittedExpression(element) || passiveInitializer(element));
-    if (ts.isObjectLiteralExpression(node))
-        return node.properties.every((property) => ts.isPropertyAssignment(property) &&
-            !ts.isComputedPropertyName(property.name) &&
-            passiveInitializer(property.initializer));
-    return false;
-}
-function passiveInitializer(node) {
-    if (!node)
-        return false;
-    if (ts.isLiteralExpression(node))
-        return true;
-    if ([
-        ts.SyntaxKind.TrueKeyword,
-        ts.SyntaxKind.FalseKeyword,
-        ts.SyntaxKind.NullKeyword,
-    ].includes(node.kind))
-        return true;
-    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node))
-        return true;
-    if (ts.isPrefixUnaryExpression(node))
-        return ([ts.SyntaxKind.PlusToken, ts.SyntaxKind.MinusToken].includes(node.operator) && ts.isNumericLiteral(node.operand));
-    const inner = unwrappedInitializer(node);
-    return inner ? passiveInitializer(inner) : passiveCompound(node);
-}
-function passiveStatement(node, kind) {
-    if (ts.isVariableStatement(node))
-        return ((node.declarationList.flags & ts.NodeFlags.Const) !== 0 &&
-            node.declarationList.declarations.every((declaration) => (kind === "helper" ||
-                (ts.getCombinedModifierFlags(declaration) &
-                    ts.ModifierFlags.Export) ===
-                    0) &&
-                ts.isIdentifier(declaration.name) &&
-                passiveInitializer(declaration.initializer)));
-    if (ts.isExpressionStatement(node))
-        return ts.isStringLiteral(node.expression);
-    return (ts.isImportDeclaration(node) ||
-        ts.isTypeAliasDeclaration(node) ||
-        ts.isInterfaceDeclaration(node) ||
-        ts.isFunctionDeclaration(node) ||
-        ts.isEmptyStatement(node));
-}
-export function passiveCandidateModule(source, kind = "workflow") {
-    return source.statements.every((node) => passiveStatement(node, kind));
-}

package/dist/tools/workflow-command.js

@@ -80,8 +80,7 @@ function presentWorkflows(workflows, options) {
 }
 async function testWorkflows(workflows, options) {
     const { id, repository } = options;
-    const selected = workflows.filter((workflow) => workflow.scope !== "bundled" &&
-        (id === undefined || workflow.workflowId === id));
+    const selected = workflows.filter((workflow) => id === undefined || workflow.workflowId === id);
     if (id !== undefined &&
         !workflows.some((workflow) => workflow.workflowId === id)) {
         process.stderr.write("unknown-workflow: " + id + "\n");

package/dist/tools/workflow-folders.d.ts

@@ -1,6 +1,6 @@
 import type { WorkflowDeclaration } from "../src/workflow-declaration.ts";
 import { type CandidateDeclaration, type WorkflowCandidateCode } from "../src/workflow-candidate.ts";
-import { type WorkflowConflictCode, type WorkflowReservation } from "../src/workflow-discovery.ts";
+import { type WorkflowConflictCode } from "../src/workflow-discovery.ts";
 import type { CandidatePackageOptions } from "./workflow-candidate-program.ts";
 import { type WorkflowCaptureCode } from "./workflow-folder-capture.ts";
 export interface WorkflowFolderInput {
@@ -8,7 +8,6 @@ export interface WorkflowFolderInput {
     readonly home: string;
     readonly xdgConfigHome?: string | undefined;
     readonly userFolder?: string | undefined;
-    readonly bundled: readonly WorkflowReservation[];
 }
 interface WorkflowLabel {
     readonly scope: "project" | "user";
@@ -28,7 +27,7 @@ export interface WorkflowFolderRefusal extends WorkflowLabel {
     readonly codes: readonly (WorkflowCandidateCode | WorkflowCaptureCode | WorkflowConflictCode | "compile-failed")[];
 }
 export interface WorkflowListing {
-    readonly scope: "bundled" | "project" | "user";
+    readonly scope: "project" | "user";
     readonly workflowId: string | null;
     readonly file: string;
     readonly admitted: boolean;

package/dist/tools/workflow-folders.js

@@ -162,7 +162,7 @@ export async function loadWorkflowFolders(input, installed = {}) {
     const candidates = [];
     const refusals = [];
     const { repository, snapshots } = await scanFolders(input, refusals);
-    const conflicts = workflowConflicts(snapshots.map(identity), input.bundled);
+    const conflicts = workflowConflicts(snapshots.map(identity));
     for (const [index, entry] of snapshots.entries()) {
         const label = entry.kind === "captured" ? entry.snapshot : entry;
         const codes = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloving",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Local durable development workflow service",
   "license": "MIT",
   "repository": {
@@ -31,10 +31,6 @@
       "types": "./dist/src/steps/protected-effect.d.ts",
       "import": "./dist/src/steps/protected-effect.js"
     },
-    "./workflows/steps/decision-gate": {
-      "types": "./dist/src/steps/decision-gate.d.ts",
-      "import": "./dist/src/steps/decision-gate.js"
-    },
     "./workflows/steps/review-subject": {
       "types": "./dist/src/steps/review-subject.d.ts",
       "import": "./dist/src/steps/review-subject.js"
@@ -55,6 +51,10 @@
       "types": "./dist/src/steps/merge-when-green.d.ts",
       "import": "./dist/src/steps/merge-when-green.js"
     },
+    "./workflows/steps/open-decision-wait": {
+      "types": "./dist/src/steps/open-decision-wait.d.ts",
+      "import": "./dist/src/steps/open-decision-wait.js"
+    },
     "./workflows/steps/wait-for-decision": {
       "types": "./dist/src/steps/wait-for-decision.d.ts",
       "import": "./dist/src/steps/wait-for-decision.js"
@@ -78,12 +78,19 @@
     "./workflows/steps/sleep": {
       "types": "./dist/src/steps/sleep.d.ts",
       "import": "./dist/src/steps/sleep.js"
+    },
+    "./workflows/steps/wait-for-command": {
+      "types": "./dist/src/steps/wait-for-command.d.ts",
+      "import": "./dist/src/steps/wait-for-command.js"
+    },
+    "./workflows/steps/command-wait": {
+      "types": "./dist/src/steps/command-wait.d.ts",
+      "import": "./dist/src/steps/command-wait.js"
     }
   },
   "files": [
     "dist/src",
     "dist/tools",
-    "dist/workflows",
     "templates",
     "assets/watch-fonts/fira-code-latin-400-normal.woff2",
     "assets/watch-fonts/fira-code-latin-500-normal.woff2",
@@ -112,7 +119,7 @@
     "x64"
   ],
   "scripts": {
-    "build": "tsc --project tsconfig.build.json && node tools/copy-workflow-declarations.ts workflows dist/workflows",
+    "build": "tsc --project tsconfig.build.json",
     "build:workflows": "node tools/compile-workflows.ts",
     "check:setup": "node tools/check-shells.ts && tsc --project tsconfig.json --noEmit",
     "check:quality": "node tools/check-quality.ts",
@@ -150,6 +157,7 @@
     "preact": "11.0.0",
     "solid-objects": "1.0.2",
     "typescript": "6.0.3",
-    "workflow": "5.1.0"
+    "workflow": "5.1.0",
+    "yaml": "2.9.1"
   }
 }

package/templates/develop/README.md

@@ -14,6 +14,18 @@ review or repairable merge result gives its full output and remaining work to
 the next worker turn. Review, local-check, conflict and CI fixes share a limit
 of three fix rounds. Pending CI and an unconfigured check stop the run.
 
+`develop/pull.ts` keeps the first line of the ticket as the pull request title,
+removes leading `#` characters and limits it to 200 characters. For a task with
+a GitHub issue, the pull request body links that issue and names its number:
+
+```text
+Refs cloving-ai/cloving-ai#375
+
+Cloving made this change for the ticket 375.
+```
+
+A task without a GitHub issue uses only `Cloving made this change for this task.`
+
 `develop.test.ts` and `develop/flow-tests.ts` test the default composition through the public fake
 step bridge. The alternative configurations use `develop/option-tests.ts`, with the selected
 point IDs in `develop/scenarios.ts`. For an edited copy, replace the default

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

@@ -116,6 +116,10 @@ flowTests.push({
       (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/);
   },
 });
@@ -355,3 +359,36 @@ flowTests.push({
     });
   },
 });
+
+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/pull.ts

@@ -21,6 +21,7 @@ export async function openPull(request: {
   readonly round: number;
 }): Promise<PullRequest> {
   const { input, round } = request;
+  const issue = input.issue;
   const result = await protectedEffect({
     scope: { phase: "pull-request", operation: "github-open-pr", round: round },
     capability: "github",
@@ -30,7 +31,10 @@ export async function openPull(request: {
       title: (input.ticket.split("\n")[0] ?? "Develop task")
         .replace(/^#+\s*/, "")
         .slice(0, 200),
-      body: "Review the committed changes and repository checks for this task.",
+      body:
+        issue === null
+          ? "Cloving made this change for this task."
+          : `Refs ${issue.owner}/${issue.repository}#${String(issue.number)}\n\nCloving made this change for the ticket ${String(issue.number)}.`,
     }),
     units: 1,
   });

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

@@ -9,6 +9,83 @@ import { effects } from "./scenarios.ts";
 
 export const refusalTests: FlowTest[] = [];
 
+refusalTests.push({
+  name: "CLV-260 a linked pull request names the issue and preserves the ticket title",
+  run: async () => {
+    using bridge = fakeStepBridge({
+      turn: completed({ number: 7, url: "pull/7", commit }),
+    });
+    await openPull({
+      input: {
+        cycleId: input.cycleId,
+        repository: input.repository,
+        ticket:
+          "# CLV-228: Stop the registration of the bundled workflows\n\nGitHub issue: cloving-ai/cloving-ai#375 (open)",
+        issue: { owner: "cloving-ai", repository: "cloving-ai", number: 375 },
+      },
+      round: 1,
+    });
+    assert.equal(bridge.requests.length, 1);
+    const opened = bridge.requests[0];
+    assert.ok(opened && opened[0] === "effect");
+    assert.equal(opened[1].method, "open-pr");
+    assert.deepEqual(JSON.parse(opened[1].payload), {
+      title: "CLV-228: Stop the registration of the bundled workflows",
+      body: "Refs cloving-ai/cloving-ai#375\n\nCloving made this change for the ticket 375.",
+    });
+  },
+});
+
+refusalTests.push({
+  name: "CLV-260 a task without an issue opens a pull request without a reference",
+  run: async () => {
+    using bridge = fakeStepBridge({
+      turn: completed({ number: 7, url: "pull/7", commit }),
+    });
+    await openPull({
+      input: {
+        cycleId: input.cycleId,
+        repository: input.repository,
+        ticket: "### Manual task\n\nGitHub issue: acme/demo#42 (open)",
+        issue: null,
+      },
+      round: 1,
+    });
+    assert.equal(bridge.requests.length, 1);
+    const opened = bridge.requests[0];
+    assert.ok(opened && opened[0] === "effect");
+    assert.equal(opened[1].method, "open-pr");
+    assert.deepEqual(JSON.parse(opened[1].payload), {
+      title: "Manual task",
+      body: "Cloving made this change for this task.",
+    });
+  },
+});
+
+refusalTests.push({
+  name: "CLV-260 pull request titles use at most 200 characters from the first line",
+  run: async () => {
+    using bridge = fakeStepBridge({
+      turn: completed({ number: 7, url: "pull/7", commit }),
+    });
+    await openPull({
+      input: {
+        cycleId: input.cycleId,
+        repository: input.repository,
+        ticket: `### ${"Title".repeat(50)}\nSecond line`,
+        issue: null,
+      },
+      round: 1,
+    });
+    const opened = bridge.requests[0];
+    assert.ok(opened && opened[0] === "effect");
+    assert.deepEqual(JSON.parse(opened[1].payload), {
+      title: "Title".repeat(40),
+      body: "Cloving made this change for this task.",
+    });
+  },
+});
+
 for (const operation of [
   "claude run-turn",
   "github open-pr",

package/templates/develop/develop/turn.ts

@@ -32,6 +32,7 @@ function turnPrompt(input: DevelopTurnInput): string {
     "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.",
+    "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.",
     "",
     "Task:",
     task,
@@ -41,7 +42,7 @@ function turnPrompt(input: DevelopTurnInput): string {
     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:",
+    "Reassess every unfinished item. Drop an item that the task does not ask for, and retain the unresolved items in the next Remaining: list:",
     input.feedback.remaining.map((item) => `- ${item}`).join("\n"),
     "",
     "Output from the previous result:",

package/templates/idea-to-issue/README.md

@@ -0,0 +1,27 @@
+# Idea to issue
+
+Copy this template with `cloving templates copy idea-to-issue`. Answer its three
+questions using `cloving templates show idea-to-issue --json`, apply the indicated
+imports and declaration edits, and run `cloving workflows test idea-to-issue`.
+The copied workflow accepts an `idea` string.
+
+The default workflow researches the idea, runs a turn to correct its draft, posts
+after the existing privacy check, and hands the issue to the repository workflow
+named `develop`. Copy the develop template or set `targetWorkflow` in
+`idea-to-issue/next.ts` and `workflow.handoffs` in the declaration to your declared
+development workflow. Its input must accept a `ticket` string.
+
+To read the draft yourself, select `review.person`. To approve publication, select
+`post.person`. Each choice captures the draft through `github capture-draft`
+before opening its approval gate. The gates show the captured text. The issue post
+checks every captured digest against the text it posts. A changed draft, denial,
+or expired gate stops the run and leaves the work tree and draft available.
+
+To queue the issue, select `next.queue`; this adds `cloving: ready`. To leave it
+alone, select `next.nothing`. Both declarations have `handoffs: []`, and neither
+needs a develop workflow. A failed handoff returns the issue to the queue.
+
+Every post requires `privateTexts` containing at least one nonblank item. Human
+approval does not bypass the privacy check. Run `cloving doctor` for the `needs`
+codes in the selected options. Update `selection` in `idea-to-issue/scenarios.ts`
+to match the choices so the copied tests verify their expected behavior.

package/templates/idea-to-issue/idea-to-issue/effects.ts

@@ -0,0 +1,52 @@
+import type { CycleOutcome, ProtectedResult } from "cloving/workflows";
+
+export interface IdeaInput {
+  readonly cycleId: string;
+  readonly input: { readonly idea: string };
+}
+
+export const draft = "cloving-prd-draft.md";
+
+export function failureReason(failure: unknown, fallback: string): string {
+  if (typeof failure !== "object" || failure === null) return fallback;
+  const cause = "cause" in failure ? failure.cause : failure;
+  if (
+    typeof cause !== "object" ||
+    cause === null ||
+    !("message" in cause) ||
+    typeof cause.message !== "string"
+  )
+    return fallback;
+  return /^[a-z][a-z0-9-]{0,127}$/.test(cause.message)
+    ? cause.message
+    : fallback;
+}
+
+export function effectResult(result: ProtectedResult): string | null {
+  if (result.kind !== "completed")
+    throw new Error(result.reason ?? result.kind);
+  return result.result;
+}
+
+export function resultFields(result: string | null): Record<string, unknown> {
+  let value: unknown;
+  try {
+    value = JSON.parse(result ?? "null");
+  } catch {
+    throw new Error("invalid-issue-result");
+  }
+  if (!resultObject(value)) throw new Error("invalid-issue-result");
+  return value;
+}
+
+function resultObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function issueOutcome(input: IdeaInput, number: number): CycleOutcome {
+  return {
+    kind: "handoff_requested",
+    cycleId: input.cycleId,
+    promotionId: `issue-${String(number)}`,
+  };
+}

package/templates/idea-to-issue/idea-to-issue/leave.ts

@@ -0,0 +1,10 @@
+import type { CycleOutcome } from "cloving/workflows";
+import { issueOutcome, type IdeaInput } from "./effects.ts";
+import type { PostedIssue } from "./post.ts";
+
+export async function leaveIssue(
+  input: IdeaInput,
+  issue: PostedIssue,
+): Promise<CycleOutcome> {
+  return Promise.resolve(issueOutcome(input, issue.number));
+}

package/templates/idea-to-issue/idea-to-issue/next.ts

@@ -0,0 +1,29 @@
+import type { CycleOutcome } from "cloving/workflows";
+import { handoff } from "cloving/workflows/steps/handoff";
+import { issueOutcome, failureReason, type IdeaInput } from "./effects.ts";
+import type { PostedIssue } from "./post.ts";
+import { queueIssue } from "./queue.ts";
+
+export const targetWorkflow = "develop";
+
+export async function handoffIssue(
+  input: IdeaInput,
+  issue: PostedIssue,
+): Promise<CycleOutcome> {
+  const outcome = issueOutcome(input, issue.number);
+  try {
+    await handoff({
+      workflowId: targetWorkflow,
+      input: { ticket: String(issue.number) },
+    });
+    return outcome;
+  } catch (error) {
+    const reason = failureReason(error, "handoff-failed");
+    try {
+      await queueIssue(input, issue);
+      return Object.assign(outcome, { reason });
+    } catch {
+      return Object.assign(outcome, { reason, issueUpdate: "failed" as const });
+    }
+  }
+}