dorfl 0.0.0 → 0.1.0

package/src/close-job-template.ts

@@ -0,0 +1,236 @@
+/**
+ * The `install-ci` CLOSE-JOB capability (prd `runner-in-ci`, task
+ * `install-ci-close-job-workflow`; capability E: close issues when their work
+ * lands). This module GENERATES the one fixed workflow file for the close-job and
+ * STRUCTURALLY VALIDATES it, mirroring the snapshot-assertion style of
+ * `advance-lifecycle-template.ts` / `advance-ci-template.ts` (the package depends on
+ * NO YAML lib, so the checks are presence/shape assertions over the raw text).
+ *
+ * The discipline (from the prd capability-E row + the Out-of-Scope fence):
+ *
+ *   - TRIGGER: a MERGE to `main`. There is no native "PR merged" event, so the
+ *     workflow uses `push: {branches: [main]}` (NOT `pull_request: closed`): it
+ *     fires for BOTH PR-merges AND direct pushes to `main`, and it ALWAYS runs with
+ *     a normal (non-fork-restricted) `GITHUB_TOKEN` that can actually close issues
+ *     — whereas a `pull_request` event from a FORK gets a read-only token and
+ *     cannot close. (See the `## Decisions` block in the task.)
+ *   - The job INVOKES the close machinery via `dorfl close-merged-issues`,
+ *     which CONSUMES the UNCHANGED engine pieces: the resolution
+ *     (`resolveClosingIssue`), the "prd complete?" query (`prd-complete-query`,
+ *     done), and `IssueProvider.closeIssue`. CI owns ONLY the job + trigger; it
+ *     re-implements NONE of those (the Out-of-Scope fence).
+ *   - CI runs IN-PLACE (the CI container IS the isolation): no
+ *     `--isolated`/`--remote`/registry. A CI concurrency group serialises
+ *     overlapping close ticks on `main`; the claim CAS is the real cross-run
+ *     serialiser elsewhere, but the close-job mutates only the ISSUE, so the group
+ *     just avoids redundant concurrent close passes.
+ *   - The running CI job NEVER edits `.github/workflows/**` (US #9): it requests NO
+ *     `workflows` permission and cannot rewrite its own triggers. It needs only
+ *     `contents: read` (to read the `work/` tree) + `issues: write` (to close).
+ *
+ * The structural validator is the dependency-free counterpart of "the workflow
+ * parses + carries the right discipline" the task's acceptance criteria require;
+ * the test generates this artifact under `--fake` and asserts every invariant.
+ */
+
+import type {ResolvedCIConfig} from './install-ci-core.js';
+
+/** The capability id (the registry key + the emitted workflow file stem). */
+export const CLOSE_JOB_CAPABILITY_ID = 'close-job';
+
+/** The wizard-facing label for the close-job capability. */
+export const CLOSE_JOB_CAPABILITY_LABEL =
+	'Close issues when their work lands (the close-job: on a merge to main)';
+
+/** The repo-relative path (under the output base) of the emitted workflow. */
+export const CLOSE_JOB_WORKFLOW_PATH = 'workflows/close-job.yml';
+
+/**
+ * Generate the close-job workflow YAML. Deterministic: the same config produces
+ * byte-identical output. The workflow is a FIXED shell (ADR §6: all policy is
+ * env/config) — `config` is accepted for parity with the `CapabilityEmitter` seam
+ * and future per-config wiring, but the close-job shape itself is
+ * config-independent.
+ */
+export function generateCloseJobWorkflow(_config: ResolvedCIConfig): string {
+	return `\
+# dorfl — the ISSUE CLOSE-JOB in CI (capability E, prd runner-in-ci).
+# EMITTED by \`dorfl install-ci\`; the human commits it. DO NOT hand-edit a
+# copy — re-run install-ci to upgrade the shell.
+#
+# TRIGGER — a MERGE to main. There is NO native "PR merged" event, so this uses
+# \`push: {branches: [main]}\` (NOT \`pull_request: closed\` + a merged guard):
+#   * it fires for BOTH a PR-merge AND a direct push to main; and
+#   * it ALWAYS runs with a normal (non-fork-restricted) GITHUB_TOKEN that can
+#     actually CLOSE issues — a \`pull_request\` event from a FORK gets a read-only
+#     token and could not close (a real limitation we deliberately avoid).
+#
+# WHAT IT DOES — \`dorfl close-merged-issues\` resolves which source issue(s)
+# the landed work closes and closes them. CI owns ONLY this job + the trigger; the
+# command CONSUMES the engine's UNCHANGED pieces and re-implements none of them:
+#   * the RESOLUTION (resolveClosingIssue): a lone task closes its own \`issue:\`;
+#     a fanned task reaches the number via \`task.prd: → prd issue:\`.
+#   * the "prd complete?" QUERY (prd-complete-query, done): a prd's issue closes
+#     ONLY when ALL its \`prd:<slug>\` tasks are in work/done/.
+#   * the CLOSE (IssueProvider.closeIssue): the atomic comment+close seam — NO
+#     direct \`gh\` in the engine core; any comment rides this close, never the PR
+#     comment seam.
+#
+# CI runs IN-PLACE (the CI container IS the isolation): NO --isolated/--remote/
+# registry (laptop-only affordances). The concurrency group below serialises
+# overlapping close ticks on main.
+#
+# SAFETY (US #9): the running job is FORBIDDEN from editing the workflows tree
+# under .github. It requests NO \`workflows\` permission, so it can never rewrite
+# its own triggers. It needs only \`contents: read\` (read the work/ tree) +
+# \`issues: write\` (close the issue).
+
+name: close-job
+
+on:
+  # A merge to main: fires for a PR-merge AND a direct push, ALWAYS with a token
+  # that can close issues (unlike a fork \`pull_request\` event's read-only token).
+  push:
+    branches:
+      - main
+
+# Serialise overlapping close ticks on main; the close-job mutates only the ISSUE
+# (not the main-CAS), so this just avoids redundant concurrent passes.
+concurrency:
+  group: close-job-\${{ github.ref }}
+  cancel-in-progress: false
+
+# NO \`workflows\` permission: the running job can NEVER edit the workflows tree
+# under .github (US #9). It needs only to READ the work/ tree and CLOSE issues.
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  close-merged-issues:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: ./.github/actions/dorfl-setup
+      - name: close issues whose work has landed on main
+        # In-place in this checkout (no --isolated/--remote): the CI container IS
+        # the isolation. Resolves the closing issue(s) from the work/ tree, runs
+        # the "prd complete?" query for the prd case, and closes via the provider
+        # seam — all UNCHANGED engine pieces, consumed not re-built.
+        env:
+          GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+        run: dorfl close-merged-issues
+`;
+}
+
+/** A single structural problem found in the generated workflow. */
+export interface CloseJobProblem {
+	/** A short, stable id for the violated invariant (for tests/assertions). */
+	id: string;
+	/** Human-readable description of what is missing or wrong. */
+	message: string;
+}
+
+/** The result of {@link validateCloseJobWorkflow}. */
+export interface CloseJobValidation {
+	/** True iff the workflow satisfies EVERY structural invariant. */
+	ok: boolean;
+	/** Each violated invariant (empty when `ok`). */
+	problems: CloseJobProblem[];
+}
+
+/**
+ * Structurally validate the close-job workflow against the task's acceptance
+ * criteria. Dependency-free (no YAML lib): presence/shape assertions over the raw
+ * text, mirroring {@link validateAdvanceLifecycleWorkflow}.
+ */
+export function validateCloseJobWorkflow(text: string): CloseJobValidation {
+	const problems: CloseJobProblem[] = [];
+	const require = (id: string, present: boolean, message: string): void => {
+		if (!present) {
+			problems.push({id, message});
+		}
+	};
+
+	// The OPERATIVE (non-comment) lines: the prohibitions below (no `--isolated`/
+	// `--remote`/`pull_request` trigger/`.github/workflows` self-edit/direct `gh
+	// issue close`) are about what the job DOES, not what the explanatory comments
+	// MENTION. Strip full-line `#` comments before the negative checks; the positive
+	// presence checks run over the full text (comments are harmless there).
+	const operative = text
+		.split('\n')
+		.filter((line) => !/^\s*#/.test(line))
+		.join('\n');
+
+	// --- TRIGGER: a merge to main via `push: {branches: [main]}` ----------------
+	require('trigger-push-main', /\bon:\s*[\s\S]*?push:\s*[\s\S]*?branches:\s*[\s\S]*?-\s*main\b/.test(
+		text,
+	), 'must trigger on a merge to main via `on.push.branches: [main]` (fires for ' +
+		'PR-merges AND direct pushes, always with a token that can close issues).');
+	// NOT the `pull_request` trigger: a fork PR gets a read-only token that cannot
+	// close, and there is no native "PR merged" event — `push: [main]` is chosen.
+	require('not-pull-request-trigger', !/\bpull_request:/.test(
+		operative,
+	), 'must NOT use the `pull_request` trigger (a fork PR gets a read-only token ' +
+		'that cannot close; `push: [main]` is the chosen trigger).');
+	// And it must NOT be the build/task tick's cron/dispatch shape — the close-job
+	// is event-driven on a merge, not a scheduled drain.
+	require('no-cron-trigger', !/\bschedule:\s*[\s\S]*?-\s*cron:/.test(
+		operative,
+	), 'the close-job is merge-triggered, NOT a cron drain (no `on.schedule.cron`).');
+	require('no-answer-loop-push-trigger', !/work\/questions\//.test(
+		text,
+	), 'the close-job must NOT carry the `push work/questions/**` (answer-loop) ' +
+		'trigger — that is the advance-lifecycle task.');
+
+	// --- INVOKES the close machinery via the existing command -------------------
+	// Scoped to operative (non-comment) lines: the explanatory comment NAMES the
+	// command, so a real `run:` step (not the doc) must carry it.
+	require('invokes-close-merged-issues', /dorfl close-merged-issues\b/.test(
+		operative,
+	), 'must invoke `dorfl close-merged-issues` (the close-job driver that ' +
+		'CONSUMES the unchanged resolution + query + close).');
+	// It must NOT re-implement the close with a direct `gh issue close` (the close
+	// goes through the IssueProvider seam, not direct `gh` in CI).
+	require('no-direct-gh-issue-close', !/gh issue close\b/.test(
+		operative,
+	), 'the close must go through `dorfl close-merged-issues` (the provider ' +
+		'seam), NOT a direct `gh issue close` in the workflow.');
+	// It must NOT invoke a build/task/intake verb — the close-job only closes.
+	require('no-build-verbs', !/dorfl (?:do|advance|intake)\b/.test(
+		operative,
+	), 'the close-job must invoke ONLY `close-merged-issues`, not a build/task/' +
+		'intake verb (CI owns only the close job + trigger).');
+
+	// --- CI runs IN-PLACE: no isolation machinery ------------------------------
+	require('no-isolated-flag', !/--isolated\b/.test(
+		operative,
+	), 'CI runs IN-PLACE (the container IS the isolation): no `--isolated` flag.');
+	require('no-remote-flag', !/--remote\b/.test(
+		operative,
+	), 'CI runs IN-PLACE: no `--remote` flag (laptop-only affordance).');
+
+	// --- A CI concurrency group ------------------------------------------------
+	require('concurrency-group', /\bconcurrency:\s*[\s\S]*?group:/.test(
+		text,
+	), 'must carry a CI `concurrency.group` so overlapping close ticks never collide.');
+
+	// --- US #9: NO `workflows` permission; cannot self-edit triggers ------------
+	require('no-workflows-permission', !/\bworkflows:\s*write\b/.test(
+		text,
+	), 'the running job must request NO `workflows` permission (US #9: it can ' +
+		'never edit `.github/workflows/**` / rewrite its own triggers).');
+	require('never-edits-dot-github-workflows', !/\.github\/workflows\//.test(
+		operative,
+	), 'no emitted job step may touch `.github/workflows/**` (US #9).');
+	// It DOES need `issues: write` (to close) — assert the permission is present so
+	// the close can actually happen with the merge-to-main token. Scoped to operative
+	// lines: the safety comment names the permission, so the real block must carry it.
+	require('issues-write-permission', /\bissues:\s*write\b/.test(
+		operative,
+	), 'must request `issues: write` so the merge-to-main token can close the issue.');
+
+	return {ok: problems.length === 0, problems};
+}

package/src/close-job.ts

@@ -0,0 +1,319 @@
+/**
+ * The CI CLOSE-JOB driver (prd `runner-in-ci`, capability E; task
+ * `install-ci-close-job-workflow`). When work lands on `main`, this resolves which
+ * source issue(s) the landed work closes and closes them — but it OWNS none of the
+ * machinery it relies on. It is the thin JOB that WIRES three UNCHANGED engine
+ * pieces together (the Out-of-Scope fence: do NOT re-build them):
+ *
+ *   - the RESOLUTION — {@link resolveClosingIssue} (`frontmatter.ts`): an artifact
+ *     uses `issue:` XOR `prd:`; a lone task closes its own `issue:` directly, a
+ *     fanned task reaches the number via `task.prd: → work/prds/<prd>.md prd
+ *     issue:`, and `prd:` WINS on a (hand-edited) conflict;
+ *   - the QUERY — {@link isSpecComplete} (`spec-complete.ts`, task
+ *     `prd-complete-query`, done): a spec is COMPLETE iff ≥1 `spec:<slug>` task AND
+ *     all such tasks are in `work/done/`;
+ *   - the CLOSE — {@link IssueProvider.closeIssue} (`issue-provider.ts`, the atomic
+ *     comment+close seam intake already uses): NO direct `gh` in this core; any
+ *     informational comment rides the SAME close call (never the PR seam
+ *     `postPRComment`).
+ *
+ * The closure conditions, per artifact kind:
+ *
+ *   - a **lone task** (`issue:`, no `prd:`) that resides in `work/done/` — its PR
+ *     merged, so its own issue closes (reason `completed`);
+ *   - a **prd** (`issue:`) — closes ONLY when {@link isSpecComplete} says ALL its
+ *     `spec:<slug>` tasks are in `work/done/` (reason `completed`).
+ *
+ * A prd whose query is NOT yet complete is left OPEN (the final fanned task's
+ * merge tick closes it). A lone task still outside `work/done/` is skipped. The
+ * close DEGRADES (never throws) on a missing/unauthenticated provider, exactly
+ * like intake's bounce close — the run reports the real cause and stays exit-0.
+ *
+ * This is the JOB the close-job WORKFLOW (capability E) invokes via
+ * `dorfl close-merged-issues`; the workflow is triggered on a merge to
+ * `main` (`push: {branches: [main]}`). The driver itself is provider-pluggable
+ * (it takes an {@link IssueProvider}) and reads only the `work/` tree.
+ */
+
+import {readdirSync, readFileSync} from 'node:fs';
+import {basename, join} from 'node:path';
+import {
+	TASK_LIFECYCLE_FOLDERS,
+	SPEC_FOLDERS,
+	type WorkFolderKey,
+	workFolderPath,
+	workItemRel,
+	isWorkItemFile,
+} from './work-layout.js';
+import {parseFrontmatter, resolveClosingIssue} from './frontmatter.js';
+import {isSpecComplete} from './spec-complete.js';
+import {
+	type IssueProvider,
+	type IssueCloseReason,
+	GitHubIssueProvider,
+} from './issue-provider.js';
+
+/** The task lifecycle folders a lone-task `issue:` can reside in. */
+const TASK_FOLDERS = TASK_LIFECYCLE_FOLDERS;
+
+/** The spec folders an `issue:`-bearing spec can reside in. */
+const SPEC_LIFECYCLE_FOLDERS = SPEC_FOLDERS;
+
+/** Why the close-job acted (or did not act) on a candidate issue. */
+export type CloseDecision =
+	| 'closed' // the issue was closed via the provider seam
+	| 'not-complete' // a prd whose query says it is not yet complete → left open
+	| 'not-landed' // a lone task not yet in work/done/ → left open
+	| 'close-failed'; // closure condition held but the provider close degraded
+
+/** One candidate the close-job considered, with the decision it reached. */
+export interface CloseCandidate {
+	/** The resolved issue number. */
+	issueNumber: number;
+	/** Whether the closing link was a lone task's `issue:` or a spec's `issue:`. */
+	via: 'issue' | 'spec';
+	/** The slug of the artifact carrying the closing link (spec slug / task slug). */
+	slug: string;
+	/** What the close-job decided for this candidate. */
+	decision: CloseDecision;
+	/** The provider's failure detail when `decision === 'close-failed'`. */
+	reason?: string;
+}
+
+/** The result of one {@link runCloseJob} pass over a repo's `work/` tree. */
+export interface CloseJobResult {
+	/** Every candidate considered, with its decision (for the human-facing log). */
+	candidates: CloseCandidate[];
+	/** Issue numbers actually closed this pass. */
+	closed: number[];
+}
+
+/** Options for {@link runCloseJob}. */
+export interface CloseJobOptions {
+	/** The repo working-tree root whose `work/` tree to scan. */
+	repoPath: string;
+	/** The issue seam to close through (GitHub adapter in production; a stub in tests). */
+	issueProvider: IssueProvider;
+	/** Environment passed through to the provider (for the `gh` adapter). */
+	env?: NodeJS.ProcessEnv;
+}
+
+/** List the `.md` filenames in `<repoPath>/work/<folder>/`, sorted; `[]` if absent. */
+function listMarkdown(repoPath: string, folder: WorkFolderKey): string[] {
+	const dir = workFolderPath(repoPath, folder);
+	let entries: string[];
+	try {
+		entries = readdirSync(dir);
+	} catch {
+		return [];
+	}
+	return entries.filter((name) => isWorkItemFile(name)).sort();
+}
+
+/**
+ * Read a prd's `issue:` number by slug, scanning the prd folders. Returns
+ * `undefined` when no prd with that slug carries an `issue:` (a prd with no source
+ * issue, or a typo'd `prd:` hop — degrades to "no issue to close", never crashes).
+ */
+function specIssueNumber(
+	repoPath: string,
+	specSlug: string,
+): number | undefined {
+	for (const folder of SPEC_LIFECYCLE_FOLDERS) {
+		for (const file of listMarkdown(repoPath, folder)) {
+			const fm = parseFrontmatter(
+				readFileSync(join(repoPath, workItemRel(folder, file)), 'utf8'),
+			);
+			const slug = fm.slug ?? basename(file, '.md');
+			if (slug === specSlug && fm.issue !== undefined) {
+				return fm.issue;
+			}
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Resolve the DEDUPLICATED set of closure candidates from the `work/` tree, each
+ * via the UNCHANGED {@link resolveClosingIssue}:
+ *
+ *   - every prd carrying `issue:` (in `work/prds/ready/` or `work/prds/tasked/`) is a
+ *     prd-kind candidate keyed on its own `prd:` query;
+ *   - every LONE task (`issue:` and NO `prd:`) is an `issue`-kind candidate.
+ *
+ * A fanned task carries `prd:` (NOT its own `issue:`), so it reaches the number
+ * through its prd's candidate, never as its own — the issue number lives ONLY on
+ * the prd. Deduplicated by issue number: a prd enumerated once even though many
+ * tasks point at it. Prd candidates are listed before lone-task candidates, each
+ * group slug-sorted, for a deterministic log.
+ */
+function resolveCandidates(repoPath: string): {
+	issueNumber: number;
+	via: 'issue' | 'spec';
+	slug: string;
+}[] {
+	const seen = new Set<number>();
+	const specCandidates: {issueNumber: number; via: 'spec'; slug: string}[] = [];
+	const taskCandidates: {issueNumber: number; via: 'issue'; slug: string}[] =
+		[];
+
+	// Spec candidates: a spec's `issue:` closes when ITS query is complete.
+	for (const folder of SPEC_LIFECYCLE_FOLDERS) {
+		for (const file of listMarkdown(repoPath, folder)) {
+			const fm = parseFrontmatter(
+				readFileSync(join(repoPath, workItemRel(folder, file)), 'utf8'),
+			);
+			const slug = fm.slug ?? basename(file, '.md');
+			const closing = resolveClosingIssue(fm);
+			// A prd's own closing link is its `issue:` (a prd has no `prd:`); on the
+			// hand-edit conflict `prd:` wins via resolveClosingIssue, so only a true
+			// `issue:`-bearing prd becomes a candidate here.
+			if (closing?.via === 'issue' && !seen.has(closing.issue)) {
+				seen.add(closing.issue);
+				specCandidates.push({issueNumber: closing.issue, via: 'spec', slug});
+			}
+		}
+	}
+
+	// Lone-task candidates: a task with `issue:` and NO `prd:` closes its OWN
+	// issue directly when it lands in work/done/.
+	for (const folder of TASK_FOLDERS) {
+		for (const file of listMarkdown(repoPath, folder)) {
+			const fm = parseFrontmatter(
+				readFileSync(join(repoPath, workItemRel(folder, file)), 'utf8'),
+			);
+			const slug = fm.slug ?? basename(file, '.md');
+			const closing = resolveClosingIssue(fm);
+			// `resolveClosingIssue` returns `via: 'issue'` ONLY when there is no `prd:`
+			// (prd wins on conflict), so a fanned task never lands here — it reaches
+			// its issue through the prd candidate above.
+			if (closing?.via === 'issue' && !seen.has(closing.issue)) {
+				seen.add(closing.issue);
+				taskCandidates.push({issueNumber: closing.issue, via: 'issue', slug});
+			}
+		}
+	}
+
+	specCandidates.sort((a, b) => a.slug.localeCompare(b.slug));
+	taskCandidates.sort((a, b) => a.slug.localeCompare(b.slug));
+	return [...specCandidates, ...taskCandidates];
+}
+
+/** True iff the lone task with this slug resides in `work/done/`. */
+function loneTaskLanded(repoPath: string, taskSlug: string): boolean {
+	for (const file of listMarkdown(repoPath, 'done')) {
+		const fm = parseFrontmatter(
+			readFileSync(join(repoPath, workItemRel('done', file)), 'utf8'),
+		);
+		const slug = fm.slug ?? basename(file, '.md');
+		if (slug === taskSlug) {
+			return true;
+		}
+	}
+	return false;
+}
+
+/** The closing comment posted (atomically, on the close call) for each kind. */
+function closeComment(via: 'issue' | 'spec', slug: string): string {
+	return via === 'spec'
+		? `Closed by dorfl: every task of spec \`${slug}\` has landed in \`work/done/\`.`
+		: `Closed by dorfl: the task \`${slug}\` has landed in \`work/done/\`.`;
+}
+
+/**
+ * Run the close-job over a repo's `work/` tree: resolve the closure candidates,
+ * apply the per-kind closure condition (a landed lone task; a prd whose
+ * {@link isSpecComplete} query holds), and close the qualifying issues through the
+ * {@link IssueProvider.closeIssue} seam (reason `completed`, an informational
+ * comment riding the SAME atomic close). REUSES the unchanged resolution + query +
+ * close — it re-implements NONE of them. NEVER throws: a degraded provider close
+ * is reported as `close-failed`, not a crash (the terminal CI tick stays exit-0).
+ */
+export async function runCloseJob(
+	options: CloseJobOptions,
+): Promise<CloseJobResult> {
+	const {repoPath, issueProvider, env} = options;
+	const candidates: CloseCandidate[] = [];
+	const closed: number[] = [];
+	const completedReason: IssueCloseReason = 'completed';
+
+	for (const cand of resolveCandidates(repoPath)) {
+		// The closure CONDITION per kind — the only place this job decides; the
+		// computation of "complete" / "landed" is the UNCHANGED engine query.
+		let shouldClose: boolean;
+		let notReady: CloseDecision;
+		if (cand.via === 'spec') {
+			shouldClose = isSpecComplete({repoPath, slug: cand.slug}).complete;
+			notReady = 'not-complete';
+		} else {
+			shouldClose = loneTaskLanded(repoPath, cand.slug);
+			notReady = 'not-landed';
+		}
+
+		if (!shouldClose) {
+			candidates.push({
+				issueNumber: cand.issueNumber,
+				via: cand.via,
+				slug: cand.slug,
+				decision: notReady,
+			});
+			continue;
+		}
+
+		// CLOSE via the provider seam (NO direct `gh`): comment + reason + close in
+		// ONE atomic call, exactly the seam intake's bounce uses.
+		const result = await issueProvider.closeIssue({
+			cwd: repoPath,
+			issueNumber: cand.issueNumber,
+			comment: closeComment(cand.via, cand.slug),
+			reason: completedReason,
+			env,
+		});
+		if (result.closed) {
+			closed.push(cand.issueNumber);
+			candidates.push({
+				issueNumber: cand.issueNumber,
+				via: cand.via,
+				slug: cand.slug,
+				decision: 'closed',
+			});
+		} else {
+			candidates.push({
+				issueNumber: cand.issueNumber,
+				via: cand.via,
+				slug: cand.slug,
+				decision: 'close-failed',
+				reason: result.reason ?? result.instruction,
+			});
+		}
+	}
+
+	return {candidates, closed};
+}
+
+/** Options for {@link performCloseMergedIssues} (the CLI entry). */
+export interface PerformCloseMergedIssuesOptions {
+	/** The repo working-tree root (default: the CLI's cwd). */
+	repoPath: string;
+	/** Override the `gh` binary (tests inject a stub); production uses `gh` on PATH. */
+	ghBin?: string;
+	/** Environment passed through to the provider. */
+	env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * The CLI entry the close-job WORKFLOW invokes (`dorfl
+ * close-merged-issues`): construct the GitHub issue provider and run the
+ * close-job over the checkout's `work/` tree. Provider-pluggable via
+ * {@link runCloseJob}; this wrapper only picks the default (GitHub) adapter.
+ */
+export async function performCloseMergedIssues(
+	options: PerformCloseMergedIssuesOptions,
+): Promise<CloseJobResult> {
+	const issueProvider = new GitHubIssueProvider({ghBin: options.ghBin});
+	return runCloseJob({
+		repoPath: options.repoPath,
+		issueProvider,
+		env: options.env,
+	});
+}