@yaawn/workflow 0.0.0-stage → 0.3.1

package/agents/skills/yaawn-split-story/scripts/create-issue.ts

@@ -0,0 +1,162 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+
+interface Options {
+  original: number;
+  template: string;
+  title: string;
+  bodyFile: string;
+  dependsOn: number[];
+}
+
+const templatesDir = ".github/ISSUE_TEMPLATE";
+const plansDir = ".yaawn/plans";
+const dependenciesHeading = "## Dependencies";
+const implementationPlanHeading = "## Implementation Plan";
+const usage =
+  "Usage: npx tsx .agents/skills/yaawn-split-story/scripts/create-issue.ts <original> --template <file> --title <title> --body-file <path> [--depends-on <n>[,<n>...]]";
+
+const issueBodyPath = (original: number): string =>
+  `${plansDir}/yaawn-${original}-split-issue-body.md`;
+
+function gh(args: string[]): string {
+  return execFileSync("gh", args, { encoding: "utf-8" }).trim();
+}
+
+function parseFlags(args: string[]): Map<string, string> {
+  if (args.length % 2 !== 0) throw new Error(usage);
+  const flags = new Map<string, string>();
+  for (let index = 0; index < args.length; index += 2) {
+    const [flag, value] = args.slice(index, index + 2);
+    if (!flag.startsWith("--")) throw new Error(usage);
+    flags.set(flag.slice(2), value);
+  }
+  return flags;
+}
+
+function parseDependsOn(value: string | undefined): number[] {
+  if (value === undefined) return [];
+  if (!/^#?\d+(,\s*#?\d+)*$/.test(value)) throw new Error(usage);
+  return value.split(",").map((issue) => Number(issue.trim().replace("#", "")));
+}
+
+function parseOptions(argv: string[]): Options {
+  const [originalArg, ...rest] = argv;
+  if (!/^\d+$/.test(originalArg ?? "")) throw new Error(usage);
+  const flags = parseFlags(rest);
+  const required = ["template", "title", "body-file"].map((name) => {
+    const value = flags.get(name);
+    if (!value) throw new Error(`--${name} is required\n${usage}`);
+    return value;
+  });
+  const [template, title, bodyFile] = required;
+  const original = Number(originalArg);
+  const dependsOn = parseDependsOn(flags.get("depends-on"));
+  if (dependsOn.includes(original)) {
+    throw new Error(
+      `--depends-on must not list the original #${original} — the new issues replace it`,
+    );
+  }
+  return { original, template, title, bodyFile, dependsOn };
+}
+
+function frontmatterValue(template: string, key: string): string {
+  const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/.exec(template)?.[1] ?? "";
+  const line = frontmatter
+    .split(/\r?\n/)
+    .find((candidate) => candidate.startsWith(`${key}:`));
+  return line?.slice(key.length + 1).trim() ?? "";
+}
+
+// Accepts both YAML list styles the templates use:
+// labels: ["Yaawn: Story", "Yaawn: To Be Refined"]  and  labels: Yaawn: Spike, Yaawn: To Be Refined
+function listValue(value: string): string[] {
+  return value
+    .replace(/^\[|\]$/g, "")
+    .split(",")
+    .map((item) => item.trim().replace(/^["']|["']$/g, ""))
+    .filter(Boolean);
+}
+
+function readTemplate(name: string): { labels: string[]; projects: string[] } {
+  const path = `${templatesDir}/${name}`;
+  if (!existsSync(path)) throw new Error(`template not found: ${path}`);
+  const template = readFileSync(path, "utf-8");
+  return {
+    labels: listValue(frontmatterValue(template, "labels")),
+    projects: listValue(frontmatterValue(template, "projects")),
+  };
+}
+
+function dependenciesSection(dependsOn: number[]): string {
+  const declaration =
+    dependsOn.length > 0
+      ? `**Depends on:** ${dependsOn.map((issue) => `#${issue}`).join(", ")}`
+      : "None — this can be worked on independently.";
+  return `${dependenciesHeading}\n\n${declaration}`;
+}
+
+// The overnight run parses this section, so the script writes it — never the agent.
+function withDependencies(body: string, dependsOn: number[]): string {
+  if (body.split(/\r?\n/).some((line) => line.trim() === dependenciesHeading)) {
+    throw new Error(
+      `the body already has "${dependenciesHeading}" — remove it and pass --depends-on instead`,
+    );
+  }
+  const section = dependenciesSection(dependsOn);
+  const planStart = body.indexOf(`\n${implementationPlanHeading}`);
+  if (planStart === -1) return `${body.trimEnd()}\n\n${section}\n`;
+  return `${body.slice(0, planStart).trimEnd()}\n\n${section}\n${body.slice(planStart)}`;
+}
+
+function createIssue(options: Options, bodyPath: string): number {
+  const { labels, projects } = readTemplate(options.template);
+  const url = gh([
+    "issue",
+    "create",
+    "--title",
+    options.title,
+    "--body-file",
+    bodyPath,
+    ...labels.flatMap((label) => ["--label", label]),
+    ...projects.flatMap((project) => ["--project", project]),
+  ]);
+  const number = /\/issues\/(\d+)\s*$/.exec(url)?.[1];
+  if (!number) throw new Error(`could not read the issue number from: ${url}`);
+  console.log(`created #${number} ${url}`);
+  return Number(number);
+}
+
+function commentOrigin(original: number, issue: number): void {
+  gh([
+    "issue",
+    "comment",
+    String(issue),
+    "--body",
+    `Split from #${original}, which this issue and its sibling slices replace. The split rationale is in a comment on #${original}.`,
+  ]);
+  console.log(`commented the origin #${original} on #${issue}`);
+}
+
+function main(): void {
+  const options = parseOptions(process.argv.slice(2));
+  const body = readFileSync(options.bodyFile, "utf-8");
+  mkdirSync(plansDir, { recursive: true });
+  const bodyPath = issueBodyPath(options.original);
+  writeFileSync(bodyPath, withDependencies(body, options.dependsOn));
+  const issue = createIssue(options, bodyPath);
+  try {
+    commentOrigin(options.original, issue);
+  } catch (error) {
+    throw new Error(
+      `#${issue} was created but the origin comment failed — add it by hand, do not create the issue again: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+try {
+  main();
+} catch (error: unknown) {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+}

package/agents/skills/yaawn-verify-executed-plan/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: yaawn-verify-executed-plan
+description: "Final verification gate of the plan pipeline, run by the developer after /yaawn-implement-plan finishes — once per issue. Assigns every Definition of Done step from .yaawn/yaawn-definition-of-done.md to a check, launches the project's verification commands from .yaawn/yaawn-verification-commands.md (set up by the install script, optional) as an unattended overnight task (kept awake with caffeinate, logs in .yaawn/plans/), lists the manual checks, and — once verified — opens a pull request for the issue."
+argument-hint: "GitHub issue number"
+disable-model-invocation: true
+metadata:
+  github-repo: https://github.com/markusfalk/yaawn
+  author: markusfalk
+---
+
+# Verify Executed Plan
+
+The last skill of the plan pipeline: `/yaawn-prepare-plan` → `/yaawn-create-plan` → `/yaawn-save-plan` → `/yaawn-implement-plan` → `/yaawn-verify-executed-plan`. Start it in a new session: it works only from the issue and the files under `.yaawn/plans/`, never from an earlier conversation. The developer runs it after `/yaawn-implement-plan` has finished. Like `/yaawn-implement-plan`, the long work runs as an unattended overnight task — when the project has verification commands configured: they run in a terminal kept awake by `caffeinate`, and the developer reads the results in the morning. Both `.yaawn/yaawn-verification-commands.md` and `.yaawn/yaawn-definition-of-done.md` are optional; without them, verification is the manual checklist only. It runs the verification steps that belong after execution — checking the plan itself is the earlier skills' job.
+
+It takes the same issue number as `/yaawn-implement-plan` and resolves the same **target**: the issue itself. Every issue is verified on its own.
+
+Out of scope: implementing or fixing anything, committing or pushing, writing or editing plans, editing the issue — step 7 is the only exception: it opens a pull request for the issue's branch and removes the issue's `Yaawn: Ready To Implement` and `Yaawn: implementation-group-<n>` labels. On failure, report and stop — fixing is `/yaawn-implement-plan`'s job.
+
+Ask for the issue number if it is not given. Run all commands from the repo root.
+
+## 1. Pre-flight
+
+```sh
+npx tsx .agents/skills/yaawn-verify-executed-plan/scripts/overnight.ts preflight <issue>
+```
+
+It first checks where it runs. `/yaawn-implement-plan` runs every issue in its own git worktree inside the project (`<project>/yaawn-<issue>-<slug>`, branch `yaawn/<issue>`), next to the main copy `<project>/main` — the bare-repo layout described in [`.agents/yaawn-worktrees.md`](../../yaawn-worktrees.md):
+
+- The issue has its own worktree and the session runs elsewhere: `FAIL` naming the worktree's path.
+- The issue has no worktree of its own and the session runs in another issue's worktree: `FAIL` pointing to the main copy `<project>/main`.
+- The issue has no worktree of its own (implemented before every run got one, or by hand) and the session runs in the main copy: `WARN #<issue> has no git worktree of its own — verifying the main copy`. Mention the warning to the developer and continue.
+
+It prints the target, the verification commands — or a note when none are configured — and checks `gh`, `caffeinate`, that no verification is already running for the issue, and that the target's plan is fully executed — every step in `.yaawn/plans/yaawn-<target>-progress.md` is `- [x]`. It also lists uncommitted changes (files under `.yaawn/plans/` are left out), because the suites run against the working tree.
+
+- Any `FAIL` line: stop and report it. A worktree `FAIL` means: start a new session in the named directory and run this skill there. A plan that is not fully executed means `/yaawn-implement-plan` has not finished — finish it first.
+- Uncommitted changes listed: show them and ask whether to continue.
+- No verification commands configured: skip steps 3 and 4 — the manual checks are the verification.
+
+## 2. Assign every Definition of Done step
+
+`.yaawn/yaawn-definition-of-done.md` is the single source of truth for the standard steps — never read Definition of Done steps from the llm-plan file or the issue. If the file is missing or lists no steps, there are no standard steps to assign.
+
+For each target, read `.yaawn/plans/yaawn-<target>-progress.md` to see which steps the overnight session already checked off or listed as manual checks.
+
+Every standard Definition of Done step must, for every target, be accounted for in exactly one of three places:
+
+- **Done in the progress log** — the overnight session turned a code-producing item (e.g. a regression test, API documentation, translations) into a step and checked it off.
+- **Covered by the verification commands** (step 3) — a step about tests passing.
+- **A manual check** (step 5) — every other step, keeping its wording and condition from the docs file (e.g. "if the UI changed"). The overnight session already lists verify-only items under the progress log's "Manual checks"; do not list them twice.
+
+With no verification commands configured, a tests-passing step becomes a manual check too — the developer runs the suites by hand.
+
+## 3. Launch the overnight verification
+
+This step only applies when pre-flight printed verification commands.
+
+An orchestrator ([scripts/overnight.ts](./scripts/overnight.ts)) runs the verification unattended in a terminal, kept awake by `caffeinate` — the same shape as `/yaawn-implement-plan`. All suite output streams to that terminal, each line prefixed `[#<issue>]`, and every suite also writes a log under `.yaawn/plans/`.
+
+The orchestrator runs the commands in `.yaawn/yaawn-verification-commands.md`, in order — the skill does not assume, propose, or change a project's verification commands.
+
+### The verification commands
+
+The developer sets the commands up once, when running the install script (`npx @yaawn/workflow`). It adds them in run order to `.yaawn/yaawn-verification-commands.md`, one bullet per command — the same way it fills `.yaawn/yaawn-definition-of-done.md`:
+
+```markdown
+- `<shell command>`
+- `<shell command>`
+```
+
+- Every `- ` bullet is one command, run through the shell. Backticks around the command are optional; any other line is ignored.
+- The n-th command logs to `.yaawn/plans/yaawn-<issue>-verify-step-<n>.log`.
+
+Do not write or edit this file. To enable the overnight verification, re-run `npx @yaawn/workflow` or edit the file.
+
+### Launch
+
+```sh
+NO_COLOR=1 npx tsx .agents/skills/yaawn-verify-executed-plan/scripts/overnight.ts run <issue>
+```
+
+Run it in an **async** terminal so it keeps running in the editor. Always set `NO_COLOR=1`: you relay its output into the chat, where color codes show as junk. Launch it exactly once. At launch, it deletes the summary of any earlier verification, so a leftover summary never looks current. Read the initial output:
+
+- Walk-away banner followed by the first suite starting: launched. The banner appears only once `caffeinate` is active.
+- The process exited or an error is shown: failed launch. Report the lines and stop. Do not retry with other flags.
+
+The orchestrator runs the verification commands in order and **stops at the first failure** — the remaining suites are `skipped`.
+
+Gotchas:
+
+- `caffeinate -s` only prevents system sleep on AC power. That is why the hand-off says to keep the Mac on power.
+- Closing the editor or the terminal ends the run. Leave both open overnight.
+- If a run dies, run `run` again — the suites simply rerun.
+
+### Start message
+
+Reply with this template, filled in:
+
+```markdown
+Overnight verification for #<issue> started in the terminal.
+
+- Target: #<issue>
+- Suites: the verification commands from `.yaawn/yaawn-verification-commands.md` — stops at the first failure
+- Output: the launch terminal, lines prefixed `[#<issue>]`; ends with each suite's state and the summary
+- Stop everything: Ctrl+C in that terminal (the running suite and caffeinate end with it)
+- Results: `.yaawn/plans/yaawn-<issue>-verify-summary.md`, per-suite logs `.yaawn/plans/yaawn-<issue>-verify-step-<n>.log`
+
+Keep the Mac on power and the editor open. I will report the results here when the run ends.
+```
+
+Then end your turn and wait. Do not poll the terminal or the summary file — the harness notifies you when the background process ends. Then continue with step 4.
+
+**When the developer asks about the verification later**, in this chat or a new one, check in this order and stop at the first match:
+
+1. `pgrep -f "yaawn-verify-executed-plan/scripts/overnight.ts run <issue>( |$)"` finds a process → say the verification is still running. Never report a summary while the run is active.
+2. `.yaawn/plans/yaawn-<issue>-verify-summary.md` exists → continue with step 4.
+3. Otherwise → say the verification was stopped before it ended and that launching it again reruns it.
+
+## 4. Report the results
+
+This step only applies when the overnight verification ran.
+
+Read `.yaawn/plans/yaawn-<issue>-verify-summary.md`. Report one line per suite — pass/fail and the failing specs only. Do not paste full logs; they are in the per-suite log files.
+
+If a suite failed: keep the working files, report the failures, and tell the developer to fix them (resuming `/yaawn-implement-plan` if a step has to be redone) and then start a new session and run this skill again. Do not continue to the manual checks.
+
+## 5. Manual checks for the developer
+
+The developer verifies by hand. Group the checklist by target. For each target, list:
+
+- the "Manual checks" from its progress log, and
+- the Definition of Done steps assigned to a manual check in step 2 that the progress log does not list yet, each with its own wording and condition.
+
+## 6. Confirm with the developer
+
+When every suite is green — or no suites were configured — present the manual checklist from step 5 and wait for the developer to confirm it. The plan is verified once the developer confirms. Leave the working files under `.yaawn/plans/` in place — the developer cleans them up manually.
+
+## 7. Finish the issue
+
+The plan is verified. Open the pull request.
+
+Tell the developer to commit and push the issue's branch, then — once they confirm — run:
+
+```sh
+npx tsx .agents/skills/yaawn-verify-executed-plan/scripts/overnight.ts finish <issue>
+```
+
+It repeats the worktree check, requires the summary's `Result: passed` when verification commands are configured, and requires a branch other than the default branch, no uncommitted changes outside `.yaawn/plans/`, an upstream, and nothing unpushed. Then it finds the branch's open pull request or opens one (`Closes #<issue>`, assigned to the developer), removes the issue's `Yaawn: Ready To Implement` label together with its `Yaawn: implementation-group-<n>` labels (through `/yaawn-implement-plan`'s shared group-label reset — a failed reset only warns), and prints the link. It never commits or pushes.
+
+Relay its output:
+
+- `pull request opened: <url>` or `pull request already open: <url>`: report the link. The issue closes when the pull request is merged.
+- Any `FAIL` line: report it and tell the developer what to do — commit and push, or switch to the issue's branch or worktree — and then run this step again.
+
+Never commit or push yourself, and never offer to close the issue.

package/agents/skills/yaawn-verify-executed-plan/scripts/overnight.ts

@@ -0,0 +1,362 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { createInterface } from "node:readline";
+import type { Readable } from "node:stream";
+import {
+  keepMacAwakeWhileRunning,
+  printWalkAwayBanner,
+} from "../../yaawn-implement-plan/scripts/caffeinate.js";
+import {
+  type Issue,
+  isDone,
+  issueRefs,
+  plansDir,
+  progressPath,
+  removeGroupLabels,
+  resolveTargets,
+  succeeds,
+  uncommittedChanges,
+} from "../../yaawn-implement-plan/scripts/targets.js";
+import { checkWorktree } from "../../yaawn-implement-plan/scripts/worktrees.js";
+import {
+  createPullRequest,
+  currentBranch,
+  defaultBranch,
+  defaultBranchFailure,
+  openPullRequestUrl,
+  pushedStateFailures,
+  readPushedState,
+  readVerifyResult,
+  removeReadyLabel,
+} from "./pull-request.js";
+
+interface Suite {
+  name: string;
+  command: string;
+}
+
+type SuiteState = "passed" | "failed" | "skipped";
+
+interface SuiteResult {
+  suite: Suite;
+  state: SuiteState;
+}
+
+interface SuiteHandle {
+  current: ChildProcess | null;
+}
+
+const suitesPath = ".yaawn/yaawn-verification-commands.md";
+const suitesSetupHint = `set them up with \`npx @yaawn/workflow\` or edit ${suitesPath}`;
+const exitCodeTerminated = 143;
+const failureTailLines = 40;
+const usage =
+  "Usage: npx tsx .agents/skills/yaawn-verify-executed-plan/scripts/overnight.ts <preflight|run|finish|reset-group-labels> <issue>";
+
+const logPath = (issue: number, suite: string): string =>
+  `${plansDir}/yaawn-${issue}-verify-${suite}.log`;
+
+const summaryPath = (issue: number): string =>
+  `${plansDir}/yaawn-${issue}-verify-summary.md`;
+
+function isRunActive(issue: number): boolean {
+  return succeeds("pgrep", [
+    "-f",
+    `yaawn-verify-executed-plan/scripts/overnight.ts run ${issue}( |$)`,
+  ]);
+}
+
+function toolFailures(issue: number): string[] {
+  const checks: [string, boolean][] = [
+    ["gh not authenticated", succeeds("gh", ["auth", "status"])],
+    ["caffeinate not installed", succeeds("which", ["caffeinate"])],
+    [`verification run already active for #${issue}`, !isRunActive(issue)],
+  ];
+  return checks.filter(([, ok]) => !ok).map(([failure]) => failure);
+}
+
+function executionFailures({ number }: Issue): string[] {
+  if (!existsSync(progressPath(number))) {
+    return [`#${number} has no progress log — run /yaawn-implement-plan first`];
+  }
+  return isDone(number)
+    ? []
+    : [
+        `#${number} plan is not fully executed — finish /yaawn-implement-plan first`,
+      ];
+}
+
+// Mirrors the bullet format the install script writes: "- `command`".
+function parseCommand(line: string): string | null {
+  if (!line.startsWith("- ")) return null;
+  const item = line.slice("- ".length).trim();
+  const wrapped = /^`([^`]+)`$/.exec(item);
+  return wrapped ? wrapped[1] : item || null;
+}
+
+function loadSuites(): Suite[] {
+  if (!existsSync(suitesPath)) return [];
+  const commands = readFileSync(suitesPath, "utf-8")
+    .split("\n")
+    .map(parseCommand)
+    .filter((command): command is string => command !== null);
+  return commands.map((command, index) => ({
+    name: `step-${index + 1}`,
+    command,
+  }));
+}
+
+function printTargets(targets: Issue[]): void {
+  console.log("targets:");
+  targets.forEach(({ number, title }) =>
+    console.log(`  #${number} ${title} — ${progressPath(number)}`),
+  );
+}
+
+function printSuites(suites: Suite[]): void {
+  if (suites.length === 0) {
+    console.log(
+      `no verification commands configured — overnight verification skipped (${suitesSetupHint})`,
+    );
+    return;
+  }
+  console.log(`verification commands (${suitesPath}):`);
+  suites.forEach((suite, index) =>
+    console.log(`  ${index + 1}. ${suite.name}: ${suite.command}`),
+  );
+}
+
+function printFailures(failures: string[]): void {
+  failures.forEach((failure) => console.log(`FAIL ${failure}`));
+}
+
+function printUncommittedChanges(): void {
+  console.log(`--- uncommitted changes (without ${plansDir}/)`);
+  console.log(uncommittedChanges());
+}
+
+// Returns false when the worktree check fails; a warning is printed and passes.
+function worktreeCheckPasses({ number }: Issue): boolean {
+  const { status, message } = checkWorktree(number);
+  if (status === "fail") {
+    printFailures([message]);
+    return false;
+  }
+  console.log(`${status === "warn" ? "WARN" : "worktree:"} ${message}`);
+  return true;
+}
+
+function preflight(parent: number): boolean {
+  const tools = toolFailures(parent);
+  if (tools.length > 0) {
+    printFailures(tools);
+    return false;
+  }
+
+  const targets = resolveTargets(parent);
+  if (!worktreeCheckPasses(targets[0])) return false;
+  const failures = targets.flatMap(executionFailures);
+  printTargets(targets);
+  printSuites(loadSuites());
+  printFailures(failures);
+  printUncommittedChanges();
+  return failures.length === 0;
+}
+
+function streamLines(
+  stream: Readable | null,
+  issue: number,
+  log: string,
+): void {
+  if (!stream) return;
+  createInterface({ input: stream }).on("line", (line) => {
+    console.log(`[#${issue}] ${line}`);
+    appendFileSync(log, `${line}\n`);
+  });
+}
+
+function runSuite(
+  issue: number,
+  suite: Suite,
+  handle: SuiteHandle,
+): Promise<SuiteState> {
+  const log = logPath(issue, suite.name);
+  appendFileSync(log, `# ${new Date().toISOString()} ${suite.command}\n\n`);
+  return new Promise((resolve) => {
+    const suiteProcess = spawn(suite.command, {
+      shell: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    handle.current = suiteProcess;
+    streamLines(suiteProcess.stdout, issue, log);
+    streamLines(suiteProcess.stderr, issue, log);
+    let settled = false;
+    const settle = (state: SuiteState): void => {
+      if (settled) return;
+      settled = true;
+      handle.current = null;
+      resolve(state);
+    };
+    suiteProcess.on("error", (error) => {
+      console.log(`[#${issue}] failed to start: ${error.message}`);
+      appendFileSync(log, `failed to start: ${error.message}\n`);
+      settle("failed");
+    });
+    suiteProcess.on("exit", (code) => settle(code === 0 ? "passed" : "failed"));
+  });
+}
+
+function stopSuiteOnSignal(handle: SuiteHandle): void {
+  const stop = (): void => {
+    handle.current?.kill("SIGTERM");
+    process.exit(exitCodeTerminated);
+  };
+  process.on("SIGTERM", stop);
+  process.on("SIGINT", stop);
+}
+
+function tailLines(path: string, count: number): string[] {
+  if (!existsSync(path)) return [];
+  return readFileSync(path, "utf-8").trimEnd().split("\n").slice(-count);
+}
+
+function writeSummary(
+  issue: number,
+  targets: Issue[],
+  results: SuiteResult[],
+): void {
+  const lines = [
+    `# Verification: #${issue}`,
+    "",
+    `Targets: ${issueRefs(targets.map(({ number }) => number))}`,
+    "",
+    `Finished: ${new Date().toISOString()}`,
+    "",
+    `Result: ${results.every(({ state }) => state === "passed") ? "passed" : "failed"}`,
+    "",
+    "| Suite | Result | Log |",
+    "| --- | --- | --- |",
+    ...results.map(
+      ({ suite, state }) =>
+        `| ${suite.command} | ${state} | ${logPath(issue, suite.name)} |`,
+    ),
+    "",
+  ];
+  results
+    .filter(({ state }) => state === "failed")
+    .forEach(({ suite }) => {
+      lines.push(
+        `## ${suite.name} — failing output (last ${failureTailLines} lines)`,
+        "",
+        "```",
+        ...tailLines(logPath(issue, suite.name), failureTailLines),
+        "```",
+        "",
+      );
+    });
+  writeFileSync(summaryPath(issue), `${lines.join("\n")}\n`);
+}
+
+async function runSuites(
+  issue: number,
+  suites: Suite[],
+): Promise<SuiteResult[]> {
+  const handle: SuiteHandle = { current: null };
+  stopSuiteOnSignal(handle);
+  const results: SuiteResult[] = [];
+  for (const suite of suites) {
+    const alreadyFailed = results.some(({ state }) => state === "failed");
+    if (alreadyFailed) {
+      results.push({ suite, state: "skipped" });
+      console.log(`[#${issue}] ${suite.name} skipped`);
+      continue;
+    }
+    console.log(`\n--- ${suite.name}: ${suite.command}`);
+    const state = await runSuite(issue, suite, handle);
+    results.push({ suite, state });
+    console.log(`[#${issue}] ${suite.name} ${state}`);
+  }
+  return results;
+}
+
+async function run(issue: number): Promise<boolean> {
+  rmSync(summaryPath(issue), { force: true });
+  const suites = loadSuites();
+  if (suites.length === 0) {
+    console.log(
+      `no verification commands configured — nothing to run (${suitesSetupHint})`,
+    );
+    return true;
+  }
+  const targets = resolveTargets(issue);
+  await keepMacAwakeWhileRunning();
+  printWalkAwayBanner();
+  const results = await runSuites(issue, suites);
+
+  writeSummary(issue, targets, results);
+  const passed = results.every(({ state }) => state === "passed");
+  console.log("\n--- summary");
+  console.log(`#${issue} ${passed ? "passed" : "failed"}`);
+  console.log(readFileSync(summaryPath(issue), "utf-8").trim());
+  return passed;
+}
+
+function summaryGuardFailures(issue: number): string[] {
+  if (loadSuites().length === 0) return [];
+  return readVerifyResult(summaryPath(issue)) === "passed"
+    ? []
+    : [`no passing verification for #${issue} in ${summaryPath(issue)} — run the verification first`];
+}
+
+function branchFailures(): string[] {
+  const failure = defaultBranchFailure(currentBranch(), defaultBranch());
+  if (failure) return [failure];
+  return pushedStateFailures(readPushedState(uncommittedChanges()));
+}
+
+function openOrFindPullRequest(issue: number): void {
+  const branch = currentBranch();
+  const existing = openPullRequestUrl(branch);
+  const url = existing ?? createPullRequest(issue, branch, defaultBranch());
+  removeReadyLabel(issue);
+  removeGroupLabels(issue);
+  console.log(`${existing ? "pull request already open" : "pull request opened"}: ${url}`);
+}
+
+// Opens a pull request for the issue's branch; never commits or pushes.
+function finish(issue: number): boolean {
+  const targets = resolveTargets(issue);
+  if (!worktreeCheckPasses(targets[0])) return false;
+  const failures = [...summaryGuardFailures(issue), ...branchFailures()];
+  if (failures.length > 0) {
+    printFailures(failures);
+    return false;
+  }
+  openOrFindPullRequest(issue);
+  return true;
+}
+
+async function main(): Promise<void> {
+  const [command, issueArg, ...extra] = process.argv.slice(2);
+  if (!/^[1-9]\d*$/.test(issueArg ?? "") || extra.length > 0) throw new Error(usage);
+  const issue = Number(issueArg);
+  mkdirSync(plansDir, { recursive: true });
+
+  if (command === "preflight") process.exitCode = preflight(issue) ? 0 : 1;
+  else if (command === "run") process.exitCode = (await run(issue)) ? 0 : 1;
+  else if (command === "finish") process.exitCode = finish(issue) ? 0 : 1;
+  else if (command === "reset-group-labels") removeGroupLabels(issue);
+  else throw new Error(usage);
+}
+
+main().catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});