@link-assistant/hive-mind 2.19.1 → 2.20.0

package/src/solve.ensure-sub-issues.lib.mjs

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+import { QUIET_PROBE } from './quiet-probe.lib.mjs';
+import { ensureUseM } from './use-m-bootstrap.lib.mjs';
+
+/**
+ * `--ensure-all-sub-issues-addressed` restart loop for solve.mjs (issue #2212).
+ *
+ * After the main solve completes, this module lists the GitHub native
+ * sub-issues of the issue being solved and checks that the pull request
+ * description closes every one of them with a reference GitHub actually
+ * recognizes. When references are missing it restarts the AI tool, asking it to
+ * double check that each of those sub-issues was really addressed in this single
+ * pull request and to add the missing closing references. It keeps restarting
+ * until nothing is missing or the configured restart limit is reached.
+ *
+ * This is what makes `/solve <repository-url>` safe: the combined issue's
+ * sub-issues are exactly the repository's open issues, so the check guarantees
+ * the single pull request lists all of them and closes them on merge.
+ *
+ * The pure detection helpers live in `solve.ensure-sub-issues.detect.lib.mjs`.
+ *
+ * @see https://github.com/link-assistant/hive-mind/issues/2212
+ */
+
+// Check if use is already defined globally (when imported from solve.mjs)
+// If not, fetch it (when running standalone)
+if (typeof globalThis.use === 'undefined') {
+  await ensureUseM();
+}
+const use = globalThis.use;
+
+// Use command-stream for consistent $ behavior across runtimes
+const { $: __rawDollar$ } = await use('command-stream');
+const { wrapDollarWithGhRetry } = await import('./github-rate-limit.lib.mjs');
+const $ = wrapDollarWithGhRetry(__rawDollar$);
+
+const lib = await import('./lib.mjs');
+const { log, cleanErrorMessage } = lib;
+
+const restartShared = await import('./solve.restart-shared.lib.mjs');
+const { executeToolIteration, isApiError, isUsageLimitReached } = restartShared;
+
+const sentryLib = await import('./sentry.lib.mjs');
+const { reportError } = sentryLib;
+
+const detectLib = await import('./solve.ensure-sub-issues.detect.lib.mjs');
+const { DEFAULT_ENSURE_SUB_ISSUES_LIMIT, ENSURE_SUB_ISSUES_PROMPT, buildEnsureSubIssuesFeedback, buildMissingReferenceBlock, findMissingSubIssueReferences, formatEnsureSubIssuesLimit, normalizeEnsureSubIssuesLimit, normalizeSubIssueEntry } = detectLib;
+
+// Re-export the pure helpers so importers only need this module.
+export { DEFAULT_ENSURE_SUB_ISSUES_LIMIT, ENSURE_SUB_ISSUES_PROMPT, buildEnsureSubIssuesFeedback, buildMissingReferenceBlock, findMissingSubIssueReferences, formatEnsureSubIssuesLimit, normalizeEnsureSubIssuesLimit, normalizeSubIssueEntry };
+
+/**
+ * Hard cap on consecutive AI errors, so "unlimited" cannot spin forever.
+ * Mirrors the keep-working loop (issue #1883).
+ */
+const MAX_CONSECUTIVE_ERRORS = 3;
+
+/**
+ * List the GitHub native sub-issues of an issue.
+ *
+ * `--paginate` is required: the endpoint returns 30 entries per page by default
+ * and a parent may have up to 100 sub-issues.
+ *
+ * @param {object} params
+ * @returns {Promise<Array<object>>}
+ */
+export const fetchSubIssues = async ({ owner, repo, issueNumber }) => {
+  // Issue #2135: `mirror: false` — the payload is inspected here, not shown.
+  const result = await $(QUIET_PROBE)`gh api repos/${owner}/${repo}/issues/${issueNumber}/sub_issues --paginate`;
+  if (result.code !== 0) {
+    const output = (result.stderr || result.stdout || '').toString().trim();
+    throw new Error(output || `gh api sub_issues exited with code ${result.code}`);
+  }
+  const parsed = JSON.parse(result.stdout.toString() || '[]');
+  return Array.isArray(parsed) ? parsed : [];
+};
+
+/**
+ * Fetch the pull request description (and title, so a closing reference placed
+ * in the title is honored too).
+ *
+ * @param {object} params
+ * @returns {Promise<string>}
+ */
+export const fetchPullRequestText = async ({ owner, repo, prNumber }) => {
+  // Issue #2135: `mirror: false` — the body can be very large.
+  const result = await $(QUIET_PROBE)`gh api repos/${owner}/${repo}/pulls/${prNumber}`;
+  if (result.code !== 0) {
+    const output = (result.stderr || result.stdout || '').toString().trim();
+    throw new Error(output || `gh api pulls exited with code ${result.code}`);
+  }
+  const pr = JSON.parse(result.stdout.toString() || '{}');
+  // The title is included on purpose: a closing reference is recognized by
+  // GitHub in the pull request title as well as in its description.
+  return [pr.title || '', pr.body || ''].join('\n\n');
+};
+
+/**
+ * Runs the `--ensure-all-sub-issues-addressed` restart iterations.
+ *
+ * @param {object} params
+ * @param {string} params.issueUrl
+ * @param {string} params.owner
+ * @param {string} params.repo
+ * @param {string|number} params.issueNumber
+ * @param {string|number} params.prNumber
+ * @param {string} params.branchName
+ * @param {string} params.tempDir
+ * @param {string} [params.workspaceTmpDir]
+ * @param {object} params.argv
+ * @param {function} params.cleanupClaudeFile
+ * @returns {Promise<{sessionId, anthropicTotalCostUSD, publicPricingEstimate, pricingInfo}|null>}
+ */
+export const runEnsureAllSubIssuesAddressed = async ({ issueUrl, owner, repo, issueNumber, prNumber, branchName, tempDir, workspaceTmpDir, argv, cleanupClaudeFile }) => {
+  const limit = normalizeEnsureSubIssuesLimit(argv.ensureAllSubIssuesAddressed ?? argv['ensure-all-sub-issues-addressed']);
+  if (!limit || !prNumber || !issueNumber) {
+    return null;
+  }
+
+  await log('');
+  await log(`🧩 ENSURE-SUB-ISSUES: Verifying the pull request description closes every sub-issue of #${issueNumber} (limit: ${formatEnsureSubIssuesLimit(limit)} restart(s))`);
+
+  let subIssues;
+  try {
+    subIssues = await fetchSubIssues({ owner, repo, issueNumber });
+  } catch (error) {
+    reportError(error, { context: 'ensure_sub_issues_fetch', owner, repo, issueNumber, operation: 'fetch_sub_issues' });
+    await log(`⚠️  ENSURE-SUB-ISSUES: Could not list sub-issues: ${cleanErrorMessage(error)}`, { level: 'warning' });
+    return null;
+  }
+
+  if (subIssues.length === 0) {
+    await log(`✅ ENSURE-SUB-ISSUES: Issue #${issueNumber} has no sub-issues. Nothing to verify.`);
+    return null;
+  }
+
+  await log(`   Sub-issues to verify: ${subIssues.length}`);
+
+  // Merge state is only used to enrich the restart prompt; a failure here is
+  // never a reason to skip the check.
+  let currentMergeStateStatus = null;
+  try {
+    const prStateResult = await $`gh api repos/${owner}/${repo}/pulls/${prNumber} --jq '.mergeStateStatus'`;
+    if (prStateResult.code === 0) {
+      currentMergeStateStatus = prStateResult.stdout.toString().trim();
+    }
+  } catch {
+    // Ignore errors getting merge state
+  }
+
+  let sessionId;
+  let anthropicTotalCostUSD;
+  let publicPricingEstimate;
+  let pricingInfo;
+  let consecutiveErrors = 0;
+  let iteration = 0;
+
+  while (true) {
+    let prText;
+    try {
+      prText = await fetchPullRequestText({ owner, repo, prNumber });
+    } catch (error) {
+      reportError(error, { context: 'ensure_sub_issues_fetch_pr', owner, repo, prNumber, operation: 'fetch_pr_body' });
+      await log(`⚠️  ENSURE-SUB-ISSUES: Could not read the pull request description: ${cleanErrorMessage(error)}`, { level: 'warning' });
+      break;
+    }
+
+    const { missing, total } = findMissingSubIssueReferences({ text: prText, subIssues, owner, repo });
+
+    if (missing.length === 0) {
+      if (iteration === 0) {
+        await log(`✅ ENSURE-SUB-ISSUES: All ${total} sub-issue(s) are closed by the pull request description.`);
+      } else {
+        await log(`✅ ENSURE-SUB-ISSUES: All ${total} sub-issue(s) are closed by the pull request description after ${iteration} restart(s).`);
+      }
+      break;
+    }
+
+    if (iteration >= limit) {
+      await log(`🛑 ENSURE-SUB-ISSUES: Reached the restart limit (${formatEnsureSubIssuesLimit(limit)}) with ${missing.length}/${total} sub-issue(s) still missing a closing reference.`);
+      for (const subIssue of missing.slice(0, 20)) {
+        await log(`   • #${subIssue.number}${subIssue.title ? ` — ${subIssue.title}` : ''}`);
+      }
+      await log('   Add these lines to the pull request description to close them on merge:');
+      await log(buildMissingReferenceBlock(missing, { owner, repo }));
+      break;
+    }
+
+    iteration++;
+    await log('');
+    await log(`🔁 ENSURE-SUB-ISSUES iteration ${iteration}/${formatEnsureSubIssuesLimit(limit)}: ${missing.length}/${total} sub-issue(s) missing a closing reference, restarting...`);
+    for (const subIssue of missing.slice(0, 20)) {
+      await log(`   • #${subIssue.number}${subIssue.title ? ` — ${subIssue.title}` : ''}`);
+    }
+
+    // Issue #1572 pattern: sync the local branch with remote before restarting.
+    try {
+      const pullResult = await $({ cwd: tempDir })`git pull origin ${branchName} 2>&1`;
+      if (pullResult.code === 0) {
+        await log(`   Synced local branch ${branchName} from remote`, { verbose: true });
+      } else {
+        await log(`   Warning: git pull failed (code ${pullResult.code}); continuing with local state`, { level: 'warning' });
+      }
+    } catch (error) {
+      reportError(error, { context: 'ensure_sub_issues_git_pull', branchName, operation: 'git_pull' });
+      await log(`   Warning: git pull error: ${cleanErrorMessage(error)}`, { level: 'warning' });
+    }
+
+    const feedbackLines = buildEnsureSubIssuesFeedback({ missing, total, iteration, limit, owner, repo, issueNumber });
+
+    const iterationResult = await executeToolIteration({
+      issueUrl,
+      owner,
+      repo,
+      issueNumber,
+      prNumber,
+      branchName,
+      tempDir,
+      workspaceTmpDir,
+      mergeStateStatus: currentMergeStateStatus,
+      feedbackLines,
+      argv: {
+        ...argv,
+        promptEnsureAllRequirementsAreMet: true,
+        // Prevent recursion inside the restart iteration.
+        ensureAllSubIssuesAddressed: 0,
+        'ensure-all-sub-issues-addressed': 0,
+      },
+    });
+
+    if (iterationResult) {
+      if (iterationResult.sessionId) sessionId = iterationResult.sessionId;
+      if (iterationResult.anthropicTotalCostUSD) anthropicTotalCostUSD = iterationResult.anthropicTotalCostUSD;
+      if (iterationResult.publicPricingEstimate) publicPricingEstimate = iterationResult.publicPricingEstimate;
+      if (iterationResult.pricingInfo) pricingInfo = iterationResult.pricingInfo;
+    }
+
+    if (isUsageLimitReached(iterationResult)) {
+      await log('🛑 ENSURE-SUB-ISSUES: Usage limit reached during restart. Stopping.');
+      break;
+    }
+    if (isApiError(iterationResult)) {
+      consecutiveErrors++;
+      await log(`⚠️  ENSURE-SUB-ISSUES: API error during restart (${consecutiveErrors}/${MAX_CONSECUTIVE_ERRORS} consecutive).`, { level: 'warning' });
+      if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
+        await log('🛑 ENSURE-SUB-ISSUES: Too many consecutive errors. Stopping.');
+        break;
+      }
+    } else {
+      consecutiveErrors = 0;
+    }
+
+    await log(`✅ ENSURE-SUB-ISSUES iteration ${iteration}/${formatEnsureSubIssuesLimit(limit)} complete`);
+    await log('');
+  }
+
+  try {
+    await cleanupClaudeFile?.(tempDir, branchName, null, argv);
+  } catch (error) {
+    reportError(error, { context: 'ensure_sub_issues_cleanup', branchName, operation: 'cleanup_claude_file' });
+  }
+
+  if (iteration === 0) return null;
+  return { sessionId, anthropicTotalCostUSD, publicPricingEstimate, pricingInfo };
+};
+
+export default {
+  DEFAULT_ENSURE_SUB_ISSUES_LIMIT,
+  ENSURE_SUB_ISSUES_PROMPT,
+  fetchSubIssues,
+  fetchPullRequestText,
+  findMissingSubIssueReferences,
+  normalizeEnsureSubIssuesLimit,
+  formatEnsureSubIssuesLimit,
+  runEnsureAllSubIssuesAddressed,
+};

package/src/solve.mjs

@@ -47,6 +47,7 @@ const { startAutoRestartUntilMergeable } = await import('./solve.auto-merge.lib.
 const { runAutoEnsureRequirements } = await import('./solve.auto-ensure.lib.mjs');
 const { runKeepWorkingUntilDone } = await import('./solve.keep-working.lib.mjs');
 const { runEscalation } = await import('./solve.escalate.lib.mjs');
+const { runEnsureAllSubIssuesAddressed } = await import('./solve.ensure-sub-issues.lib.mjs');
 const { finalizeSolveProcess } = await import('./solve.finalize.lib.mjs');
 const exitHandler = await import('./exit-handler.lib.mjs');
 const { initializeExitHandler, installGlobalExitHandlers, safeExit: baseSafeExit, logActiveHandles } = exitHandler;
@@ -152,6 +153,25 @@ if (!issueUrl) {
   await log('Run "solve.mjs --help" for more information', { level: 'error' });
   await safeExit(1, 'Missing required GitHub URL');
 }
+// Issue #2212: repository mode. When a repository URL is given instead of an
+// issue/pull request URL, collect every open issue of that repository, create a
+// single combined issue that lists them as GitHub native sub-issues, and solve
+// that issue instead — so one pull request can close all of them at once.
+{
+  const { resolveRepositoryModeTarget } = await import('./solve.repository-mode.run.lib.mjs');
+  const repositoryMode = await resolveRepositoryModeTarget({ url: issueUrl, log });
+  if (repositoryMode.handled) {
+    if (repositoryMode.error) {
+      await log(`Error: ${repositoryMode.error}`, { level: 'error' });
+      await safeExit(1, 'Repository mode failed');
+    }
+    issueUrl = repositoryMode.issueUrl;
+    argv['issue-url'] = repositoryMode.issueUrl;
+    // Repository mode always asks for deep analysis and always double checks
+    // that the pull request lists every issue it is supposed to close.
+    Object.assign(argv, repositoryMode.argvOverrides);
+  }
+}
 // Validate GitHub URL using validation module (more thorough check)
 const urlValidation = validateGitHubUrl(issueUrl);
 if (!urlValidation.isValid) {
@@ -1081,6 +1101,10 @@ try {
   applyRestartResult(await runEscalation({ issueUrl, owner, repo, issueNumber, prNumber, branchName, tempDir, workspaceTmpDir, argv, cleanupClaudeFile, resultSummary }));
   applyRestartResult(await runAutoEnsureRequirements({ issueUrl, owner, repo, issueNumber, prNumber, branchName, tempDir, argv, cleanupClaudeFile }));
   applyRestartResult(await runKeepWorkingUntilDone({ issueUrl, owner, repo, issueNumber, prNumber, branchName, tempDir, workspaceTmpDir, argv, cleanupClaudeFile, resultSummary }));
+  // Issue #2212: runs last on purpose — the earlier loops may still rewrite the
+  // pull request description, so the closing references are verified against its
+  // final state.
+  applyRestartResult(await runEnsureAllSubIssuesAddressed({ issueUrl, owner, repo, issueNumber, prNumber, branchName, tempDir, workspaceTmpDir, argv, cleanupClaudeFile }));
   // Start watch mode if enabled OR if we need to handle uncommitted changes
   if (argv.verbose) {
     await log('');
@@ -1197,6 +1221,20 @@ try {
       logsAttached = true;
     }
   }
+  // Issue #1516: Cleanup after all completion signals (it was before verifyResults, which
+  // caused premature commits). Issue #2211: but strictly BEFORE the auto-merge watch loop.
+  // It used to run after it, and `--auto-merge` therefore merged the placeholder into the
+  // default branch and only then reverted it on a branch nobody would look at again:
+  //
+  //   19:20:07  Initial commit with task details   (.gitkeep touched)
+  //   19:28:09  Merge pull request #3              (.gitkeep leaked into main)
+  //   19:28:13  Revert "Initial commit with task details"  <- 4 seconds too late
+  //
+  // https://github.com/konard/audio-decomposer/pull/3, docs/case-studies/issue-2211.
+  // Reverting first also lets the loop see the pull request as it really is: with the
+  // placeholder gone, a pull request that implemented nothing has an empty diff and the
+  // loop restarts the AI instead of merging an empty change.
+  await cleanupClaudeFile(tempDir, branchName, claudeCommitHash, argv);
   // Issue #2182: the AI working session is over at this point — everything below is
   // monitoring and merging, not working. The pull request must therefore be back in
   // "ready for review" BEFORE the auto-merge watch loop starts, because that loop can
@@ -1237,8 +1275,6 @@ try {
   }
   // Issue #1952: Final --attach-logs safety net + logsAttached reconciliation. See attach-logs-guarantee.lib.mjs.
   logsAttached = (await attachFinalLogIfMissing({ shouldAttachLogs, prNumber, owner, repo, $, log, sanitizeLogContent, getLogFile, attachLogToGitHub, argv, sessionId, tempDir, anthropicTotalCostUSD, resultModelUsage })) || logsAttached;
-  // Issue #1516: Cleanup after all signals (was before verifyResults, caused premature commits)
-  await cleanupClaudeFile(tempDir, branchName, claudeCommitHash, argv);
   await finalizeDevelopmentLog(); // Issue #1596/#2048: idempotent no-op on the success path (already committed before readiness signal); still preserves late/error work.
   await endWorkSession({ isContinueMode, prNumber, argv, log, formatAligned, $, logsAttached });
 } catch (error) {

package/src/solve.repository-mode.lib.mjs

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+
+/**
+ * Pure helpers for `/solve <github-repository-url>` — "repository mode"
+ * (issue #2212).
+ *
+ * When `/solve` is given a repository URL instead of an issue or pull request
+ * URL, it behaves similarly to `/fix --ci-cd`: it collects data about the
+ * repository, creates a single combined issue that lists every open issue in
+ * the repository as a GitHub native sub-issue, and then solves that combined
+ * issue as it normally would — producing one pull request that closes all of
+ * them at once.
+ *
+ * GitHub allows at most 100 sub-issues per parent issue
+ * (https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues),
+ * so when a repository has more open issues only the oldest 100 are attached
+ * and the rest are intentionally left out of this run.
+ *
+ * Everything in this module is network- and filesystem-free so it can be unit
+ * tested without GitHub access. The network side lives in
+ * `solve.repository-mode.run.lib.mjs`.
+ */
+
+/**
+ * GitHub's documented maximum number of sub-issues per parent issue.
+ * @see https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/adding-sub-issues
+ */
+export const MAX_SUB_ISSUES_PER_PARENT = 100;
+
+/** Marker that identifies an issue generated by `/solve <repository-url>`. */
+export const REPOSITORY_MODE_MARKER = '<!-- hive-mind-solve-repository-mode -->';
+
+/**
+ * Build the `gh api` arguments that list every open issue of a repository,
+ * oldest first.
+ *
+ * The REST `/issues` endpoint also returns pull requests; they are filtered out
+ * by {@link isPullRequestEntry}. `--paginate` is required because the endpoint
+ * returns at most 100 entries per page.
+ *
+ * @param {object} params
+ * @param {string} params.owner
+ * @param {string} params.repo
+ * @param {number} [params.perPage=100]
+ * @returns {string[]} argument list for `gh`
+ */
+export function buildOpenIssuesApiArgs({ owner, repo, perPage = MAX_SUB_ISSUES_PER_PARENT }) {
+  if (!owner || !repo) throw new Error('buildOpenIssuesApiArgs requires owner and repo');
+  const size = Number(perPage);
+  const safePerPage = Number.isInteger(size) && size >= 1 && size <= 100 ? size : MAX_SUB_ISSUES_PER_PARENT;
+  // Query parameters must be part of the endpoint string: `gh api -f key=value`
+  // switches the request to POST, which makes this endpoint fail with
+  // HTTP 422 ("title wasn't supplied").
+  return ['api', `repos/${owner}/${repo}/issues?state=open&sort=created&direction=asc&per_page=${safePerPage}`, '--paginate'];
+}
+
+/**
+ * The REST issues endpoint returns pull requests alongside issues; a pull
+ * request is identified by the presence of a `pull_request` object.
+ *
+ * @param {object} entry - raw REST issue entry
+ * @returns {boolean}
+ */
+export function isPullRequestEntry(entry) {
+  return Boolean(entry && typeof entry === 'object' && entry.pull_request);
+}
+
+/**
+ * Normalize a raw REST issue entry into the minimal shape the rest of
+ * repository mode needs.
+ *
+ * `id` is the REST database id (not the GraphQL node id): the sub-issues API
+ * takes `sub_issue_id` as a REST id.
+ *
+ * @param {object} entry
+ * @returns {{number: number, id: number, title: string, url: string, createdAt: string}|null}
+ */
+export function normalizeOpenIssueEntry(entry) {
+  if (!entry || typeof entry !== 'object') return null;
+  const number = Number(entry.number);
+  const id = Number(entry.id);
+  if (!Number.isInteger(number) || number <= 0) return null;
+  return {
+    number,
+    id: Number.isInteger(id) && id > 0 ? id : null,
+    title: String(entry.title || '').trim(),
+    url: String(entry.html_url || '').trim(),
+    createdAt: String(entry.created_at || '').trim(),
+  };
+}
+
+/**
+ * Filter out pull requests, normalize, sort oldest-first and cap the list at
+ * `limit` entries.
+ *
+ * Sorting is done here (not only server-side) so the selection is deterministic
+ * even when the caller passes an unsorted list. Ties fall back to the issue
+ * number, which is monotonic per repository.
+ *
+ * @param {Array<object>} entries - raw REST issue entries
+ * @param {object} [options]
+ * @param {number} [options.limit=MAX_SUB_ISSUES_PER_PARENT]
+ * @param {Array<number>} [options.exclude] - issue numbers to skip
+ * @returns {{selected: Array<object>, totalOpen: number, skipped: number}}
+ */
+export function selectOldestOpenIssues(entries, { limit = MAX_SUB_ISSUES_PER_PARENT, exclude = [] } = {}) {
+  const excluded = new Set((exclude || []).map(Number).filter(Number.isInteger));
+  const issues = (Array.isArray(entries) ? entries : [])
+    .filter(entry => !isPullRequestEntry(entry))
+    .map(normalizeOpenIssueEntry)
+    .filter(Boolean)
+    .filter(issue => !excluded.has(issue.number));
+
+  issues.sort((a, b) => {
+    const aTime = Date.parse(a.createdAt);
+    const bTime = Date.parse(b.createdAt);
+    if (Number.isFinite(aTime) && Number.isFinite(bTime) && aTime !== bTime) return aTime - bTime;
+    return a.number - b.number;
+  });
+
+  const cap = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : MAX_SUB_ISSUES_PER_PARENT;
+  const selected = issues.slice(0, cap);
+
+  return {
+    selected,
+    totalOpen: issues.length,
+    skipped: Math.max(0, issues.length - selected.length),
+  };
+}
+
+/**
+ * Title for the combined issue.
+ *
+ * @param {object} params
+ * @param {string} params.owner
+ * @param {string} params.repo
+ * @param {number} params.count - number of attached sub-issues
+ * @param {number} params.totalOpen - total open issues found in the repository
+ * @returns {string}
+ */
+export function buildCombinedIssueTitle({ owner, repo, count, totalOpen }) {
+  const repository = `${owner}/${repo}`;
+  if (totalOpen > count) {
+    return `Address the ${count} oldest open issues in ${repository} (of ${totalOpen} open)`;
+  }
+  if (count === 1) {
+    return `Address the single open issue in ${repository}`;
+  }
+  return `Address all ${count} open issues in ${repository}`;
+}
+
+function formatIssueLine(issue) {
+  const created = issue.createdAt ? ` — opened ${issue.createdAt.slice(0, 10)}` : '';
+  const title = issue.title ? ` ${issue.title}` : '';
+  return `- [ ] #${issue.number}${title}${created}`;
+}
+
+/**
+ * Build the closing-keyword block the pull request description must contain.
+ *
+ * GitHub requires the full syntax for *each* issue: a single keyword does not
+ * apply to a comma separated list of issues
+ * (https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue).
+ *
+ * @param {Array<{number: number}>} issues
+ * @param {string} [keyword='Fixes']
+ * @returns {string}
+ */
+export function buildClosingKeywordBlock(issues, keyword = 'Fixes') {
+  return (Array.isArray(issues) ? issues : []).map(issue => `${keyword} #${issue.number}`).join('\n');
+}
+
+/**
+ * Body of the combined issue.
+ *
+ * @param {object} params
+ * @param {{owner: string, repo: string, url: string}} params.repository
+ * @param {Array<object>} params.issues - selected sub-issues (oldest first)
+ * @param {number} params.totalOpen
+ * @param {number} [params.limit=MAX_SUB_ISSUES_PER_PARENT]
+ * @param {string} [params.sourceIssueUrl] - issue that introduced repository mode
+ * @returns {string}
+ */
+export function buildCombinedIssueBody({ repository, issues, totalOpen, limit = MAX_SUB_ISSUES_PER_PARENT, sourceIssueUrl = 'https://github.com/link-assistant/hive-mind/issues/2212' }) {
+  const list = Array.isArray(issues) ? issues : [];
+  const repositoryUrl = repository.url || `https://github.com/${repository.owner}/${repository.repo}`;
+  const skipped = Math.max(0, Number(totalOpen || 0) - list.length);
+
+  const lines = [REPOSITORY_MODE_MARKER, '', '## Objective', '', `Address every open issue listed below in [${repository.owner}/${repository.repo}](${repositoryUrl}) with a **single pull request**.`, '', `This issue was generated automatically by \`/solve ${repositoryUrl}\` (repository mode, see ${sourceIssueUrl}). Every issue below is attached to this issue as a GitHub native sub-issue.`, '', '## Scope', '', `- Open issues found in the repository: ${totalOpen}`, `- Issues attached as sub-issues of this issue: ${list.length}`, `- GitHub sub-issue limit per parent issue: ${limit}`];
+
+  if (skipped > 0) {
+    lines.push(`- Open issues intentionally left out of this run (newest ${skipped}, over the sub-issue limit): ${skipped}`);
+  }
+
+  lines.push('', '## Issues to address', '');
+
+  if (list.length === 0) {
+    lines.push('_No open issues were found._');
+  } else {
+    lines.push(...list.map(formatIssueLine));
+  }
+
+  lines.push('', '## Requirements', '', '1. Read every issue listed above (including its comments) and fully implement what it asks for.', '2. Do all of the work in this single pull request. Do not defer any listed issue to a follow-up pull request.', '3. The pull request description **must** close this issue and **every** issue listed above, so that merging the pull request closes all of them at once.', '4. GitHub requires the full closing syntax for each issue: one keyword per issue. `Fixes #1, #2` only closes `#1`. Use the block below verbatim (plus `Fixes #<this issue>` for this issue).', '5. If an issue turns out to be already resolved or not reproducible, say so explicitly in the pull request description — but still keep its closing reference so it is closed on merge.', '', '## Required closing references in the pull request description', '', '```', buildClosingKeywordBlock(list) || '(no issues)', '```', '');
+
+  return lines.join('\n');
+}
+
+/**
+ * Human-readable summary of what repository mode is about to do, for logs.
+ *
+ * @param {object} params
+ * @returns {string[]}
+ */
+export function buildRepositoryModeSummaryLines({ totalOpen, selectedCount, skipped, limit = MAX_SUB_ISSUES_PER_PARENT }) {
+  const lines = [`   Open issues found:        ${totalOpen}`, `   Attached as sub-issues:   ${selectedCount} (limit ${limit})`];
+  if (skipped > 0) {
+    lines.push(`   Left out (newest, over limit): ${skipped}`);
+  }
+  return lines;
+}
+
+export default {
+  MAX_SUB_ISSUES_PER_PARENT,
+  REPOSITORY_MODE_MARKER,
+  buildOpenIssuesApiArgs,
+  isPullRequestEntry,
+  normalizeOpenIssueEntry,
+  selectOldestOpenIssues,
+  buildCombinedIssueTitle,
+  buildClosingKeywordBlock,
+  buildCombinedIssueBody,
+  buildRepositoryModeSummaryLines,
+};