@oss-scout/core 0.7.1 → 0.9.0

package/dist/core/feature-discovery.js

@@ -0,0 +1,380 @@
+/**
+ * Feature Discovery — orchestrates `scout features` mode: surfaces
+ * feature-scoped contribution opportunities in repos where the user has
+ * 3+ merged PRs, ranked into separate "quick wins" and "bigger bets" buckets.
+ *
+ * Reuses existing infrastructure:
+ * - issue-vetting.ts    — per-issue vetting + scoring (with featureSignals)
+ * - issue-scoring.ts    — viability score (existing weights + feature bonuses)
+ * - http-cache.ts       — response cache
+ * - errors.ts           — auth/rate-limit propagation
+ *
+ * No state singletons — anchor repos are resolved from RepoScore[] passed in.
+ */
+import { errorMessage, getHttpStatusCode, isRateLimitError } from "./errors.js";
+import { warn } from "./logger.js";
+import { sleep } from "./utils.js";
+import { fetchRoadmapIssueRefs } from "./roadmap.js";
+const MODULE = "feature-discovery";
+/** Delay between per-repo issue lists, mirroring search-phases.INTER_QUERY_DELAY_MS. */
+const INTER_REPO_DELAY_MS = 2000;
+/** Minimum viability score for a feature candidate to surface — same as scout search. */
+const MIN_VIABILITY_SCORE = 40;
+/** Default minimum merged-PR count for a repo to qualify as an anchor. */
+export const ANCHOR_THRESHOLD = 3;
+/** Default quick-wins / bigger-bets split ratio (60/40). */
+export const DEFAULT_SPLIT_RATIO = 0.6;
+/**
+ * Resolve anchor repos: those with mergedPRCount >= threshold (default 3),
+ * sorted by mergedPRCount descending. ScoutState stores repoScores as a
+ * Record<string, RepoScore>, so we read its values.
+ *
+ * @param threshold Override minimum merged-PR count (#98).
+ */
+export function resolveAnchorRepos(repoScores, threshold = ANCHOR_THRESHOLD) {
+    return Object.values(repoScores)
+        .filter((rs) => rs.mergedPRCount >= threshold)
+        .sort((a, b) => b.mergedPRCount - a.mergedPRCount)
+        .map((rs) => rs.repo);
+}
+/** Labels that promote an issue to the "bigger-bet" bucket. */
+export const BIGGER_BET_LABELS = new Set([
+    "roadmap",
+    "accepted-rfc",
+    "proposal",
+]);
+/**
+ * Classify an issue into "quick-win" or "bigger-bet" based on
+ * maintainer-commitment signals (milestone presence, label set, ROADMAP.md
+ * membership). Roadmap membership (#95) is treated as an explicit
+ * maintainer commitment and forces the bigger-bet horizon.
+ */
+export function classifyHorizon(input) {
+    if (input.hasMilestone || input.isOnRoadmap)
+        return "bigger-bet";
+    for (const label of input.labels) {
+        if (BIGGER_BET_LABELS.has(label.toLowerCase()))
+            return "bigger-bet";
+    }
+    return "quick-win";
+}
+/**
+ * Split feature candidates into two buckets respecting a configurable
+ * quick-wins / bigger-bets ratio (default 60/40). If either bucket is
+ * short, redirect the deficit to the other bucket. Each bucket is
+ * sorted by viabilityScore descending.
+ *
+ * @param ratio Fraction (0..1) of `count` to allocate to quick wins (#99).
+ */
+export function splitByHorizon(candidates, count, ratio = DEFAULT_SPLIT_RATIO) {
+    const allQuick = candidates
+        .filter((c) => c.horizon === "quick-win")
+        .sort((a, b) => b.viabilityScore - a.viabilityScore);
+    const allBigger = candidates
+        .filter((c) => c.horizon === "bigger-bet")
+        .sort((a, b) => b.viabilityScore - a.viabilityScore);
+    const targetQuick = Math.round(count * ratio);
+    const targetBigger = count - targetQuick;
+    const quickTaken = Math.min(allQuick.length, targetQuick);
+    const biggerTaken = Math.min(allBigger.length, targetBigger);
+    // Redirect deficits.
+    let quickFinal = quickTaken;
+    let biggerFinal = biggerTaken;
+    const quickDeficit = targetQuick - quickTaken;
+    const biggerDeficit = targetBigger - biggerTaken;
+    if (quickDeficit > 0) {
+        biggerFinal = Math.min(allBigger.length, biggerFinal + quickDeficit);
+    }
+    if (biggerDeficit > 0) {
+        quickFinal = Math.min(allQuick.length, quickFinal + biggerDeficit);
+    }
+    return {
+        quickWins: allQuick.slice(0, quickFinal),
+        biggerBets: allBigger.slice(0, biggerFinal),
+    };
+}
+/** Feature labels used to filter issues. Any-of match. */
+export const FEATURE_LABELS = [
+    "enhancement",
+    "feature",
+    "feature-request",
+    "proposal",
+    "roadmap",
+    "accepted-rfc",
+];
+/** Labels excluded from feature-mode results (overlap with `scout` territory). */
+export const FEATURE_EXCLUSION_LABELS = new Set([
+    "good first issue",
+    "bug",
+    "documentation",
+]);
+/**
+ * Labels that signal "the maintainer wants outside contributions". When any
+ * is present, combined with no linked PR and an issue age >= 60 days, the
+ * issue is treated as wontfix-no-contributor (#96).
+ */
+export const WONTFIX_NO_CONTRIBUTOR_LABELS = new Set([
+    "help wanted",
+    "contributions welcome",
+    "up-for-grabs",
+    "bounty",
+    "pinned",
+    "unmaintained",
+]);
+/** Minimum days an issue must be open to qualify as wontfix-no-contributor. */
+export const WONTFIX_MIN_AGE_DAYS = 60;
+/**
+ * Pure detector for the "wontfix because no contributor stepped up" pattern (#96).
+ *
+ * True when:
+ *   - issue carries any of WONTFIX_NO_CONTRIBUTOR_LABELS, AND
+ *   - issue has been open at least `minAgeDays` days (default 60)
+ *
+ * The orchestrator already filters out assigned issues before reaching the
+ * vetter. Linked-PR cases are deliberately not gated here: the existing
+ * -30 viability penalty for `hasExistingPR` already discounts those, and
+ * checking `hasLinkedPR` would require deferring scoring until after vet,
+ * doubling the work for a marginally cleaner signal.
+ */
+export function detectWontfixNoContributor(input) {
+    const matched = input.labels.some((l) => WONTFIX_NO_CONTRIBUTOR_LABELS.has(l.toLowerCase()));
+    if (!matched)
+        return false;
+    const created = new Date(input.createdAt);
+    if (Number.isNaN(created.getTime()))
+        return false;
+    const now = input.now ?? new Date();
+    const ageDays = (now.getTime() - created.getTime()) / (1000 * 60 * 60 * 24);
+    return ageDays >= (input.minAgeDays ?? WONTFIX_MIN_AGE_DAYS);
+}
+export const NO_ANCHORS_MESSAGE = "No anchor repos yet (need 3+ merged PRs in a repo). Try `scout search` to build relationships first.";
+export const NO_RESULTS_MESSAGE = "No open feature opportunities in your anchor repos right now. Check back next week, or try `scout search` for fix-mode work.";
+function extractLabels(item) {
+    if (!Array.isArray(item.labels))
+        return [];
+    return item.labels
+        .map((l) => (typeof l === "string" ? l : l?.name))
+        .filter((s) => typeof s === "string");
+}
+function isFeatureIssue(item) {
+    const labels = extractLabels(item).map((l) => l.toLowerCase());
+    if (labels.length === 0)
+        return false;
+    if (labels.some((l) => FEATURE_EXCLUSION_LABELS.has(l)))
+        return false;
+    return labels.some((l) => FEATURE_LABELS.includes(l));
+}
+/**
+ * Orchestrate `scout features`: anchor resolution → per-repo issue listing
+ * → feature-signal extraction → vetting → horizon classification → bucket split.
+ *
+ * Returns separate "quick wins" and "bigger bets" buckets per the 60/40 target,
+ * with a human-friendly message when no anchors qualify or no candidates pass
+ * the viability threshold.
+ *
+ * Auth (401) and rate-limit errors propagate. Per-repo and per-issue failures
+ * degrade gracefully via `warn`.
+ */
+export async function discoverFeatures(opts) {
+    const anchorRepos = resolveAnchorRepos(opts.repoScores, opts.anchorThreshold);
+    if (anchorRepos.length === 0) {
+        return {
+            quickWins: [],
+            biggerBets: [],
+            anchorRepos: [],
+            message: NO_ANCHORS_MESSAGE,
+        };
+    }
+    const candidates = [];
+    for (let i = 0; i < anchorRepos.length; i++) {
+        if (i > 0)
+            await sleep(INTER_REPO_DELAY_MS);
+        const [owner, repo] = anchorRepos[i].split("/");
+        // Issues list and roadmap fetch run in parallel — roadmap scraping (#95)
+        // adds at most one extra GET per anchor repo and the result is reused
+        // across every issue in this loop iteration.
+        let response;
+        let roadmapRefs;
+        try {
+            const [listResp, refs] = await Promise.all([
+                opts.octokit.issues.listForRepo({
+                    owner,
+                    repo,
+                    state: "open",
+                    sort: "updated",
+                    direction: "desc",
+                    per_page: 20,
+                }),
+                fetchRoadmapIssueRefs(opts.octokit, owner, repo),
+            ]);
+            response = listResp;
+            roadmapRefs = refs;
+        }
+        catch (err) {
+            if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
+                throw err;
+            warn(MODULE, `failed to list issues for ${anchorRepos[i]}: ${errorMessage(err)}`);
+            continue;
+        }
+        const items = response.data.filter((it) => !it.pull_request && !it.assignee && isFeatureIssue(it));
+        for (const item of items) {
+            const labels = extractLabels(item);
+            const hasMilestone = !!item.milestone;
+            const reactions = item.reactions?.total_count ?? 0;
+            const comments = item.comments ?? 0;
+            const wontfixNoContributor = item.created_at
+                ? detectWontfixNoContributor({ labels, createdAt: item.created_at })
+                : false;
+            const onRoadmap = typeof item.number === "number" && roadmapRefs.has(item.number);
+            let candidate;
+            try {
+                candidate = await opts.vetter.vetIssue(item.html_url, {
+                    featureSignals: {
+                        reactions,
+                        comments,
+                        hasMilestone,
+                        wontfixNoContributor,
+                        onRoadmap,
+                    },
+                });
+            }
+            catch (err) {
+                if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
+                    throw err;
+                warn(MODULE, `vet failed for ${item.html_url}: ${errorMessage(err)}`);
+                continue;
+            }
+            const horizon = classifyHorizon({
+                hasMilestone,
+                labels,
+                isOnRoadmap: onRoadmap,
+            });
+            candidates.push({ ...candidate, horizon });
+        }
+    }
+    // Drop low-viability results — same threshold as scout search.
+    const passing = candidates.filter((c) => c.viabilityScore >= MIN_VIABILITY_SCORE);
+    const split = splitByHorizon(passing, opts.count, opts.splitRatio);
+    const total = split.quickWins.length + split.biggerBets.length;
+    return {
+        ...split,
+        anchorRepos,
+        message: total === 0 ? NO_RESULTS_MESSAGE : null,
+    };
+}
+// ── Broad / cross-repo mode (#100) ──────────────────────────────────────
+export const NO_BROAD_RESULTS_MESSAGE = "No open feature opportunities matched your filters. Try widening your language preferences in `scout config`.";
+const DEFAULT_BROAD_MAX_TO_VET = 30;
+/**
+ * Build a GitHub Search query for cross-repo feature discovery.
+ *
+ * Exported separately from `discoverFeaturesBroad` so the query construction
+ * is independently testable without mocking the Search API.
+ */
+export function buildBroadFeatureSearchQuery(opts) {
+    const parts = ["is:issue", "is:open", "no:assignee"];
+    // Feature labels — any-of via parenthesized OR.
+    const labelClause = FEATURE_LABELS.map((l) => `label:"${l}"`).join(" OR ");
+    parts.push(`(${labelClause})`);
+    // Exclude labels that overlap with `scout` territory.
+    for (const excl of FEATURE_EXCLUSION_LABELS) {
+        parts.push(`-label:"${excl}"`);
+    }
+    // Languages — skip the filter when "any" is the only preference, since
+    // GitHub Search has no `language:any` operator.
+    const languages = (opts.languages ?? []).filter((l) => l && l.toLowerCase() !== "any");
+    if (languages.length > 0) {
+        const langClause = languages.map((l) => `language:${l}`).join(" OR ");
+        parts.push(`(${langClause})`);
+    }
+    // User exclusions.
+    for (const repo of opts.excludeRepos ?? []) {
+        parts.push(`-repo:${repo}`);
+    }
+    for (const org of opts.excludeOrgs ?? []) {
+        parts.push(`-user:${org}`);
+    }
+    return parts.join(" ");
+}
+/**
+ * Orchestrate broad / cross-repo feature discovery (#100). Bypasses anchor
+ * resolution; runs a single GitHub Search API query for feature-labeled
+ * open issues across the entire ecosystem, filtered by the user's language
+ * preferences and excluded repos/orgs.
+ *
+ * Designed for first-touch contributors who haven't yet built repo
+ * relationships and so wouldn't qualify under the default `scout features`
+ * anchor-based path.
+ *
+ * Auth (401) and rate-limit errors propagate; per-issue vet failures
+ * degrade gracefully.
+ */
+export async function discoverFeaturesBroad(opts) {
+    const query = buildBroadFeatureSearchQuery({
+        languages: opts.languages,
+        excludeRepos: opts.excludeRepos,
+        excludeOrgs: opts.excludeOrgs,
+    });
+    const maxToVet = opts.maxToVet ?? DEFAULT_BROAD_MAX_TO_VET;
+    let items;
+    try {
+        const response = await opts.octokit.search.issuesAndPullRequests({
+            q: query,
+            sort: "interactions",
+            order: "desc",
+            per_page: maxToVet,
+        });
+        items = response.data.items.filter((it) => !it.pull_request && !it.assignee && isFeatureIssue(it));
+    }
+    catch (err) {
+        if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
+            throw err;
+        warn(MODULE, `broad feature search failed: ${errorMessage(err)}`);
+        return {
+            quickWins: [],
+            biggerBets: [],
+            anchorRepos: [],
+            message: NO_BROAD_RESULTS_MESSAGE,
+        };
+    }
+    const candidates = [];
+    for (const item of items) {
+        const labels = extractLabels(item);
+        const hasMilestone = !!item.milestone;
+        const reactions = item.reactions?.total_count ?? 0;
+        const comments = item.comments ?? 0;
+        const wontfixNoContributor = item.created_at
+            ? detectWontfixNoContributor({ labels, createdAt: item.created_at })
+            : false;
+        let candidate;
+        try {
+            candidate = await opts.vetter.vetIssue(item.html_url, {
+                featureSignals: {
+                    reactions,
+                    comments,
+                    hasMilestone,
+                    wontfixNoContributor,
+                    // Roadmap scraping is per-repo and would require an extra fetch
+                    // per unique repo in the broad result set — deliberately skipped
+                    // here to keep the broad path cheap. Anchor mode keeps the bonus.
+                },
+            });
+        }
+        catch (err) {
+            if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
+                throw err;
+            warn(MODULE, `vet failed for ${item.html_url}: ${errorMessage(err)}`);
+            continue;
+        }
+        const horizon = classifyHorizon({ hasMilestone, labels });
+        candidates.push({ ...candidate, horizon });
+    }
+    const passing = candidates.filter((c) => c.viabilityScore >= MIN_VIABILITY_SCORE);
+    const split = splitByHorizon(passing, opts.count, opts.splitRatio);
+    const total = split.quickWins.length + split.biggerBets.length;
+    return {
+        ...split,
+        anchorRepos: [],
+        message: total === 0 ? NO_BROAD_RESULTS_MESSAGE : null,
+    };
+}

package/dist/core/gist-state-store.d.ts

@@ -50,11 +50,14 @@ export interface GistOctokitLike {
         }>;
     };
 }
+/** Why bootstrap fell back to local-cache mode, when known. */
+export type DegradedReason = "rate_limit" | "network" | "server" | "unknown";
 export interface BootstrapResult {
     gistId: string;
     state: ScoutState;
     created: boolean;
     degraded?: boolean;
+    degradedReason?: DegradedReason;
 }
 export declare class GistStateStore {
     private octokit;

package/dist/core/gist-state-store.js

@@ -9,13 +9,44 @@ import * as path from "path";
 import { ScoutStateSchema } from "./schemas.js";
 import { getDataDir } from "./utils.js";
 import { debug, warn } from "./logger.js";
-import { errorMessage } from "./errors.js";
+import { errorMessage, getHttpStatusCode, isRateLimitError } from "./errors.js";
 const MODULE = "gist-state";
 const GIST_DESCRIPTION = "oss-scout-state";
 const GIST_FILENAME = "state.json";
 const GIST_ID_FILE = "gist-id";
 const CACHE_FILE = "state-cache.json";
 const SEARCH_MAX_PAGES = 5;
+/** Classify an unknown error into a DegradedReason for user-facing messaging. */
+function classifyDegradedReason(err) {
+    if (isRateLimitError(err))
+        return "rate_limit";
+    const status = getHttpStatusCode(err);
+    // GitHub's abuse-detection responses arrive as 403 with "abuse detection"
+    // in the message but no "rate limit" substring — match resolveErrorCode's
+    // logic in errors.ts so we don't misclassify as 'unknown'.
+    if (status === 403 &&
+        errorMessage(err).toLowerCase().includes("abuse detection")) {
+        return "rate_limit";
+    }
+    if (status !== undefined && status >= 500 && status < 600)
+        return "server";
+    if (err && typeof err === "object" && "code" in err) {
+        const code = err.code;
+        if (code === "ECONNREFUSED" ||
+            code === "ENOTFOUND" ||
+            code === "ETIMEDOUT" ||
+            code === "ECONNRESET" ||
+            code === "EAI_AGAIN") {
+            return "network";
+        }
+    }
+    // Node 18+ fetch errors arrive as `Error: fetch failed` with the cause set.
+    if (err instanceof Error &&
+        err.message.toLowerCase().includes("fetch failed")) {
+        return "network";
+    }
+    return "unknown";
+}
 function getGistIdPath() {
     return path.join(getDataDir(), GIST_ID_FILE);
 }
@@ -37,8 +68,13 @@ export class GistStateStore {
             return await this.bootstrapFromApi();
         }
         catch (err) {
+            // 401 means the token is invalid — fail loudly so the user re-auths.
+            // Rate-limit / network / 5xx fall back to local cache so the user can
+            // keep working offline until the issue resolves.
+            if (getHttpStatusCode(err) === 401)
+                throw err;
             warn(MODULE, `API bootstrap failed: ${errorMessage(err)}`);
-            return this.bootstrapFromCache();
+            return this.bootstrapFromCache(classifyDegradedReason(err));
         }
     }
     /**
@@ -66,6 +102,11 @@ export class GistStateStore {
             return true;
         }
         catch (err) {
+            // Both auth and rate-limit propagate per documented strategy.
+            // Local cache write already happened above, so the user's work isn't
+            // lost — but they need clear feedback that the sync failed.
+            if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
+                throw err;
             warn(MODULE, `Failed to push: ${errorMessage(err)}`);
             return false;
         }
@@ -84,6 +125,8 @@ export class GistStateStore {
             return state;
         }
         catch (err) {
+            if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
+                throw err;
             warn(MODULE, `Failed to pull: ${errorMessage(err)}`);
             return null;
         }
@@ -107,7 +150,14 @@ export class GistStateStore {
                 }
             }
             catch (err) {
-                debug(MODULE, `Cached gist ID invalid: ${errorMessage(err)}`);
+                // Only "the cached gist was deleted server-side" (404) justifies
+                // falling through to search. Auth/rate-limit/network must propagate
+                // so the outer bootstrap() catch can apply the documented strategy
+                // — otherwise a 401 here silently creates a brand-new empty gist
+                // for users with stale cached IDs.
+                if (getHttpStatusCode(err) !== 404)
+                    throw err;
+                debug(MODULE, `Cached gist gone (404): ${errorMessage(err)}`);
             }
             debug(MODULE, "Cached gist ID invalid, searching...");
         }
@@ -125,7 +175,7 @@ export class GistStateStore {
             // Gist exists but content failed validation — fall back to cache
             // to avoid overwriting the user's data by creating a new gist.
             warn(MODULE, `Found existing gist ${foundId} but content failed validation. Using local cache to avoid data loss.`);
-            return this.bootstrapFromCache();
+            return this.bootstrapFromCache("unknown");
         }
         // 3. Create new gist
         debug(MODULE, "No existing gist found, creating new one");
@@ -136,7 +186,7 @@ export class GistStateStore {
         this.writeCache(freshState);
         return { gistId: newId, state: freshState, created: true };
     }
-    bootstrapFromCache() {
+    bootstrapFromCache(reason) {
         const cached = this.readCache();
         if (cached) {
             debug(MODULE, "Bootstrapped from local cache (degraded mode)");
@@ -148,11 +198,18 @@ export class GistStateStore {
                 state: cached,
                 created: false,
                 degraded: true,
+                degradedReason: reason,
             };
         }
         debug(MODULE, "No cache available, using fresh state (degraded mode)");
         const fresh = ScoutStateSchema.parse({ version: 1 });
-        return { gistId: "", state: fresh, created: false, degraded: true };
+        return {
+            gistId: "",
+            state: fresh,
+            created: false,
+            degraded: true,
+            degradedReason: reason,
+        };
     }
     // ── Gist API operations ──────────────────────────────────────────────
     async fetchGistState(gistId) {

package/dist/core/issue-discovery.js

@@ -203,6 +203,8 @@ async function runPhase3(octokit, vetter, langQuery, minStars, projectCategories
         };
     }
     catch (error) {
+        if (getHttpStatusCode(error) === 401)
+            throw error;
         const errMsg = errorMessage(error);
         warn(MODULE, `Error in maintained-repo search: ${errMsg}`);
         return {

package/dist/core/issue-eligibility.js

@@ -36,12 +36,17 @@ function buildLinkedPRFromTimelineEvent(e, context) {
         warn(MODULE, `Cross-referenced PR #${issue.number} for ${ctx} missing html_url — skipping linkedPR metadata`);
         return null;
     }
+    // updatedAt is read directly from the timeline event's source.issue
+    // (issue.updated_at is exposed on the cross-reference payload), so no
+    // extra pulls.get round-trip is needed. Left undefined when absent —
+    // isLinkedPRStalled treats missing data as not-stalled.
     return {
         number: issue.number,
         author,
         state: issue.state === "closed" ? "closed" : "open",
         merged: !!issue.pull_request?.merged_at,
         url,
+        updatedAt: issue.updated_at,
     };
 }
 const MODULE = "issue-eligibility";

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

@@ -23,6 +23,22 @@ export interface ViabilityScoreParams {
     repoQualityBonus?: number;
     /** True when the repo matches one of the user's preferred project categories. */
     matchesPreferredCategory?: boolean;
+    /**
+     * Optional feature-mode signals. When present, applies reaction (cap +10),
+     * comment-depth (+5 if >=5), milestone (+5), and wontfixNoContributor
+     * (+10) bonuses. When absent, scoring behavior is unchanged.
+     *
+     * Note: `onRoadmap` is forwarded for cache-key uniqueness but does NOT
+     * contribute to the viability score (#95) — roadmap membership influences
+     * horizon classification only, not score.
+     */
+    featureSignals?: {
+        reactions: number;
+        comments: number;
+        hasMilestone: boolean;
+        onRoadmap?: boolean;
+        wontfixNoContributor?: boolean;
+    };
 }
 /**
  * Calculate viability score for an issue (0-100 scale)

package/dist/core/issue-scoring.js

@@ -92,6 +92,19 @@ export function calculateViabilityScore(params) {
     if (params.closedWithoutMergeCount > 0 && params.mergedPRCount === 0) {
         score -= 15;
     }
+    // Feature signals: reactions, comment depth, milestone, wontfix-no-contributor.
+    // Note: onRoadmap (#95) is intentionally NOT scored — roadmap membership is
+    // surfaced via the horizon classifier instead.
+    if (params.featureSignals) {
+        const fs = params.featureSignals;
+        score += Math.min(Math.floor(fs.reactions / 2), 10);
+        if (fs.comments >= 5)
+            score += 5;
+        if (fs.hasMilestone)
+            score += 5;
+        if (fs.wontfixNoContributor)
+            score += 10;
+    }
     // Clamp to 0-100
     return Math.max(0, Math.min(100, score));
 }

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

@@ -8,6 +8,28 @@
  */
 import { Octokit } from "@octokit/rest";
 import { type SearchPriority, type IssueCandidate, type ProjectCategory } from "./types.js";
+/**
+ * Feature-mode signals supplied by the caller (orchestrator) — the vetter
+ * does NOT extract these from the GitHub issue itself. When passed, they
+ * plumb through to `calculateViabilityScore` to apply reaction, comment-depth,
+ * milestone, roadmap, and wontfix-no-contributor bonuses.
+ */
+export type FeatureSignals = {
+    reactions: number;
+    comments: number;
+    hasMilestone: boolean;
+    /**
+     * Issue is referenced from the repo's ROADMAP.md. Strong maintainer-commitment
+     * signal — they've publicly committed to the work in a roadmap doc (#95).
+     */
+    onRoadmap?: boolean;
+    /**
+     * Issue exhibits "wontfix-no-contributor" pattern — labeled help-wanted /
+     * contributions-welcome / up-for-grabs / bounty, no linked PR, open >= 60
+     * days. Maintainer wants it; nobody has stepped up (#96).
+     */
+    wontfixNoContributor?: boolean;
+};
 /**
  * Read-only interface for accessing scout state during issue vetting.
  * Implementations may be backed by gist persistence, in-memory state, etc.
@@ -40,8 +62,15 @@ export declare class IssueVetter {
     /**
      * Vet a specific issue — runs all checks and computes recommendation + viability score.
      * Results are cached for 15 minutes to avoid redundant API calls on repeated searches.
+     *
+     * `opts.featureSignals` are forwarded directly to scoring; the vetter does
+     * not derive them from the fetched issue. Cache key includes a digest of
+     * the signals so the same URL with different signals doesn't return a
+     * stale score.
      */
-    vetIssue(issueUrl: string): Promise<IssueCandidate>;
+    vetIssue(issueUrl: string, opts?: {
+        featureSignals?: FeatureSignals;
+    }): Promise<IssueCandidate>;
     /**
      * Vet multiple issues in parallel with concurrency limit
      */