@oss-autopilot/core 0.54.0 → 0.55.0

package/dist/core/daily-logic.js

@@ -52,43 +52,34 @@ export function applyStatusOverrides(prs, state) {
     if (!overrides || Object.keys(overrides).length === 0)
         return prs;
     const stateManager = getStateManager();
-    // Snapshot keys before iteration — clearStatusOverride mutates the same object
-    const overrideUrls = new Set(Object.keys(overrides));
-    let didAutoClear = false;
-    const result = prs.map((pr) => {
-        try {
-            const override = stateManager.getStatusOverride(pr.url, pr.updatedAt);
-            if (!override) {
-                if (overrideUrls.has(pr.url))
-                    didAutoClear = true;
-                return pr;
-            }
-            if (!VALID_OVERRIDE_STATUSES.has(override.status)) {
-                warn('daily-logic', `Invalid override status "${override.status}" for ${pr.url} — ignoring`);
-                return pr;
+    // Wrap in batch: getStatusOverride may auto-clear stale overrides via clearStatusOverride,
+    // which now auto-saves. Batching produces a single disk write for all auto-clears.
+    let result = [];
+    stateManager.batch(() => {
+        result = prs.map((pr) => {
+            try {
+                const override = stateManager.getStatusOverride(pr.url, pr.updatedAt);
+                if (!override) {
+                    return pr;
+                }
+                if (!VALID_OVERRIDE_STATUSES.has(override.status)) {
+                    warn('daily-logic', `Invalid override status "${override.status}" for ${pr.url} — ignoring`);
+                    return pr;
+                }
+                if (override.status === pr.status)
+                    return pr;
+                // Clear the contradictory reason field and set an appropriate default
+                if (override.status === 'waiting_on_maintainer') {
+                    return { ...pr, status: override.status, actionReason: undefined, waitReason: 'pending_review' };
+                }
+                return { ...pr, status: override.status, waitReason: undefined, actionReason: 'needs_response' };
             }
-            if (override.status === pr.status)
+            catch (err) {
+                warn('daily-logic', `Failed to apply status override for ${pr.url}: ${errorMessage(err)}`);
                 return pr;
-            // Clear the contradictory reason field and set an appropriate default
-            if (override.status === 'waiting_on_maintainer') {
-                return { ...pr, status: override.status, actionReason: undefined, waitReason: 'pending_review' };
             }
-            return { ...pr, status: override.status, waitReason: undefined, actionReason: 'needs_response' };
-        }
-        catch (err) {
-            warn('daily-logic', `Failed to apply status override for ${pr.url}: ${errorMessage(err)}`);
-            return pr;
-        }
+        });
     });
-    // Persist any auto-cleared overrides so they don't resurrect on restart
-    if (didAutoClear) {
-        try {
-            stateManager.save();
-        }
-        catch (err) {
-            warn('daily-logic', `Failed to persist auto-cleared overrides — they may reappear on restart: ${errorMessage(err)}`);
-        }
-    }
     return result;
 }
 // ---------------------------------------------------------------------------

package/dist/core/index.d.ts

@@ -4,7 +4,8 @@
  */
 export { StateManager, getStateManager, resetStateManager, type Stats } from './state.js';
 export { PRMonitor, type PRCheckFailure, type FetchPRsResult, computeDisplayLabel, classifyCICheck, classifyFailingChecks, } from './pr-monitor.js';
-export { IssueDiscovery, type IssueCandidate, type SearchPriority, isDocOnlyIssue, applyPerRepoCap, DOC_ONLY_LABELS, } from './issue-discovery.js';
+export { IssueDiscovery } from './issue-discovery.js';
+export { isDocOnlyIssue, applyPerRepoCap, DOC_ONLY_LABELS } from './issue-filtering.js';
 export { IssueConversationMonitor } from './issue-conversation.js';
 export { isBotAuthor, isAcknowledgmentComment } from './comment-utils.js';
 export { getOctokit, checkRateLimit, type RateLimitInfo } from './github.js';

package/dist/core/index.js

@@ -4,7 +4,8 @@
  */
 export { StateManager, getStateManager, resetStateManager } from './state.js';
 export { PRMonitor, computeDisplayLabel, classifyCICheck, classifyFailingChecks, } from './pr-monitor.js';
-export { IssueDiscovery, isDocOnlyIssue, applyPerRepoCap, DOC_ONLY_LABELS, } from './issue-discovery.js';
+export { IssueDiscovery } from './issue-discovery.js';
+export { isDocOnlyIssue, applyPerRepoCap, DOC_ONLY_LABELS } from './issue-filtering.js';
 export { IssueConversationMonitor } from './issue-conversation.js';
 export { isBotAuthor, isAcknowledgmentComment } from './comment-utils.js';
 export { getOctokit, checkRateLimit } from './github.js';

package/dist/core/issue-discovery.d.ts

@@ -1,17 +1,15 @@
 /**
  * Issue Discovery — orchestrates multi-phase issue search across GitHub.
  *
- * Delegates filtering, scoring, and vetting to focused modules (#356):
- * - issue-filtering.ts — spam detection, doc-only filtering, per-repo caps
- * - issue-scoring.ts  — viability scores, repo quality bonuses
- * - issue-vetting.ts  — individual issue checks (PRs, claims, health, guidelines)
+ * Delegates filtering, scoring, vetting, and search infrastructure to focused modules (#356, #621):
+ * - issue-filtering.ts  — spam detection, doc-only filtering, per-repo caps
+ * - issue-scoring.ts   — viability scores, repo quality bonuses
+ * - issue-vetting.ts   — vetting orchestration, recommendation + viability scoring
+ * - issue-eligibility.ts — PR existence, claim detection, requirements analysis
+ * - repo-health.ts     — project health checks, contribution guidelines
+ * - search-phases.ts   — search helpers, caching, batched repo search
  */
 import { type IssueCandidate } from './types.js';
-import { type ViabilityScoreParams } from './issue-scoring.js';
-export { isDocOnlyIssue, applyPerRepoCap, isLabelFarming, hasTemplatedTitle, detectLabelFarmingRepos, DOC_ONLY_LABELS, BEGINNER_LABELS, type GitHubSearchItem, } from './issue-filtering.js';
-export { calculateRepoQualityBonus, calculateViabilityScore, type ViabilityScoreParams } from './issue-scoring.js';
-export { type CheckResult } from './issue-vetting.js';
-export type { SearchPriority, IssueCandidate } from './types.js';
 export declare class IssueDiscovery {
     private octokit;
     private stateManager;
@@ -20,12 +18,6 @@ export declare class IssueDiscovery {
     /** Set after searchIssues() runs if rate limits affected the search (low pre-flight quota or mid-search rate limit hits). */
     rateLimitWarning: string | null;
     constructor(githubToken: string);
-    /**
-     * Wrap octokit.search.issuesAndPullRequests with time-based caching.
-     * Repeated identical queries within SEARCH_CACHE_TTL_MS return cached results
-     * without consuming GitHub API rate limit points.
-     */
-    private cachedSearch;
     /**
      * Fetch the authenticated user's starred repositories from GitHub.
      * Updates the state manager with the list and timestamp.
@@ -35,11 +27,6 @@ export declare class IssueDiscovery {
      * Get starred repos, fetching from GitHub if cache is stale
      */
     getStarredReposWithRefresh(): Promise<string[]>;
-    /**
-     * Shared pipeline for Phases 2 and 3: spam-filter, repo-exclusion, vetting, and star-count filter.
-     * Extracts the common logic so each phase only needs to supply search results and context.
-     */
-    private filterVetAndScore;
     /**
      * Search for issues matching our criteria.
      * Searches in priority order: merged-PR repos first (no label filter), then starred repos,
@@ -51,34 +38,10 @@ export declare class IssueDiscovery {
         labels?: string[];
         maxResults?: number;
     }): Promise<IssueCandidate[]>;
-    /**
-     * Search for issues within specific repos using batched queries.
-     *
-     * To avoid GitHub's secondary rate limit (30 requests/minute), we batch
-     * multiple repos into a single search query using OR syntax:
-     *   repo:owner1/repo1 OR repo:owner2/repo2 OR repo:owner3/repo3
-     *
-     * This reduces API calls from N (one per repo) to ceil(N/BATCH_SIZE).
-     */
-    private searchInRepos;
-    /**
-     * Split repos into batches of the specified size.
-     */
-    private batchRepos;
     /**
      * Vet a specific issue (delegates to IssueVetter).
      */
     vetIssue(issueUrl: string): Promise<IssueCandidate>;
-    /**
-     * Analyze issue requirements for clarity (delegates to IssueVetter).
-     * Kept on class for backward compatibility.
-     */
-    analyzeRequirements(body: string): boolean;
-    /**
-     * Calculate viability score for an issue (delegates to issue-scoring module).
-     * Kept on class for backward compatibility with tests that call instance.calculateViabilityScore().
-     */
-    calculateViabilityScore(params: ViabilityScoreParams): number;
     /**
      * Save search results to ~/.oss-autopilot/found-issues.md
      * Results are sorted by viability score (highest first)

package/dist/core/issue-discovery.js

@@ -1,31 +1,27 @@
 /**
  * Issue Discovery — orchestrates multi-phase issue search across GitHub.
  *
- * Delegates filtering, scoring, and vetting to focused modules (#356):
- * - issue-filtering.ts — spam detection, doc-only filtering, per-repo caps
- * - issue-scoring.ts  — viability scores, repo quality bonuses
- * - issue-vetting.ts  — individual issue checks (PRs, claims, health, guidelines)
+ * Delegates filtering, scoring, vetting, and search infrastructure to focused modules (#356, #621):
+ * - issue-filtering.ts  — spam detection, doc-only filtering, per-repo caps
+ * - issue-scoring.ts   — viability scores, repo quality bonuses
+ * - issue-vetting.ts   — vetting orchestration, recommendation + viability scoring
+ * - issue-eligibility.ts — PR existence, claim detection, requirements analysis
+ * - repo-health.ts     — project health checks, contribution guidelines
+ * - search-phases.ts   — search helpers, caching, batched repo search
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import { getOctokit, checkRateLimit } from './github.js';
 import { getStateManager } from './state.js';
 import { daysBetween, getDataDir } from './utils.js';
-import { DEFAULT_CONFIG } from './types.js';
+import { DEFAULT_CONFIG, SCOPE_LABELS } from './types.js';
 import { ValidationError, errorMessage, getHttpStatusCode, isRateLimitError } from './errors.js';
 import { debug, info, warn } from './logger.js';
-import { getHttpCache, cachedTimeBased } from './http-cache.js';
-import { isDocOnlyIssue, detectLabelFarmingRepos, applyPerRepoCap } from './issue-filtering.js';
+import { isDocOnlyIssue, applyPerRepoCap } from './issue-filtering.js';
 import { IssueVetter } from './issue-vetting.js';
-import { calculateViabilityScore as calcViabilityScore } from './issue-scoring.js';
 import { getTopicsForCategories } from './category-mapping.js';
-// Re-export everything from sub-modules for backward compatibility.
-// Existing consumers (tests, CLI commands) import from './issue-discovery.js'.
-export { isDocOnlyIssue, applyPerRepoCap, isLabelFarming, hasTemplatedTitle, detectLabelFarmingRepos, DOC_ONLY_LABELS, BEGINNER_LABELS, } from './issue-filtering.js';
-export { calculateRepoQualityBonus, calculateViabilityScore } from './issue-scoring.js';
+import { buildLabelQuery, buildEffectiveLabels, interleaveArrays, cachedSearchIssues, filterVetAndScore, searchInRepos, } from './search-phases.js';
 const MODULE = 'issue-discovery';
-/** TTL for cached search API results (15 minutes). */
-const SEARCH_CACHE_TTL_MS = 15 * 60 * 1000;
 export class IssueDiscovery {
     octokit;
     stateManager;
@@ -39,18 +35,6 @@ export class IssueDiscovery {
         this.stateManager = getStateManager();
         this.vetter = new IssueVetter(this.octokit, this.stateManager);
     }
-    /**
-     * Wrap octokit.search.issuesAndPullRequests with time-based caching.
-     * Repeated identical queries within SEARCH_CACHE_TTL_MS return cached results
-     * without consuming GitHub API rate limit points.
-     */
-    async cachedSearch(params) {
-        const cacheKey = `search:${params.q}:${params.sort}:${params.order}:${params.per_page}`;
-        return cachedTimeBased(getHttpCache(), cacheKey, SEARCH_CACHE_TTL_MS, async () => {
-            const { data } = await this.octokit.search.issuesAndPullRequests(params);
-            return data;
-        });
-    }
     /**
      * Fetch the authenticated user's starred repositories from GitHub.
      * Updates the state manager with the list and timestamp.
@@ -117,41 +101,6 @@ export class IssueDiscovery {
         }
         return this.stateManager.getStarredRepos();
     }
-    /**
-     * Shared pipeline for Phases 2 and 3: spam-filter, repo-exclusion, vetting, and star-count filter.
-     * Extracts the common logic so each phase only needs to supply search results and context.
-     */
-    async filterVetAndScore(items, filterIssues, excludedRepoSets, remainingNeeded, minStars, phaseLabel) {
-        const spamRepos = detectLabelFarmingRepos(items);
-        if (spamRepos.size > 0) {
-            const spamCount = items.filter((i) => spamRepos.has(i.repository_url.split('/').slice(-2).join('/'))).length;
-            debug(MODULE, `[SPAM_FILTER] Filtered ${spamCount} issues from ${spamRepos.size} label-farming repos: ${[...spamRepos].join(', ')}`);
-        }
-        const itemsToVet = filterIssues(items)
-            .filter((item) => {
-            const repoFullName = item.repository_url.split('/').slice(-2).join('/');
-            if (spamRepos.has(repoFullName))
-                return false;
-            return excludedRepoSets.every((s) => !s.has(repoFullName));
-        })
-            .slice(0, remainingNeeded * 2);
-        if (itemsToVet.length === 0) {
-            debug(MODULE, `[${phaseLabel}] All ${items.length} items filtered before vetting`);
-            return { candidates: [], allVetFailed: false, rateLimitHit: false };
-        }
-        const { candidates: results, allFailed: allVetFailed, rateLimitHit, } = await this.vetter.vetIssuesParallel(itemsToVet.map((i) => i.html_url), remainingNeeded, 'normal');
-        const starFiltered = results.filter((c) => {
-            if (c.projectHealth.checkFailed)
-                return true;
-            const stars = c.projectHealth.stargazersCount ?? 0;
-            return stars >= minStars;
-        });
-        const starFilteredCount = results.length - starFiltered.length;
-        if (starFilteredCount > 0) {
-            debug(MODULE, `[STAR_FILTER] Filtered ${starFilteredCount} ${phaseLabel} candidates below ${minStars} stars`);
-        }
-        return { candidates: starFiltered, allVetFailed, rateLimitHit };
-    }
     /**
      * Search for issues matching our criteria.
      * Searches in priority order: merged-PR repos first (no label filter), then starred repos,
@@ -161,7 +110,8 @@ export class IssueDiscovery {
     async searchIssues(options = {}) {
         const config = this.stateManager.getState().config;
         const languages = options.languages || config.languages;
-        const labels = options.labels || config.labels;
+        const scopes = config.scope; // undefined = legacy mode
+        const labels = options.labels || (scopes ? buildEffectiveLabels(scopes, config.labels) : config.labels);
         const maxResults = options.maxResults || 10;
         const minStars = config.minStars ?? 50;
         const allCandidates = [];
@@ -202,7 +152,7 @@ export class IssueDiscovery {
         const maxAgeDays = config.maxIssueAgeDays || 90;
         const now = new Date();
         // Build query parts
-        const labelQuery = labels.map((l) => `label:"${l}"`).join(' ');
+        const labelQuery = buildLabelQuery(labels);
         // When languages includes 'any', omit the language filter entirely
         const isAnyLanguage = languages.some((l) => l.toLowerCase() === 'any');
         const langQuery = isAnyLanguage ? '' : languages.map((l) => `language:${l}`).join(' ');
@@ -241,8 +191,6 @@ export class IssueDiscovery {
             });
         };
         // Phase 0: Search repos where user has merged PRs + open-PR repos (highest merge probability)
-        // Uses broader query — established contributors don't need "good first issue" labels
-        // Merged-PR repos come first, then open-PR repos fill remaining slots (capped at 10 total)
         const phase0Repos = [...mergedPRRepos, ...openPRRepos.filter((r) => !mergedPRRepoSet.has(r))].slice(0, 10);
         const phase0RepoSet = new Set(phase0Repos);
         if (phase0Repos.length > 0) {
@@ -254,7 +202,7 @@ export class IssueDiscovery {
             if (mergedPhase0Repos.length > 0) {
                 const remainingNeeded = maxResults - allCandidates.length;
                 if (remainingNeeded > 0) {
-                    const { candidates: mergedCandidates, allBatchesFailed, rateLimitHit, } = await this.searchInRepos(mergedPhase0Repos, establishedQuery, remainingNeeded, 'merged_pr', filterIssues);
+                    const { candidates: mergedCandidates, allBatchesFailed, rateLimitHit, } = await searchInRepos(this.octokit, this.vetter, mergedPhase0Repos, establishedQuery, remainingNeeded, 'merged_pr', filterIssues);
                     allCandidates.push(...mergedCandidates);
                     if (allBatchesFailed) {
                         phase0Error = 'All merged-PR repo batches failed';
@@ -270,7 +218,7 @@ export class IssueDiscovery {
             if (openPhase0Repos.length > 0 && allCandidates.length < maxResults) {
                 const remainingNeeded = maxResults - allCandidates.length;
                 if (remainingNeeded > 0) {
-                    const { candidates: openCandidates, allBatchesFailed, rateLimitHit, } = await this.searchInRepos(openPhase0Repos, establishedQuery, remainingNeeded, 'starred', filterIssues);
+                    const { candidates: openCandidates, allBatchesFailed, rateLimitHit, } = await searchInRepos(this.octokit, this.vetter, openPhase0Repos, establishedQuery, remainingNeeded, 'starred', filterIssues);
                     allCandidates.push(...openCandidates);
                     if (allBatchesFailed) {
                         const msg = 'All open-PR repo batches failed';
@@ -296,7 +244,7 @@ export class IssueDiscovery {
                 const orgRepoFilter = orgsToSearch.map((org) => `org:${org}`).join(' OR ');
                 const orgQuery = `${baseQuery} (${orgRepoFilter})`;
                 try {
-                    const data = await this.cachedSearch({
+                    const data = await cachedSearchIssues(this.octokit, {
                         q: orgQuery,
                         sort: 'created',
                         order: 'desc',
@@ -335,7 +283,7 @@ export class IssueDiscovery {
                 info(MODULE, `Phase 1: Searching issues in ${reposToSearch.length} starred repos...`);
                 const remainingNeeded = maxResults - allCandidates.length;
                 if (remainingNeeded > 0) {
-                    const { candidates: starredCandidates, allBatchesFailed, rateLimitHit, } = await this.searchInRepos(reposToSearch.slice(0, 10), baseQuery, remainingNeeded, 'starred', filterIssues);
+                    const { candidates: starredCandidates, allBatchesFailed, rateLimitHit, } = await searchInRepos(this.octokit, this.vetter, reposToSearch.slice(0, 10), baseQuery, remainingNeeded, 'starred', filterIssues);
                     allCandidates.push(...starredCandidates);
                     if (allBatchesFailed) {
                         phase1Error = 'All starred repo batches failed';
@@ -348,42 +296,81 @@ export class IssueDiscovery {
             }
         }
         // Phase 2: General search (if still need more)
+        // When multiple scope tiers are active, fire one query per tier and interleave
+        // results to prevent high-volume tiers (e.g., "enhancement") from drowning out
+        // beginner results.
         let phase2Error = null;
         if (allCandidates.length < maxResults) {
             info(MODULE, 'Phase 2: General issue search...');
             const remainingNeeded = maxResults - allCandidates.length;
-            try {
-                const data = await this.cachedSearch({
-                    q: baseQuery,
-                    sort: 'created',
-                    order: 'desc',
-                    per_page: remainingNeeded * 3, // Fetch extra since some will be filtered
-                });
-                info(MODULE, `Found ${data.total_count} issues in general search, processing top ${data.items.length}...`);
-                const seenRepos = new Set(allCandidates.map((c) => c.issue.repo));
-                const { candidates: starFiltered, allVetFailed, rateLimitHit: vetRateLimitHit, } = await this.filterVetAndScore(data.items, filterIssues, [phase0RepoSet, starredRepoSet, seenRepos], remainingNeeded, minStars, 'Phase 2');
-                allCandidates.push(...starFiltered);
-                if (allVetFailed) {
-                    phase2Error = (phase2Error ? phase2Error + '; ' : '') + 'all vetting failed';
+            const seenRepos = new Set(allCandidates.map((c) => c.issue.repo));
+            // Build per-tier label groups. Multi-tier when 2+ scopes; single-tier otherwise.
+            const tierLabelGroups = [];
+            if (scopes && scopes.length > 1) {
+                for (const scope of scopes) {
+                    const scopeLabels = SCOPE_LABELS[scope] ?? [];
+                    if (scopeLabels.length === 0) {
+                        warn(MODULE, `Scope "${scope}" has no labels, skipping tier`);
+                        continue;
+                    }
+                    tierLabelGroups.push({ tier: scope, tierLabels: scopeLabels });
                 }
-                if (vetRateLimitHit) {
-                    rateLimitHitDuringSearch = true;
+                // Custom labels not in any tier get their own pseudo-tier
+                const allScopeLabels = new Set(scopes.flatMap((s) => SCOPE_LABELS[s] ?? []));
+                const customOnly = config.labels.filter((l) => !allScopeLabels.has(l));
+                if (customOnly.length > 0) {
+                    tierLabelGroups.push({ tier: 'custom', tierLabels: customOnly });
                 }
-                info(MODULE, `Found ${starFiltered.length} candidates from general search`);
             }
-            catch (error) {
-                const errMsg = errorMessage(error);
-                phase2Error = errMsg;
-                if (isRateLimitError(error)) {
-                    rateLimitHitDuringSearch = true;
+            else {
+                tierLabelGroups.push({ tier: 'general', tierLabels: labels });
+            }
+            const budgetPerTier = Math.ceil(remainingNeeded / tierLabelGroups.length);
+            const tierResults = [];
+            for (const { tier, tierLabels } of tierLabelGroups) {
+                const tierQuery = `is:issue is:open ${buildLabelQuery(tierLabels)} ${langQuery} no:assignee`
+                    .replace(/  +/g, ' ')
+                    .trim();
+                try {
+                    const data = await cachedSearchIssues(this.octokit, {
+                        q: tierQuery,
+                        sort: 'created',
+                        order: 'desc',
+                        per_page: budgetPerTier * 3,
+                    });
+                    info(MODULE, `Phase 2 [${tier}]: ${data.total_count} total, processing top ${data.items.length}...`);
+                    const { candidates: tierCandidates, allVetFailed, rateLimitHit: vetRateLimitHit, } = await filterVetAndScore(this.vetter, data.items, filterIssues, [phase0RepoSet, starredRepoSet, seenRepos], budgetPerTier, minStars, `Phase 2 [${tier}]`);
+                    tierResults.push(tierCandidates);
+                    // Update seenRepos so later tiers don't return duplicate repos
+                    for (const c of tierCandidates)
+                        seenRepos.add(c.issue.repo);
+                    if (allVetFailed) {
+                        phase2Error = (phase2Error ? phase2Error + '; ' : '') + `${tier}: all vetting failed`;
+                    }
+                    if (vetRateLimitHit) {
+                        rateLimitHitDuringSearch = true;
+                    }
+                    info(MODULE, `Found ${tierCandidates.length} candidates from ${tier} tier`);
+                }
+                catch (error) {
+                    if (getHttpStatusCode(error) === 401)
+                        throw error;
+                    const errMsg = errorMessage(error);
+                    phase2Error = (phase2Error ? phase2Error + '; ' : '') + `${tier}: ${errMsg}`;
+                    if (isRateLimitError(error)) {
+                        rateLimitHitDuringSearch = true;
+                    }
+                    warn(MODULE, `Error in ${tier} tier search: ${errMsg}`);
+                    tierResults.push([]);
                 }
-                warn(MODULE, `Error in general issue search: ${errMsg}`);
             }
+            const interleaved = interleaveArrays(tierResults);
+            if (interleaved.length === 0 && phase2Error) {
+                warn(MODULE, `All ${tierLabelGroups.length} scope tiers failed in Phase 2: ${phase2Error}`);
+            }
+            allCandidates.push(...interleaved.slice(0, remainingNeeded));
         }
         // Phase 3: Actively maintained repos (#349)
-        // Searches the "long tail" of well-maintained repos (50+ stars, recently pushed,
-        // not archived) that Phase 2 may miss because they aren't trending or pre-filtered.
-        // Uses label-free query to cast a wider net focused on repo health.
         let phase3Error = null;
         if (allCandidates.length < maxResults) {
             info(MODULE, 'Phase 3: Searching actively maintained repos...');
@@ -391,16 +378,13 @@ export class IssueDiscovery {
             const thirtyDaysAgo = new Date();
             thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
             const pushedSince = thirtyDaysAgo.toISOString().split('T')[0];
-            // When user has category preferences, add a single topic filter to focus on relevant repos.
-            // GitHub Search API AND-joins multiple topic: qualifiers, which is overly restrictive,
-            // so we pick just the first topic to nudge results without eliminating valid matches.
             const categoryTopics = getTopicsForCategories(config.projectCategories ?? []);
             const topicQuery = categoryTopics.length > 0 ? `topic:${categoryTopics[0]}` : '';
             const phase3Query = `is:issue is:open no:assignee ${langQuery} ${topicQuery} stars:>=${minStars} pushed:>=${pushedSince} archived:false`
                 .replace(/  +/g, ' ')
                 .trim();
             try {
-                const data = await this.cachedSearch({
+                const data = await cachedSearchIssues(this.octokit, {
                     q: phase3Query,
                     sort: 'updated',
                     order: 'desc',
@@ -408,7 +392,7 @@ export class IssueDiscovery {
                 });
                 info(MODULE, `Found ${data.total_count} issues in maintained-repo search, processing top ${data.items.length}...`);
                 const seenRepos = new Set(allCandidates.map((c) => c.issue.repo));
-                const { candidates: starFiltered, allVetFailed, rateLimitHit: vetRateLimitHit, } = await this.filterVetAndScore(data.items, filterIssues, [phase0RepoSet, starredRepoSet, seenRepos], remainingNeeded, minStars, 'Phase 3');
+                const { candidates: starFiltered, allVetFailed, rateLimitHit: vetRateLimitHit, } = await filterVetAndScore(this.vetter, data.items, filterIssues, [phase0RepoSet, starredRepoSet, seenRepos], remainingNeeded, minStars, 'Phase 3');
                 allCandidates.push(...starFiltered);
                 if (allVetFailed) {
                     phase3Error = 'all vetting failed';
@@ -436,8 +420,6 @@ export class IssueDiscovery {
                 phase3Error ? `Phase 3 (maintained repos): ${phase3Error}` : null,
             ].filter(Boolean);
             const details = phaseErrors.length > 0 ? ` ${phaseErrors.join('. ')}.` : '';
-            // When rate limits caused zero results, return empty array with warning
-            // instead of throwing, so callers can handle it gracefully
             if (rateLimitHitDuringSearch) {
                 this.rateLimitWarning =
                     `Search returned no results due to GitHub API rate limits.${details} ` +
@@ -448,8 +430,6 @@ export class IssueDiscovery {
                 'Try adjusting your search criteria (languages, labels) or check your network connection.');
         }
         // Surface rate limit warning even with partial results (#100)
-        // This overwrites the pre-flight "quota low" warning (speculative) with a more
-        // informative "results incomplete" warning (factual) when rate limits actually hit.
         if (rateLimitHitDuringSearch) {
             this.rateLimitWarning =
                 `Search results may be incomplete: GitHub API rate limits were hit during search. ` +
@@ -458,109 +438,26 @@ export class IssueDiscovery {
         }
         // Sort by priority first, then by recommendation, then by viability score
         allCandidates.sort((a, b) => {
-            // Priority order: merged_pr > preferred_org > starred > normal
             const priorityOrder = { merged_pr: 0, preferred_org: 1, starred: 2, normal: 3 };
             const priorityDiff = priorityOrder[a.searchPriority] - priorityOrder[b.searchPriority];
             if (priorityDiff !== 0)
                 return priorityDiff;
-            // Then by recommendation
             const recommendationOrder = { approve: 0, needs_review: 1, skip: 2 };
             const recDiff = recommendationOrder[a.recommendation] - recommendationOrder[b.recommendation];
             if (recDiff !== 0)
                 return recDiff;
-            // Then by viability score (highest first)
             return b.viabilityScore - a.viabilityScore;
         });
         // Apply per-repo cap: max 2 issues from any single repo (#105)
         const capped = applyPerRepoCap(allCandidates, 2);
         return capped.slice(0, maxResults);
     }
-    /**
-     * Search for issues within specific repos using batched queries.
-     *
-     * To avoid GitHub's secondary rate limit (30 requests/minute), we batch
-     * multiple repos into a single search query using OR syntax:
-     *   repo:owner1/repo1 OR repo:owner2/repo2 OR repo:owner3/repo3
-     *
-     * This reduces API calls from N (one per repo) to ceil(N/BATCH_SIZE).
-     */
-    async searchInRepos(repos, baseQuery, maxResults, priority, filterFn) {
-        const candidates = [];
-        // Batch repos to reduce API calls.
-        // GitHub search query has a max length (~256 chars for query part).
-        // Each "repo:owner/repo" is ~20-40 chars, plus " OR " (4 chars).
-        // Using 5 repos per batch stays well under the limit.
-        const BATCH_SIZE = 5;
-        const batches = this.batchRepos(repos, BATCH_SIZE);
-        let failedBatches = 0;
-        let rateLimitFailures = 0;
-        for (const batch of batches) {
-            if (candidates.length >= maxResults)
-                break;
-            try {
-                // Build repo filter: (repo:a OR repo:b OR repo:c)
-                const repoFilter = batch.map((r) => `repo:${r}`).join(' OR ');
-                const batchQuery = `${baseQuery} (${repoFilter})`;
-                const data = await this.cachedSearch({
-                    q: batchQuery,
-                    sort: 'created',
-                    order: 'desc',
-                    per_page: Math.min(30, (maxResults - candidates.length) * 3),
-                });
-                if (data.items.length > 0) {
-                    const filtered = filterFn(data.items);
-                    const remainingNeeded = maxResults - candidates.length;
-                    const { candidates: vetted } = await this.vetter.vetIssuesParallel(filtered.slice(0, remainingNeeded * 2).map((i) => i.html_url), remainingNeeded, priority);
-                    candidates.push(...vetted);
-                }
-            }
-            catch (error) {
-                failedBatches++;
-                if (isRateLimitError(error)) {
-                    rateLimitFailures++;
-                }
-                const batchRepos = batch.join(', ');
-                warn(MODULE, `Error searching issues in batch [${batchRepos}]:`, errorMessage(error));
-            }
-        }
-        const allBatchesFailed = failedBatches === batches.length && batches.length > 0;
-        const rateLimitHit = rateLimitFailures > 0;
-        if (allBatchesFailed) {
-            warn(MODULE, `All ${batches.length} batch(es) failed for ${priority} phase. ` +
-                `This may indicate a systemic issue (rate limit, auth, network).`);
-        }
-        return { candidates, allBatchesFailed, rateLimitHit };
-    }
-    /**
-     * Split repos into batches of the specified size.
-     */
-    batchRepos(repos, batchSize) {
-        const batches = [];
-        for (let i = 0; i < repos.length; i += batchSize) {
-            batches.push(repos.slice(i, i + batchSize));
-        }
-        return batches;
-    }
     /**
      * Vet a specific issue (delegates to IssueVetter).
      */
     async vetIssue(issueUrl) {
         return this.vetter.vetIssue(issueUrl);
     }
-    /**
-     * Analyze issue requirements for clarity (delegates to IssueVetter).
-     * Kept on class for backward compatibility.
-     */
-    analyzeRequirements(body) {
-        return this.vetter.analyzeRequirements(body);
-    }
-    /**
-     * Calculate viability score for an issue (delegates to issue-scoring module).
-     * Kept on class for backward compatibility with tests that call instance.calculateViabilityScore().
-     */
-    calculateViabilityScore(params) {
-        return calcViabilityScore(params);
-    }
     /**
      * Save search results to ~/.oss-autopilot/found-issues.md
      * Results are sorted by viability score (highest first)
@@ -570,8 +467,6 @@ export class IssueDiscovery {
         const sorted = [...candidates].sort((a, b) => b.viabilityScore - a.viabilityScore);
         const outputDir = getDataDir();
         const outputFile = path.join(outputDir, 'found-issues.md');
-        // Directory is created by getDataDir() if needed
-        // Generate markdown content
         const timestamp = new Date().toISOString();
         let content = `# Found Issues\n\n`;
         content += `> Generated at: ${timestamp}\n\n`;

package/dist/core/issue-eligibility.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Issue Eligibility — checks whether an individual issue is claimable:
+ * existing PR detection, claim-phrase scanning, user merge history,
+ * and requirement clarity analysis.
+ *
+ * Extracted from issue-vetting.ts (#621) to isolate eligibility logic.
+ */
+import { Octokit } from '@octokit/rest';
+/** Result of a vetting check that may be inconclusive due to API errors. */
+export interface CheckResult {
+    passed: boolean;
+    inconclusive?: boolean;
+    reason?: string;
+}
+/**
+ * Check whether an open PR already exists for the given issue.
+ * Searches both the PR search index and the issue timeline for linked PRs.
+ */
+export declare function checkNoExistingPR(octokit: Octokit, owner: string, repo: string, issueNumber: number): Promise<CheckResult>;
+/**
+ * Check how many merged PRs the authenticated user has in a repo.
+ * Uses GitHub Search API. Returns 0 on error (non-fatal).
+ */
+export declare function checkUserMergedPRsInRepo(octokit: Octokit, owner: string, repo: string): Promise<number>;
+/**
+ * Check whether an issue has been claimed by another contributor
+ * by scanning recent comments for claim phrases.
+ */
+export declare function checkNotClaimed(octokit: Octokit, owner: string, repo: string, issueNumber: number, commentCount: number): Promise<CheckResult>;
+/**
+ * Analyze whether an issue body has clear, actionable requirements.
+ * Returns true when at least two "clarity indicators" are present:
+ * numbered/bulleted steps, code blocks, expected-behavior keywords, length > 200.
+ */
+export declare function analyzeRequirements(body: string): boolean;