@oss-autopilot/core 3.6.0 → 3.7.0

package/dist/core/linked-pr-classification.d.ts

@@ -23,7 +23,35 @@ export interface LinkedPR {
         login: string;
     } | null;
     state: LinkedPRState;
+    /**
+     * ISO timestamp of the linked PR's last update, surfaced from scout's
+     * timeline-event metadata when available (#97). Optional so existing
+     * callers and fixtures that don't carry the field continue to type-check.
+     * Used by `isLinkedPRStalled` to flag open PRs that haven't been touched
+     * in the last `STALLED_PR_THRESHOLD_DAYS` days.
+     */
+    updatedAt?: string;
 }
+/**
+ * Days of inactivity that classify an open linked PR as "stalled" — kept
+ * in sync with scout's `STALLED_PR_THRESHOLD_DAYS` so the autopilot helper
+ * and scout's own annotation use the same boundary.
+ */
+export declare const STALLED_PR_THRESHOLD_DAYS = 30;
+/**
+ * Determine whether an autopilot-shaped `LinkedPR` is stalled.
+ *
+ * True when:
+ *   - the PR is open, AND
+ *   - `updatedAt` is set, AND
+ *   - the elapsed time since `updatedAt` is at least `thresholdDays`.
+ *
+ * Returns false for closed/merged PRs, missing `updatedAt`, or invalid
+ * timestamps. Reimplemented locally rather than delegating to scout's
+ * helper so this module owns autopilot's `LinkedPR` shape contract end
+ * to end (avoids a runtime import dependency on scout's internal type).
+ */
+export declare function isLinkedPRStalled(linkedPR: LinkedPR | null | undefined, now?: Date, thresholdDays?: number): boolean;
 export declare function classifyLinkedPR(params: {
     linkedPR: LinkedPR | null;
     userLogin: string;

package/dist/core/linked-pr-classification.js

@@ -11,6 +11,38 @@
  * linked PR themselves (e.g. via Octokit) and hand the shape to this
  * function. See #978 for the upstream data-contract work.
  */
+/**
+ * Days of inactivity that classify an open linked PR as "stalled" — kept
+ * in sync with scout's `STALLED_PR_THRESHOLD_DAYS` so the autopilot helper
+ * and scout's own annotation use the same boundary.
+ */
+export const STALLED_PR_THRESHOLD_DAYS = 30;
+/**
+ * Determine whether an autopilot-shaped `LinkedPR` is stalled.
+ *
+ * True when:
+ *   - the PR is open, AND
+ *   - `updatedAt` is set, AND
+ *   - the elapsed time since `updatedAt` is at least `thresholdDays`.
+ *
+ * Returns false for closed/merged PRs, missing `updatedAt`, or invalid
+ * timestamps. Reimplemented locally rather than delegating to scout's
+ * helper so this module owns autopilot's `LinkedPR` shape contract end
+ * to end (avoids a runtime import dependency on scout's internal type).
+ */
+export function isLinkedPRStalled(linkedPR, now = new Date(), thresholdDays = STALLED_PR_THRESHOLD_DAYS) {
+    if (!linkedPR)
+        return false;
+    if (linkedPR.state !== 'open')
+        return false;
+    if (!linkedPR.updatedAt)
+        return false;
+    const updatedMs = Date.parse(linkedPR.updatedAt);
+    if (!Number.isFinite(updatedMs))
+        return false;
+    const ageDays = (now.getTime() - updatedMs) / (1000 * 60 * 60 * 24);
+    return ageDays >= thresholdDays;
+}
 /**
  * Normalize a state value from either REST (lowercase `open`/`closed`
  * plus a separate `merged` boolean) or GraphQL (uppercase `OPEN`/

package/dist/formatters/json.d.ts

@@ -509,11 +509,137 @@ export declare const SearchOutputSchema: z.ZodObject<{
             isResponsive: z.ZodBoolean;
             lastMergedAt: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
+        linkedPR: z.ZodOptional<z.ZodObject<{
+            number: z.ZodNumber;
+            state: z.ZodEnum<{
+                closed: "closed";
+                open: "open";
+                merged: "merged";
+            }>;
+            url: z.ZodString;
+            updatedAt: z.ZodOptional<z.ZodString>;
+            isStalled: z.ZodBoolean;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     excludedRepos: z.ZodArray<z.ZodString>;
     aiPolicyBlocklist: z.ZodArray<z.ZodString>;
     rateLimitWarning: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+export declare const FeaturesOutputSchema: z.ZodObject<{
+    quickWins: z.ZodArray<z.ZodObject<{
+        issue: z.ZodObject<{
+            repo: z.ZodString;
+            repoUrl: z.ZodString;
+            number: z.ZodNumber;
+            title: z.ZodString;
+            url: z.ZodString;
+            labels: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        recommendation: z.ZodEnum<{
+            approve: "approve";
+            skip: "skip";
+            needs_review: "needs_review";
+        }>;
+        reasonsToApprove: z.ZodArray<z.ZodString>;
+        reasonsToSkip: z.ZodArray<z.ZodString>;
+        searchPriority: z.ZodEnum<{
+            normal: "normal";
+            merged_pr: "merged_pr";
+            preferred_org: "preferred_org";
+            starred: "starred";
+        }>;
+        viabilityScore: z.ZodNumber;
+        grade: z.ZodObject<{
+            letter: z.ZodEnum<{
+                A: "A";
+                B: "B";
+                C: "C";
+                F: "F";
+            }>;
+            reason: z.ZodString;
+        }, z.core.$strip>;
+        repoScore: z.ZodOptional<z.ZodObject<{
+            score: z.ZodNumber;
+            mergedPRCount: z.ZodNumber;
+            closedWithoutMergeCount: z.ZodNumber;
+            isResponsive: z.ZodBoolean;
+            lastMergedAt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        linkedPR: z.ZodOptional<z.ZodObject<{
+            number: z.ZodNumber;
+            state: z.ZodEnum<{
+                closed: "closed";
+                open: "open";
+                merged: "merged";
+            }>;
+            url: z.ZodString;
+            updatedAt: z.ZodOptional<z.ZodString>;
+            isStalled: z.ZodBoolean;
+        }, z.core.$strip>>;
+        horizon: z.ZodEnum<{
+            "quick-win": "quick-win";
+            "bigger-bet": "bigger-bet";
+        }>;
+    }, z.core.$strip>>;
+    biggerBets: z.ZodArray<z.ZodObject<{
+        issue: z.ZodObject<{
+            repo: z.ZodString;
+            repoUrl: z.ZodString;
+            number: z.ZodNumber;
+            title: z.ZodString;
+            url: z.ZodString;
+            labels: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+        recommendation: z.ZodEnum<{
+            approve: "approve";
+            skip: "skip";
+            needs_review: "needs_review";
+        }>;
+        reasonsToApprove: z.ZodArray<z.ZodString>;
+        reasonsToSkip: z.ZodArray<z.ZodString>;
+        searchPriority: z.ZodEnum<{
+            normal: "normal";
+            merged_pr: "merged_pr";
+            preferred_org: "preferred_org";
+            starred: "starred";
+        }>;
+        viabilityScore: z.ZodNumber;
+        grade: z.ZodObject<{
+            letter: z.ZodEnum<{
+                A: "A";
+                B: "B";
+                C: "C";
+                F: "F";
+            }>;
+            reason: z.ZodString;
+        }, z.core.$strip>;
+        repoScore: z.ZodOptional<z.ZodObject<{
+            score: z.ZodNumber;
+            mergedPRCount: z.ZodNumber;
+            closedWithoutMergeCount: z.ZodNumber;
+            isResponsive: z.ZodBoolean;
+            lastMergedAt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        linkedPR: z.ZodOptional<z.ZodObject<{
+            number: z.ZodNumber;
+            state: z.ZodEnum<{
+                closed: "closed";
+                open: "open";
+                merged: "merged";
+            }>;
+            url: z.ZodString;
+            updatedAt: z.ZodOptional<z.ZodString>;
+            isStalled: z.ZodBoolean;
+        }, z.core.$strip>>;
+        horizon: z.ZodEnum<{
+            "quick-win": "quick-win";
+            "bigger-bet": "bigger-bet";
+        }>;
+    }, z.core.$strip>>;
+    anchorRepos: z.ZodArray<z.ZodString>;
+    message: z.ZodNullable<z.ZodString>;
+    rateLimitWarning: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 export declare const DoctorOutputSchema: z.ZodObject<{
     checks: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -846,46 +972,95 @@ export declare const LocalReposOutputSchema: z.ZodObject<{
     cachedAt: z.ZodString;
     fromCache: z.ZodBoolean;
 }, z.core.$strip>;
+/**
+ * Compact summary of an issue's first linked PR, surfaced on candidate
+ * outputs (#97 / scout 0.9.0). `isStalled` is `true` when the PR is open
+ * and has not been updated for `STALLED_PR_THRESHOLD_DAYS` (default 30) —
+ * a revive-opportunity signal callers can render or filter on.
+ *
+ * `state` mirrors autopilot's existing tri-state classifier (`'merged'` is
+ * folded in from scout's `merged: true` boolean), not scout's raw enum.
+ */
+export interface CandidateLinkedPR {
+    number: number;
+    state: 'open' | 'closed' | 'merged';
+    url: string;
+    /** ISO timestamp of the PR's last update (when scout surfaces it). */
+    updatedAt?: string;
+    /** True when the PR is open AND `updatedAt` is more than 30 days old. */
+    isStalled: boolean;
+}
+/**
+ * One candidate row in `SearchOutput`/`FeaturesOutput`. Extracted so the
+ * features command can reuse the exact contract `runSearch` already
+ * publishes — keeping the two outputs structurally identical for everything
+ * except the bucket-specific `horizon` annotation.
+ */
+export interface SearchCandidate {
+    issue: {
+        repo: string;
+        repoUrl: string;
+        number: number;
+        title: string;
+        url: string;
+        labels: string[];
+    };
+    recommendation: 'approve' | 'skip' | 'needs_review';
+    reasonsToApprove: string[];
+    reasonsToSkip: string[];
+    searchPriority: SearchPriority;
+    /** 0-100 scale composite viability score. Sanitized on the boundary (#1043): out-of-contract values are coerced to 0 and logged. */
+    viabilityScore: number;
+    /**
+     * Letter grade (A/B/C/F) computed from the autopilot-tracked repoScore.
+     * Scout's `search` does not emit per-candidate projectHealth, so scout-side
+     * signals are treated as unknown; unscored repos grade 'F'. See #1043.
+     */
+    grade: {
+        letter: 'A' | 'B' | 'C' | 'F';
+        reason: string;
+    };
+    repoScore?: {
+        /** 1-10 scale repository quality score */
+        score: number;
+        mergedPRCount: number;
+        closedWithoutMergeCount: number;
+        isResponsive: boolean;
+        lastMergedAt?: string;
+    };
+    /**
+     * First linked PR on the issue, when scout surfaced one. Optional —
+     * absent when no linked PR exists. `isStalled` flags revive
+     * opportunities (open PR + no updates for 30+ days, scout 0.9.0 #97).
+     */
+    linkedPR?: CandidateLinkedPR;
+}
 export interface SearchOutput {
-    candidates: Array<{
-        issue: {
-            repo: string;
-            repoUrl: string;
-            number: number;
-            title: string;
-            url: string;
-            labels: string[];
-        };
-        recommendation: 'approve' | 'skip' | 'needs_review';
-        reasonsToApprove: string[];
-        reasonsToSkip: string[];
-        searchPriority: SearchPriority;
-        /** 0-100 scale composite viability score. Sanitized on the boundary (#1043): out-of-contract values are coerced to 0 and logged. */
-        viabilityScore: number;
-        /**
-         * Letter grade (A/B/C/F) computed from the autopilot-tracked repoScore.
-         * Scout's `search` does not emit per-candidate projectHealth, so scout-side
-         * signals are treated as unknown; unscored repos grade 'F'. See #1043.
-         */
-        grade: {
-            letter: 'A' | 'B' | 'C' | 'F';
-            reason: string;
-        };
-        repoScore?: {
-            /** 1-10 scale repository quality score */
-            score: number;
-            mergedPRCount: number;
-            closedWithoutMergeCount: number;
-            isResponsive: boolean;
-            lastMergedAt?: string;
-        };
-    }>;
+    candidates: SearchCandidate[];
     excludedRepos: string[];
     /** Repos with known anti-AI contribution policies, filtered from search results (#108). */
     aiPolicyBlocklist: string[];
     /** Present when rate limits affected the search — either low pre-flight quota or mid-search rate limit hits (#100). */
     rateLimitWarning?: string;
 }
+/** Horizon classification stamped on each features-mode candidate. */
+export type FeaturesHorizon = 'quick-win' | 'bigger-bet';
+/** A `SearchCandidate` augmented with its features-mode horizon. */
+export type FeaturesCandidate = SearchCandidate & {
+    horizon: FeaturesHorizon;
+};
+export interface FeaturesOutput {
+    /** "Quick-win" bucket: feature-scoped issues without strong commitment markers (no milestone, no roadmap, no bigger-bet labels). */
+    quickWins: FeaturesCandidate[];
+    /** "Bigger-bet" bucket: feature-scoped issues that carry maintainer-commitment signals (milestone, roadmap, bigger-bet label). */
+    biggerBets: FeaturesCandidate[];
+    /** Repos that qualified as anchors for this run (3+ merged PRs, configurable). Empty when the user has no anchor repos yet. */
+    anchorRepos: string[];
+    /** Human-friendly explainer shown when neither bucket has results (no anchors, or anchors but no open feature opportunities). `null` on success. */
+    message: string | null;
+    /** Present when rate limits affected the search. Mirrors `SearchOutput.rateLimitWarning`. */
+    rateLimitWarning?: string;
+}
 export interface TrackOutput {
     pr: {
         repo: string;
@@ -991,8 +1166,14 @@ export interface CheckIntegrationOutput {
     newFiles: NewFileInfo[];
     unreferencedCount: number;
 }
-/** Status of a re-vetted issue from the curated list (#764). */
-export type VetListItemStatus = 'still_available' | 'claimed' | 'closed' | 'has_pr' | 'error';
+/**
+ * Status of a re-vetted issue from the curated list (#764).
+ *
+ * `has_stalled_pr` (scout 0.9.0 #97) distinguishes open-but-stalled linked
+ * PRs from cleanly-claimed `has_pr` issues — the issue is still actionable
+ * as a revive opportunity rather than something to drop.
+ */
+export type VetListItemStatus = 'still_available' | 'claimed' | 'closed' | 'has_pr' | 'has_stalled_pr' | 'error';
 /** Output of the vet-list command (#764). */
 export interface VetListOutput {
     results: Array<VetOutput & {
@@ -1005,6 +1186,8 @@ export interface VetListOutput {
         claimed: number;
         closed: number;
         hasPR: number;
+        /** Open linked PRs that haven't been touched in 30+ days (scout 0.9.0 #97). Surfaced as revive opportunities, not auto-dropped. */
+        hasStalledPR: number;
         errors: number;
     };
     pruneResult?: {
@@ -1042,6 +1225,12 @@ export interface VetOutput {
      * already has work in flight vs. a competing contributor.
      */
     linkedPRClassification?: 'none' | 'user_open' | 'user_closed' | 'user_merged' | 'other_open' | 'other_closed' | 'other_merged';
+    /**
+     * Compact linked-PR summary (#97 / scout 0.9.0). Present when the issue
+     * has a linked PR; absent otherwise. `isStalled` flags open PRs that
+     * haven't been touched in 30+ days as revive opportunities.
+     */
+    linkedPR?: CandidateLinkedPR;
     /**
      * Optional SLM pre-triage classification (#1122). Populated when the
      * user has set `slmTriageModel` and a local Ollama instance answered

package/dist/formatters/json.js

@@ -284,6 +284,17 @@ export const CompactDailyOutputSchema = z.object({
 });
 // ── Search output schema (#1147) ─────────────────────────────────────
 const SearchPrioritySchema = z.enum(['merged_pr', 'preferred_org', 'starred', 'normal']);
+/**
+ * Schema for the compact linked-PR annotation surfaced on candidate
+ * outputs (#97 / scout 0.9.0). Mirrors {@link CandidateLinkedPR}.
+ */
+const CandidateLinkedPRSchema = z.object({
+    number: z.number().int().positive(),
+    state: z.enum(['open', 'closed', 'merged']),
+    url: z.string(),
+    updatedAt: z.string().optional(),
+    isStalled: z.boolean(),
+});
 const SearchCandidateSchema = z.object({
     issue: z.object({
         repo: z.string(),
@@ -311,6 +322,7 @@ const SearchCandidateSchema = z.object({
         lastMergedAt: z.string().optional(),
     })
         .optional(),
+    linkedPR: CandidateLinkedPRSchema.optional(),
 });
 export const SearchOutputSchema = z.object({
     candidates: z.array(SearchCandidateSchema),
@@ -318,6 +330,22 @@ export const SearchOutputSchema = z.object({
     aiPolicyBlocklist: z.array(z.string()),
     rateLimitWarning: z.string().optional(),
 });
+// ── Features output schema (scout 0.9.0 #97/#98/#99) ─────────────────
+//
+// `SearchCandidateSchema` augmented with the horizon literal that scout
+// stamps in features mode. Reusing the search candidate keeps the two
+// envelopes structurally identical apart from the bucket annotation.
+const FeaturesHorizonSchema = z.enum(['quick-win', 'bigger-bet']);
+const FeaturesCandidateSchema = SearchCandidateSchema.extend({
+    horizon: FeaturesHorizonSchema,
+});
+export const FeaturesOutputSchema = z.object({
+    quickWins: z.array(FeaturesCandidateSchema),
+    biggerBets: z.array(FeaturesCandidateSchema),
+    anchorRepos: z.array(z.string()),
+    message: z.string().nullable(),
+    rateLimitWarning: z.string().optional(),
+});
 // ── Doctor / skip-add / list-move-tier output schemas (#1148) ────────
 const DoctorCheckSchema = z.object({
     name: z.string(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oss-autopilot/core",
-  "version": "3.6.0",
+  "version": "3.7.0",
   "description": "CLI and core library for managing open source contributions",
   "type": "module",
   "bin": {
@@ -54,7 +54,7 @@
   "dependencies": {
     "@octokit/plugin-throttling": "^11.0.3",
     "@octokit/rest": "^22.0.1",
-    "@oss-scout/core": "^0.8.0",
+    "@oss-scout/core": "^0.9.0",
     "commander": "^14.0.3",
     "zod": "^4.4.3"
   },