@oss-scout/core 0.8.0 → 0.9.1

package/dist/core/roadmap.js

@@ -0,0 +1,131 @@
+/**
+ * Roadmap scraping (#95) — fetches a repo's ROADMAP.md (or variant) and
+ * extracts referenced GitHub issue numbers. Used by feature-discovery to
+ * apply an `onRoadmap` bonus when the maintainer has publicly committed
+ * to an issue in their roadmap doc.
+ *
+ * Cached for 1 hour per repo. 404s are cached as empty sets so repos
+ * without a roadmap don't get re-probed every run.
+ *
+ * Auth (401) and rate-limit errors propagate, matching the rest of the
+ * codebase's error strategy. Other errors degrade gracefully (warn + empty).
+ */
+import { errorMessage, getHttpStatusCode, isRateLimitError } from "./errors.js";
+import { warn } from "./logger.js";
+const MODULE = "roadmap";
+/** TTL for roadmap fetch results (1 hour). */
+const CACHE_TTL_MS = 60 * 60 * 1000;
+/** Paths probed in priority order. First success wins. */
+const ROADMAP_PATHS = [
+    "ROADMAP.md",
+    "docs/ROADMAP.md",
+    ".github/ROADMAP.md",
+    "Roadmap.md",
+    "roadmap.md",
+];
+const roadmapCache = new Map();
+/** Drop expired entries. Called from each fetch. */
+function pruneCache() {
+    const cutoff = Date.now() - CACHE_TTL_MS;
+    for (const [key, value] of roadmapCache.entries()) {
+        if (value.fetchedAt < cutoff)
+            roadmapCache.delete(key);
+    }
+}
+/**
+ * Parse markdown content for issue number references.
+ *
+ * Extracts:
+ *   - bare `#NNN` references that are not on a markdown heading line
+ *   - `<owner>/<repo>#NNN` cross-repo refs that match the repo we're parsing for
+ *   - `https://github.com/<owner>/<repo>/issues/NNN` URLs that match the
+ *     repo we're parsing for (URLs to other repos are ignored)
+ *
+ * The match for cross-repo `owner/repo#N` and full URLs is intentional:
+ * scattered references to unrelated repos in a roadmap shouldn't bump
+ * scores in those repos.
+ */
+export function parseRoadmapIssueRefs(content, owner, repo) {
+    const refs = new Set();
+    const ownerRepoLower = `${owner}/${repo}`.toLowerCase();
+    // `owner/repo#N` cross-repo style refs — must match the current repo.
+    // We escape regex metachars in case repo names contain `.` or `-`.
+    const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const fullRefPattern = new RegExp(`\\b${escape(owner)}/${escape(repo)}#(\\d+)\\b`, "gi");
+    for (const m of content.matchAll(fullRefPattern)) {
+        const n = Number.parseInt(m[1], 10);
+        if (n > 0)
+            refs.add(n);
+    }
+    // Bare `#N` references, scanned line-by-line so we can skip markdown
+    // headings (`# title`, `## section`) — those aren't issue refs. We also
+    // strip out `owner/repo#N` matches first so `#N` in a cross-repo ref to
+    // a different repo doesn't leak in as a bare match.
+    const fullRefStripPattern = /\b[\w.-]+\/[\w.-]+#\d+\b/gi;
+    for (const line of content.split("\n")) {
+        if (/^\s*#+\s/.test(line))
+            continue;
+        const stripped = line.replace(fullRefStripPattern, "");
+        for (const m of stripped.matchAll(/(?:^|[^&\w])#(\d+)\b/g)) {
+            const n = Number.parseInt(m[1], 10);
+            if (n > 0)
+                refs.add(n);
+        }
+    }
+    // Full GitHub issue URLs scoped to this repo.
+    const urlPattern = /https?:\/\/github\.com\/([\w.-]+\/[\w.-]+)\/issues\/(\d+)/gi;
+    for (const m of content.matchAll(urlPattern)) {
+        if (m[1].toLowerCase() === ownerRepoLower) {
+            const n = Number.parseInt(m[2], 10);
+            if (n > 0)
+                refs.add(n);
+        }
+    }
+    return refs;
+}
+/**
+ * Fetch and parse the repo's ROADMAP.md, returning the set of referenced
+ * issue numbers. Returns an empty set if no roadmap is found.
+ *
+ * Probes ROADMAP_PATHS sequentially until a 200 response is received.
+ * Auth/rate-limit errors propagate; other errors are logged and degrade
+ * to an empty set.
+ */
+export async function fetchRoadmapIssueRefs(octokit, owner, repo) {
+    const cacheKey = `${owner}/${repo}`.toLowerCase();
+    const cached = roadmapCache.get(cacheKey);
+    if (cached && Date.now() - cached.fetchedAt < CACHE_TTL_MS) {
+        return cached.refs;
+    }
+    for (const path of ROADMAP_PATHS) {
+        try {
+            const { data } = await octokit.repos.getContent({ owner, repo, path });
+            if (!("content" in data))
+                continue;
+            const content = Buffer.from(data.content, "base64").toString("utf-8");
+            const refs = parseRoadmapIssueRefs(content, owner, repo);
+            roadmapCache.set(cacheKey, { refs, fetchedAt: Date.now() });
+            pruneCache();
+            return refs;
+        }
+        catch (err) {
+            if (getHttpStatusCode(err) === 401 || isRateLimitError(err))
+                throw err;
+            const status = getHttpStatusCode(err);
+            if (status === 404)
+                continue; // path missing — try next
+            warn(MODULE, `Unexpected error fetching ${path} from ${owner}/${repo}: ${errorMessage(err)}`);
+            // Fall through and try next path.
+        }
+    }
+    // No roadmap found (or all probes errored softly). Cache the empty result
+    // so we don't re-probe every run.
+    const empty = new Set();
+    roadmapCache.set(cacheKey, { refs: empty, fetchedAt: Date.now() });
+    pruneCache();
+    return empty;
+}
+/** Test-only: clear the in-memory cache. */
+export function _clearRoadmapCacheForTests() {
+    roadmapCache.clear();
+}

package/dist/core/schemas.d.ts

@@ -94,6 +94,7 @@ export declare const LinkedPRSchema: z.ZodObject<{
     }>;
     merged: z.ZodBoolean;
     url: z.ZodString;
+    updatedAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const IssueVettingResultSchema: z.ZodObject<{
     passedAllChecks: z.ZodBoolean;
@@ -129,6 +130,7 @@ export declare const IssueVettingResultSchema: z.ZodObject<{
         }>;
         merged: z.ZodBoolean;
         url: z.ZodString;
+        updatedAt: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     notes: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
@@ -182,6 +184,7 @@ export declare const TrackedIssueSchema: z.ZodObject<{
             }>;
             merged: z.ZodBoolean;
             url: z.ZodString;
+            updatedAt: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
         notes: z.ZodArray<z.ZodString>;
     }, z.core.$strip>>;
@@ -193,6 +196,10 @@ export declare const SkippedIssueSchema: z.ZodObject<{
     title: z.ZodString;
     skippedAt: z.ZodString;
 }, z.core.$strip>;
+export declare const HorizonSchema: z.ZodEnum<{
+    "quick-win": "quick-win";
+    "bigger-bet": "bigger-bet";
+}>;
 export declare const SavedCandidateSchema: z.ZodObject<{
     issueUrl: z.ZodString;
     repo: z.ZodString;
@@ -209,6 +216,10 @@ export declare const SavedCandidateSchema: z.ZodObject<{
     firstSeenAt: z.ZodString;
     lastSeenAt: z.ZodString;
     lastScore: z.ZodNumber;
+    horizon: z.ZodOptional<z.ZodEnum<{
+        "quick-win": "quick-win";
+        "bigger-bet": "bigger-bet";
+    }>>;
 }, z.core.$strip>;
 export declare const PersistenceModeSchema: z.ZodEnum<{
     local: "local";
@@ -254,6 +265,8 @@ export declare const ScoutPreferencesSchema: z.ZodObject<{
     skipBroadWhenSufficientResults: z.ZodDefault<z.ZodNumber>;
     slmTriageModel: z.ZodDefault<z.ZodString>;
     slmTriageHost: z.ZodDefault<z.ZodString>;
+    featuresAnchorThreshold: z.ZodDefault<z.ZodNumber>;
+    featuresSplitRatio: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>;
 export declare const ScoutStateSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
@@ -297,6 +310,8 @@ export declare const ScoutStateSchema: z.ZodObject<{
         skipBroadWhenSufficientResults: z.ZodDefault<z.ZodNumber>;
         slmTriageModel: z.ZodDefault<z.ZodString>;
         slmTriageHost: z.ZodDefault<z.ZodString>;
+        featuresAnchorThreshold: z.ZodDefault<z.ZodNumber>;
+        featuresSplitRatio: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
     repoScores: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         repo: z.ZodString;
@@ -347,6 +362,10 @@ export declare const ScoutStateSchema: z.ZodObject<{
         firstSeenAt: z.ZodString;
         lastSeenAt: z.ZodString;
         lastScore: z.ZodNumber;
+        horizon: z.ZodOptional<z.ZodEnum<{
+            "quick-win": "quick-win";
+            "bigger-bet": "bigger-bet";
+        }>>;
     }, z.core.$strip>>>;
     skippedIssues: z.ZodDefault<z.ZodArray<z.ZodObject<{
         url: z.ZodString;
@@ -372,6 +391,7 @@ export type LinkedPR = z.infer<typeof LinkedPRSchema>;
 export type IssueVettingResult = z.infer<typeof IssueVettingResultSchema>;
 export type TrackedIssue = z.infer<typeof TrackedIssueSchema>;
 export type ScoutPreferences = z.infer<typeof ScoutPreferencesSchema>;
+export type Horizon = z.infer<typeof HorizonSchema>;
 export type SavedCandidate = z.infer<typeof SavedCandidateSchema>;
 export type SkippedIssue = z.infer<typeof SkippedIssueSchema>;
 export type ScoutState = z.infer<typeof ScoutStateSchema>;

package/dist/core/schemas.js

@@ -95,6 +95,12 @@ export const LinkedPRSchema = z.object({
     state: z.enum(["open", "closed"]),
     merged: z.boolean(),
     url: z.string(),
+    /**
+     * ISO-8601 timestamp of the linked PR's last update. Optional so existing
+     * persisted state validates unchanged. Used by `isLinkedPRStalled` to
+     * surface stale revive opportunities (#97).
+     */
+    updatedAt: z.string().optional(),
 });
 export const IssueVettingResultSchema = z.object({
     passedAllChecks: z.boolean(),
@@ -131,6 +137,7 @@ export const SkippedIssueSchema = z.object({
     skippedAt: z.string(),
 });
 // ── Saved candidate schema ─────────────────────────────────────────
+export const HorizonSchema = z.enum(["quick-win", "bigger-bet"]);
 export const SavedCandidateSchema = z.object({
     issueUrl: z.string(),
     repo: z.string(),
@@ -143,6 +150,7 @@ export const SavedCandidateSchema = z.object({
     firstSeenAt: z.string(),
     lastSeenAt: z.string(),
     lastScore: z.number(),
+    horizon: HorizonSchema.optional(),
 });
 // ── Scout preferences schema ────────────────────────────────────────
 export const PersistenceModeSchema = z.enum(["local", "gist"]);
@@ -177,6 +185,18 @@ export const ScoutPreferencesSchema = z.object({
      * local network.
      */
     slmTriageHost: z.string().default(""),
+    /**
+     * Minimum merged-PR count for a repo to qualify as an anchor in
+     * `scout features` (#98). Lowering surfaces more anchors at the cost
+     * of weaker prior engagement signal.
+     */
+    featuresAnchorThreshold: z.number().int().min(1).max(50).default(3),
+    /**
+     * Quick-wins / bigger-bets split ratio for `scout features` (#99).
+     * 0.6 means 60% quick wins, 40% bigger bets when both pools are
+     * abundant. Deficits redirect to the other bucket.
+     */
+    featuresSplitRatio: z.number().min(0).max(1).default(0.6),
 });
 // ── Root state schema ───────────────────────────────────────────────
 export const ScoutStateSchema = z.object({

package/dist/core/search-phases.d.ts

@@ -61,6 +61,30 @@ export declare function fetchIssuesFromKnownRepos(octokit: Octokit, vetter: Issu
  * @param perPage      Number of results per API call
  */
 export declare function searchWithChunkedLabels(octokit: Octokit, labels: string[], reservedOps: number, buildQuery: (labelQuery: string) => string, perPage: number): Promise<GitHubSearchItem[]>;
+/**
+ * Build per-call language qualifier strings, fanning out across languages
+ * when a multi-language + labels combination would trip GitHub Search's
+ * empty-result edge case (multi-`language:` AND with a label OR-group
+ * silently returns 0 — see https://github.com/costajohnt/oss-autopilot/issues/1331).
+ */
+export declare function buildLanguageVariants(languages: string[], isAnyLanguage: boolean, hasLabels: boolean): string[];
+/**
+ * Search across languages with label chunking, deduplicating results.
+ *
+ * Fans out one query per language when 2+ languages are paired with labels
+ * (works around a GitHub Search backend edge case where the multi-language
+ * AND combined with a label OR-group returns 0). For each language variant,
+ * delegates to searchWithChunkedLabels to keep within GitHub's 5-operator limit.
+ *
+ * @param octokit         Authenticated Octokit instance
+ * @param languages       Configured languages (used as `language:X` qualifiers)
+ * @param isAnyLanguage   When true, skip language qualifiers entirely
+ * @param labels          Label list passed to searchWithChunkedLabels
+ * @param buildBaseQuery  Builds the query prefix from a language qualifier string;
+ *                        e.g. `(langQ) => `is:issue is:open ${langQ} no:assignee`.trim()`
+ * @param perPage         Results per API call
+ */
+export declare function searchAcrossLanguagesAndLabels(octokit: Octokit, languages: string[], isAnyLanguage: boolean, labels: string[], buildBaseQuery: (langQuery: string) => string, perPage: number): Promise<GitHubSearchItem[]>;
 /**
  * Shared pipeline: spam-filter, repo-exclusion, vetting, and star-count filter.
  * Used by Phases 2 and 3 to convert raw search results into vetted candidates.

package/dist/core/search-phases.js

@@ -291,6 +291,56 @@ export async function searchWithChunkedLabels(octokit, labels, reservedOps, buil
     }
     return allItems;
 }
+/**
+ * Build per-call language qualifier strings, fanning out across languages
+ * when a multi-language + labels combination would trip GitHub Search's
+ * empty-result edge case (multi-`language:` AND with a label OR-group
+ * silently returns 0 — see https://github.com/costajohnt/oss-autopilot/issues/1331).
+ */
+export function buildLanguageVariants(languages, isAnyLanguage, hasLabels) {
+    if (isAnyLanguage || languages.length === 0)
+        return [""];
+    if (languages.length === 1)
+        return [`language:${languages[0]}`];
+    if (!hasLabels)
+        return [languages.map((l) => `language:${l}`).join(" ")];
+    return languages.map((l) => `language:${l}`);
+}
+/**
+ * Search across languages with label chunking, deduplicating results.
+ *
+ * Fans out one query per language when 2+ languages are paired with labels
+ * (works around a GitHub Search backend edge case where the multi-language
+ * AND combined with a label OR-group returns 0). For each language variant,
+ * delegates to searchWithChunkedLabels to keep within GitHub's 5-operator limit.
+ *
+ * @param octokit         Authenticated Octokit instance
+ * @param languages       Configured languages (used as `language:X` qualifiers)
+ * @param isAnyLanguage   When true, skip language qualifiers entirely
+ * @param labels          Label list passed to searchWithChunkedLabels
+ * @param buildBaseQuery  Builds the query prefix from a language qualifier string;
+ *                        e.g. `(langQ) => `is:issue is:open ${langQ} no:assignee`.trim()`
+ * @param perPage         Results per API call
+ */
+export async function searchAcrossLanguagesAndLabels(octokit, languages, isAnyLanguage, labels, buildBaseQuery, perPage) {
+    const langVariants = buildLanguageVariants(languages, isAnyLanguage, labels.length > 0);
+    const seenUrls = new Set();
+    const allItems = [];
+    for (let i = 0; i < langVariants.length; i++) {
+        if (i > 0)
+            await sleep(INTER_QUERY_DELAY_MS);
+        const items = await searchWithChunkedLabels(octokit, labels, 0, (labelQ) => `${buildBaseQuery(langVariants[i])} ${labelQ}`
+            .replace(/  +/g, " ")
+            .trim(), perPage);
+        for (const item of items) {
+            if (!seenUrls.has(item.html_url)) {
+                seenUrls.add(item.html_url);
+                allItems.push(item);
+            }
+        }
+    }
+    return allItems;
+}
 /**
  * Shared pipeline: spam-filter, repo-exclusion, vetting, and star-count filter.
  * Used by Phases 2 and 3 to convert raw search results into vetted candidates.

package/dist/index.d.ts

@@ -16,9 +16,12 @@
  */
 export { createScout, OssScout } from "./scout.js";
 export type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, OpenPRRecord, RepoScoreUpdate, ProjectHealth, SearchPriority, CheckResult, AntiLLMPolicyResult, AntiLLMPolicySourceFile, VetListOptions, VetListResult, VetListEntry, VetListSummary, } from "./core/types.js";
-export type { ScoutState, ScoutPreferences, RepoScore, RepoSignals, IssueVettingResult, LinkedPR, ContributionGuidelines, TrackedIssue, IssueScope, ProjectCategory, StoredMergedPR, StoredClosedPR, StoredOpenPR, SearchStrategy, SkippedIssue, } from "./core/schemas.js";
-export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, SkippedIssueSchema, } from "./core/schemas.js";
+export type { ScoutState, ScoutPreferences, RepoScore, RepoSignals, IssueVettingResult, LinkedPR, ContributionGuidelines, TrackedIssue, IssueScope, ProjectCategory, StoredMergedPR, StoredClosedPR, StoredOpenPR, SearchStrategy, SkippedIssue, Horizon, } from "./core/schemas.js";
+export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, SkippedIssueSchema, HorizonSchema, } from "./core/schemas.js";
 export { requireGitHubToken, getGitHubToken } from "./core/utils.js";
 export { IssueDiscovery } from "./core/issue-discovery.js";
-export { IssueVetter, type ScoutStateReader } from "./core/issue-vetting.js";
+export { IssueVetter, type ScoutStateReader, type FeatureSignals, } from "./core/issue-vetting.js";
 export { scanForAntiLLMPolicy, ANTI_LLM_KEYWORDS, } from "./core/anti-llm-policy.js";
+export { discoverFeatures, resolveAnchorRepos, classifyHorizon, splitByHorizon, ANCHOR_THRESHOLD, FEATURE_LABELS, NO_ANCHORS_MESSAGE, NO_RESULTS_MESSAGE, type FeatureCandidate, type FeatureSearchResult, type DiscoverFeaturesOptions, } from "./core/feature-discovery.js";
+export { isLinkedPRStalled, STALLED_PR_THRESHOLD_DAYS, } from "./core/linked-pr.js";
+export { fetchRoadmapIssueRefs, parseRoadmapIssueRefs, } from "./core/roadmap.js";

package/dist/index.js

@@ -17,10 +17,16 @@
 // Main API
 export { createScout, OssScout } from "./scout.js";
 // Schemas (for consumers who need runtime validation)
-export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, SkippedIssueSchema, } from "./core/schemas.js";
+export { ScoutStateSchema, ScoutPreferencesSchema, RepoScoreSchema, IssueScopeSchema, ProjectCategorySchema, SearchStrategySchema, SkippedIssueSchema, HorizonSchema, } from "./core/schemas.js";
 // Utilities
 export { requireGitHubToken, getGitHubToken } from "./core/utils.js";
 // Internal classes (for advanced use)
 export { IssueDiscovery } from "./core/issue-discovery.js";
-export { IssueVetter } from "./core/issue-vetting.js";
+export { IssueVetter, } from "./core/issue-vetting.js";
 export { scanForAntiLLMPolicy, ANTI_LLM_KEYWORDS, } from "./core/anti-llm-policy.js";
+// Feature discovery API
+export { discoverFeatures, resolveAnchorRepos, classifyHorizon, splitByHorizon, ANCHOR_THRESHOLD, FEATURE_LABELS, NO_ANCHORS_MESSAGE, NO_RESULTS_MESSAGE, } from "./core/feature-discovery.js";
+// Linked-PR helpers (#97)
+export { isLinkedPRStalled, STALLED_PR_THRESHOLD_DAYS, } from "./core/linked-pr.js";
+// Roadmap scraping (#95)
+export { fetchRoadmapIssueRefs, parseRoadmapIssueRefs, } from "./core/roadmap.js";

package/dist/scout.d.ts

@@ -5,7 +5,8 @@
  * Implements ScoutStateReader to bridge state with the search engine.
  */
 import type { ScoutStateReader } from "./core/issue-vetting.js";
-import type { ScoutState, ScoutPreferences, RepoScore, SavedCandidate, SkippedIssue } from "./core/schemas.js";
+import { type FeatureSearchResult } from "./core/feature-discovery.js";
+import type { ScoutState, ScoutPreferences, RepoScore, SavedCandidate, SkippedIssue, Horizon } from "./core/schemas.js";
 import type { ScoutConfig, SearchOptions, SearchResult, IssueCandidate, MergedPRRecord, ClosedPRRecord, OpenPRRecord, RepoScoreUpdate, ProjectCategory, VetListOptions, VetListResult } from "./core/types.js";
 import { GistStateStore } from "./core/gist-state-store.js";
 /**
@@ -51,6 +52,26 @@ export declare class OssScout implements ScoutStateReader {
      * Vet a single issue URL for claimability.
      */
     vetIssue(issueUrl: string): Promise<IssueCandidate>;
+    /**
+     * `scout features` — surfaces feature-scoped contribution opportunities
+     * in repos where the user has 3+ merged PRs (configurable via
+     * `featuresAnchorThreshold`), ranked into separate "quick wins" and
+     * "bigger bets" buckets (split via `featuresSplitRatio`).
+     *
+     * Per-call `anchorThreshold` and `splitRatio` overrides take precedence
+     * over the persisted preferences.
+     *
+     * When `broad` is true (#100), bypasses anchor resolution and runs a
+     * cross-repo GitHub Search query for first-touch contributors who
+     * haven't yet built repo relationships. Filters by user language
+     * preferences and excluded repos/orgs.
+     */
+    features(options?: {
+        count?: number;
+        anchorThreshold?: number;
+        splitRatio?: number;
+        broad?: boolean;
+    }): Promise<FeatureSearchResult>;
     /**
      * Re-vet all saved results with bounded concurrency.
      * Classifies each as still_available, claimed, has_pr, closed, or error.
@@ -106,7 +127,9 @@ export declare class OssScout implements ScoutStateReader {
      * If a candidate already exists, updates score/recommendation/lastSeenAt
      * but preserves firstSeenAt.
      */
-    saveResults(candidates: IssueCandidate[]): void;
+    saveResults(candidates: Array<IssueCandidate | (IssueCandidate & {
+        horizon?: Horizon;
+    })>): void;
     /**
      * Get all saved results.
      */

package/dist/scout.js

@@ -5,6 +5,8 @@
  * Implements ScoutStateReader to bridge state with the search engine.
  */
 import { IssueDiscovery } from "./core/issue-discovery.js";
+import { IssueVetter } from "./core/issue-vetting.js";
+import { discoverFeatures, discoverFeaturesBroad, } from "./core/feature-discovery.js";
 import { ScoutStateSchema } from "./core/schemas.js";
 import { GistStateStore, mergeStates } from "./core/gist-state-store.js";
 import { getOctokit } from "./core/github.js";
@@ -164,6 +166,48 @@ export class OssScout {
         const discovery = new IssueDiscovery(this.githubToken, this.state.preferences, this);
         return discovery.vetIssue(issueUrl);
     }
+    /**
+     * `scout features` — surfaces feature-scoped contribution opportunities
+     * in repos where the user has 3+ merged PRs (configurable via
+     * `featuresAnchorThreshold`), ranked into separate "quick wins" and
+     * "bigger bets" buckets (split via `featuresSplitRatio`).
+     *
+     * Per-call `anchorThreshold` and `splitRatio` overrides take precedence
+     * over the persisted preferences.
+     *
+     * When `broad` is true (#100), bypasses anchor resolution and runs a
+     * cross-repo GitHub Search query for first-touch contributors who
+     * haven't yet built repo relationships. Filters by user language
+     * preferences and excluded repos/orgs.
+     */
+    async features(options) {
+        const count = options?.count ?? 10;
+        const octokit = getOctokit(this.githubToken);
+        const vetter = new IssueVetter(octokit, this);
+        const result = options?.broad
+            ? await discoverFeaturesBroad({
+                octokit,
+                vetter,
+                count,
+                languages: this.state.preferences.languages,
+                excludeRepos: this.state.preferences.excludeRepos,
+                excludeOrgs: this.state.preferences.excludeOrgs,
+                splitRatio: options?.splitRatio ?? this.state.preferences.featuresSplitRatio,
+            })
+            : await discoverFeatures({
+                octokit,
+                vetter,
+                repoScores: this.state.repoScores ?? {},
+                count,
+                anchorThreshold: options?.anchorThreshold ??
+                    this.state.preferences.featuresAnchorThreshold,
+                splitRatio: options?.splitRatio ?? this.state.preferences.featuresSplitRatio,
+            });
+        this.saveResults([...result.quickWins, ...result.biggerBets]);
+        this.state.lastSearchAt = new Date().toISOString();
+        this.dirty = true;
+        return result;
+    }
     // ── Batch Vetting ───────────────────────────────────────────────────
     /**
      * Re-vet all saved results with bounded concurrency.
@@ -423,6 +467,7 @@ export class OssScout {
                 firstSeenAt: prev?.firstSeenAt ?? now,
                 lastSeenAt: now,
                 lastScore: c.viabilityScore,
+                horizon: "horizon" in c ? c.horizon : undefined,
             });
         }
         this.state.savedResults = [...existing.values()];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-scout/core",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Personalized GitHub issue finder with multi-strategy search, deep vetting, and viability scoring — CLI, library, MCP server, and Claude Code plugin",
   "type": "module",
   "bin": {