@oss-autopilot/core 3.4.1 → 3.5.0

package/dist/core/repo-vet.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Repo health scoring (#1242).
+ *
+ * Extracted from `agents/repo-evaluator.md`'s in-prompt assembly logic
+ * so the rubric weights, sub-factor thresholds, and verdict cutoffs
+ * are deterministic, unit-testable, and tunable without editing
+ * markdown. Same architectural shape as success-grade (#858),
+ * compliance-score (#1245), and strategy (#1243).
+ *
+ * The function is pure — callers (the MCP tool, the CLI command)
+ * supply pre-fetched repo signals so the score is reproducible
+ * against fixture data and offline replays.
+ *
+ * Rubric reference: docs/repo-rubric.md.
+ */
+export interface RepoVetInput {
+    /** Star count from the GitHub repo metadata. */
+    stars: number;
+    forks: number;
+    openIssues: number;
+    watchers: number;
+    isArchived: boolean;
+    /** ISO-8601 timestamp of the last push. */
+    lastPushed: string;
+    /** ISO-8601 timestamp of repo creation. */
+    createdAt: string;
+    /** Number of commits to the default branch in the last 30 days. */
+    commitsLast30Days: number;
+    /** Per-PR `createdAt → mergedAt` durations in days, for the last 90
+     * days of merged PRs. Used to derive avg / median merge time. */
+    prMergeTimesDays: number[];
+    /** Count of merges in the last 90 days. */
+    mergedCount90Days: number;
+    /** Count of opened PRs in the last 90 days. Used for merge rate. */
+    openedCount90Days: number;
+    /** ISO-8601 timestamp of the most recent commit on the default branch. */
+    lastCommitISO: string | null;
+    /** Distinct authors who committed in the last 90 days. */
+    contributorsLast90d: number;
+    /** ISO-8601 timestamp of the most recent published release. */
+    lastReleaseISO: string | null;
+    hasContributing: boolean;
+    hasIssueTemplates: boolean;
+    hasPRTemplate: boolean;
+    hasCodeOfConduct: boolean;
+}
+export type RepoVetVerdict = 'recommended' | 'proceed_with_caution' | 'avoid';
+export interface RepoVetResult {
+    repo: {
+        stars: number;
+        forks: number;
+        openIssues: number;
+        watchers: number;
+        isArchived: boolean;
+        lastPushed: string;
+        createdAt: string;
+    };
+    prMergeTime: {
+        avgDays: number | null;
+        medianDays: number | null;
+        sampleSize: number;
+        sourceWindowDays: 90;
+    };
+    mergeRate: {
+        merged: number;
+        opened: number;
+        percent: number | null;
+        windowDays: 90;
+    };
+    maintainerActivity: {
+        lastCommitISO: string | null;
+        contributorsLast90d: number;
+        lastReleaseISO: string | null;
+    };
+    communityHealth: {
+        contributing: boolean;
+        issueTemplates: boolean;
+        prTemplate: boolean;
+        codeOfConduct: boolean;
+    };
+    /** Weighted 1-10 score per docs/repo-rubric.md. */
+    rubricScore: number;
+    /** Top-line verdict derived from the score and red-flag overrides. */
+    rubricVerdict: RepoVetVerdict;
+}
+/**
+ * Compute repo-health metrics and an overall rubric score from
+ * pre-fetched signals (#1242). Pure function — no I/O, no global state.
+ */
+export declare function computeRepoVet(input: RepoVetInput): RepoVetResult;

package/dist/core/repo-vet.js

@@ -0,0 +1,178 @@
+/**
+ * Repo health scoring (#1242).
+ *
+ * Extracted from `agents/repo-evaluator.md`'s in-prompt assembly logic
+ * so the rubric weights, sub-factor thresholds, and verdict cutoffs
+ * are deterministic, unit-testable, and tunable without editing
+ * markdown. Same architectural shape as success-grade (#858),
+ * compliance-score (#1245), and strategy (#1243).
+ *
+ * The function is pure — callers (the MCP tool, the CLI command)
+ * supply pre-fetched repo signals so the score is reproducible
+ * against fixture data and offline replays.
+ *
+ * Rubric reference: docs/repo-rubric.md.
+ */
+const WEIGHTS = {
+    activity: 0.25,
+    prSpeed: 0.25,
+    mergeRate: 0.2,
+    guidelines: 0.1,
+    stability: 0.05,
+    /** Responsiveness (15%) is documented in the rubric but the input
+     * shape doesn't surface it — `gh pr list --json` doesn't expose
+     * "time to first review". Per the rubric note, omit it rather than
+     * fabricate it. The remaining weights total 0.85 and are normalized
+     * to a 10-point ceiling at the end. */
+};
+const SUM_OF_AVAILABLE_WEIGHTS = WEIGHTS.activity + WEIGHTS.prSpeed + WEIGHTS.mergeRate + WEIGHTS.guidelines + WEIGHTS.stability;
+const VERDICT_CUTOFFS = {
+    recommended: 7.5,
+    cautious: 5,
+};
+function median(nums) {
+    if (nums.length === 0)
+        return 0;
+    const sorted = [...nums].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+function activitySubScore(input) {
+    // 1.0 when commits/30d ≥ 30 (one per day), 0 when 0, linear in between.
+    if (input.isArchived)
+        return 0;
+    return Math.min(1, input.commitsLast30Days / 30);
+}
+function prSpeedSubScore(input) {
+    // Rubric: avg PR merge time < 7 days = healthy. Linear: 0d → 1.0,
+    // 14d+ → 0.0. Sample of zero merges = 0 score (no signal of speed).
+    if (input.prMergeTimesDays.length === 0)
+        return 0;
+    const avg = input.prMergeTimesDays.reduce((sum, d) => sum + d, 0) / input.prMergeTimesDays.length;
+    if (avg <= 0)
+        return 1;
+    if (avg >= 14)
+        return 0;
+    return Math.max(0, Math.min(1, (14 - avg) / 14));
+}
+function mergeRateSubScore(input) {
+    // Rubric: >70% merged in last 90 days. Linear: 100% → 1.0, 0% → 0.
+    if (input.openedCount90Days === 0)
+        return 0;
+    const rate = input.mergedCount90Days / input.openedCount90Days;
+    return Math.max(0, Math.min(1, rate));
+}
+function guidelinesSubScore(input) {
+    // Each of the four community-health flags contributes equally.
+    let score = 0;
+    if (input.hasContributing)
+        score += 0.4;
+    if (input.hasIssueTemplates)
+        score += 0.25;
+    if (input.hasPRTemplate)
+        score += 0.25;
+    if (input.hasCodeOfConduct)
+        score += 0.1;
+    return Math.min(1, score);
+}
+function stabilitySubScore(input) {
+    // Rubric: not archived, regular releases. Half-credit for not-archived,
+    // half for a release within the last 6 months.
+    if (input.isArchived)
+        return 0;
+    let score = 0.5;
+    if (input.lastReleaseISO) {
+        const since = Date.now() - new Date(input.lastReleaseISO).getTime();
+        const sixMonths = 1000 * 60 * 60 * 24 * 30 * 6;
+        if (since <= sixMonths)
+            score += 0.5;
+    }
+    return score;
+}
+/**
+ * Hard red-flag overrides — when one fires, verdict drops to `avoid`
+ * regardless of the weighted score. Sourced verbatim from the rubric.
+ */
+function hasRedFlags(input) {
+    if (input.isArchived)
+        return true;
+    if (input.lastCommitISO) {
+        const sinceCommit = Date.now() - new Date(input.lastCommitISO).getTime();
+        const sixtyDays = 60 * 24 * 60 * 60 * 1000;
+        if (sinceCommit > sixtyDays)
+            return true;
+    }
+    if (input.openedCount90Days > 0 && input.mergedCount90Days === 0)
+        return true;
+    return false;
+}
+function deriveVerdict(score, redFlags) {
+    if (redFlags)
+        return 'avoid';
+    if (score >= VERDICT_CUTOFFS.recommended)
+        return 'recommended';
+    if (score >= VERDICT_CUTOFFS.cautious)
+        return 'proceed_with_caution';
+    return 'avoid';
+}
+/**
+ * Compute repo-health metrics and an overall rubric score from
+ * pre-fetched signals (#1242). Pure function — no I/O, no global state.
+ */
+export function computeRepoVet(input) {
+    const subScores = {
+        activity: activitySubScore(input),
+        prSpeed: prSpeedSubScore(input),
+        mergeRate: mergeRateSubScore(input),
+        guidelines: guidelinesSubScore(input),
+        stability: stabilitySubScore(input),
+    };
+    // Weighted average normalized to the 10-point ceiling.
+    const weightedSum = subScores.activity * WEIGHTS.activity +
+        subScores.prSpeed * WEIGHTS.prSpeed +
+        subScores.mergeRate * WEIGHTS.mergeRate +
+        subScores.guidelines * WEIGHTS.guidelines +
+        subScores.stability * WEIGHTS.stability;
+    const rubricScore = Math.round((weightedSum / SUM_OF_AVAILABLE_WEIGHTS) * 100) / 10;
+    const sampleSize = input.prMergeTimesDays.length;
+    const avgDays = sampleSize === 0 ? null : input.prMergeTimesDays.reduce((s, d) => s + d, 0) / sampleSize;
+    const medianDays = sampleSize === 0 ? null : median(input.prMergeTimesDays);
+    // Cap at 100. A repo clearing a backlog can have mergedCount > openedCount
+    // because PRs opened before the window can merge inside it — without the
+    // cap, the surfaced text would read "Merge rate (90d): 160% (8/5)" which
+    // looks like a tool bug. The score itself is fine (mergeRateSubScore
+    // clamps separately); this just keeps the display sensible.
+    const mergeRatePercent = input.openedCount90Days === 0 ? null : Math.min(100, (input.mergedCount90Days / input.openedCount90Days) * 100);
+    const verdict = deriveVerdict(rubricScore, hasRedFlags(input));
+    return {
+        repo: {
+            stars: input.stars,
+            forks: input.forks,
+            openIssues: input.openIssues,
+            watchers: input.watchers,
+            isArchived: input.isArchived,
+            lastPushed: input.lastPushed,
+            createdAt: input.createdAt,
+        },
+        prMergeTime: { avgDays, medianDays, sampleSize, sourceWindowDays: 90 },
+        mergeRate: {
+            merged: input.mergedCount90Days,
+            opened: input.openedCount90Days,
+            percent: mergeRatePercent,
+            windowDays: 90,
+        },
+        maintainerActivity: {
+            lastCommitISO: input.lastCommitISO,
+            contributorsLast90d: input.contributorsLast90d,
+            lastReleaseISO: input.lastReleaseISO,
+        },
+        communityHealth: {
+            contributing: input.hasContributing,
+            issueTemplates: input.hasIssueTemplates,
+            prTemplate: input.hasPRTemplate,
+            codeOfConduct: input.hasCodeOfConduct,
+        },
+        rubricScore,
+        rubricVerdict: verdict,
+    };
+}

package/dist/core/state-schema.d.ts

@@ -78,6 +78,53 @@ export declare const AnalyzedIssueConversationSchema: z.ZodObject<{
     repo: z.ZodString;
     analyzedAt: z.ZodString;
 }, z.core.$strip>;
+/**
+ * One entry in a PR's follow-up history (#1277). Tier matches the
+ * cadence labels in `skills/pr-etiquette/SKILL.md` (light_check_in
+ * for 7-13 days, direct_check_in for 14-29 days, final_check_in for
+ * 30+ days). The `draftPath` is optional so an entry recorded from a
+ * direct `gh pr comment` (no draft) still validates.
+ */
+export declare const FollowUpEntrySchema: z.ZodObject<{
+    tier: z.ZodEnum<{
+        light_check_in: "light_check_in";
+        direct_check_in: "direct_check_in";
+        final_check_in: "final_check_in";
+    }>;
+    timestamp: z.ZodString;
+    draftPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type FollowUpEntry = z.infer<typeof FollowUpEntrySchema>;
+/**
+ * Pause-point snapshot for resumable workflows (#1280). When the user
+ * picks "Done for now" inside `draft-first-workflow.md`,
+ * `work-through-issues.md`, or `pre-commit-review.md`, the workflow
+ * records its position here. The next `/oss` run consults this state
+ * and offers "Resume / Restart / Discard" instead of restarting from
+ * the beginning.
+ *
+ * `stepData` is intentionally typed as `Record<string, unknown>` so
+ * each workflow can persist whatever per-step context it needs to
+ * resume cleanly (compliance-gap skip list, last review pass count,
+ * etc.) without forcing a tagged-union schema in shared state.
+ */
+export declare const WorkflowStateSchema: z.ZodObject<{
+    workflowName: z.ZodEnum<{
+        "draft-first": "draft-first";
+        "work-through-issues": "work-through-issues";
+        "pre-commit-review": "pre-commit-review";
+    }>;
+    currentStep: z.ZodString;
+    branchName: z.ZodOptional<z.ZodString>;
+    issueContext: z.ZodOptional<z.ZodObject<{
+        title: z.ZodString;
+        url: z.ZodString;
+    }, z.core.$strip>>;
+    completedSteps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    stepData: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    lastUpdatedAt: z.ZodString;
+}, z.core.$strip>;
+export type WorkflowState = z.infer<typeof WorkflowStateSchema>;
 export declare const ContributionGuidelinesSchema: z.ZodObject<{
     branchNamingConvention: z.ZodOptional<z.ZodString>;
     commitMessageFormat: z.ZodOptional<z.ZodString>;
@@ -243,6 +290,8 @@ export declare const AgentConfigSchema: z.ZodObject<{
     }>>;
     diffToolCustomCommand: z.ZodOptional<z.ZodString>;
     autoFormatBeforePush: z.ZodDefault<z.ZodBoolean>;
+    healthCheckFreshnessMinutes: z.ZodDefault<z.ZodNumber>;
+    reviewMaxPasses: z.ZodOptional<z.ZodNumber>;
     slmTriageModel: z.ZodDefault<z.ZodString>;
     slmTriageHost: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
@@ -403,6 +452,8 @@ export declare const AgentStateSchema: z.ZodObject<{
         }>>;
         diffToolCustomCommand: z.ZodOptional<z.ZodString>;
         autoFormatBeforePush: z.ZodDefault<z.ZodBoolean>;
+        healthCheckFreshnessMinutes: z.ZodDefault<z.ZodNumber>;
+        reviewMaxPasses: z.ZodOptional<z.ZodNumber>;
         slmTriageModel: z.ZodDefault<z.ZodString>;
         slmTriageHost: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
@@ -532,6 +583,31 @@ export declare const AgentStateSchema: z.ZodObject<{
             notes: z.ZodArray<z.ZodString>;
         }, z.core.$strip>>;
     }, z.core.$strip>>>;
+    prFollowUpHistory: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodObject<{
+        tier: z.ZodEnum<{
+            light_check_in: "light_check_in";
+            direct_check_in: "direct_check_in";
+            final_check_in: "final_check_in";
+        }>;
+        timestamp: z.ZodString;
+        draftPath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>>;
+    workflowState: z.ZodOptional<z.ZodObject<{
+        workflowName: z.ZodEnum<{
+            "draft-first": "draft-first";
+            "work-through-issues": "work-through-issues";
+            "pre-commit-review": "pre-commit-review";
+        }>;
+        currentStep: z.ZodString;
+        branchName: z.ZodOptional<z.ZodString>;
+        issueContext: z.ZodOptional<z.ZodObject<{
+            title: z.ZodString;
+            url: z.ZodString;
+        }, z.core.$strip>>;
+        completedSteps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        stepData: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        lastUpdatedAt: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type IssueStatus = z.infer<typeof IssueStatusSchema>;
 export type FetchedPRStatus = z.infer<typeof FetchedPRStatusSchema>;

package/dist/core/state-schema.js

@@ -67,6 +67,45 @@ export const AnalyzedIssueConversationSchema = z.object({
     repo: z.string(),
     analyzedAt: z.string(),
 });
+/**
+ * One entry in a PR's follow-up history (#1277). Tier matches the
+ * cadence labels in `skills/pr-etiquette/SKILL.md` (light_check_in
+ * for 7-13 days, direct_check_in for 14-29 days, final_check_in for
+ * 30+ days). The `draftPath` is optional so an entry recorded from a
+ * direct `gh pr comment` (no draft) still validates.
+ */
+export const FollowUpEntrySchema = z.object({
+    tier: z.enum(['light_check_in', 'direct_check_in', 'final_check_in']),
+    timestamp: z.string().datetime(),
+    draftPath: z.string().optional(),
+});
+/**
+ * Pause-point snapshot for resumable workflows (#1280). When the user
+ * picks "Done for now" inside `draft-first-workflow.md`,
+ * `work-through-issues.md`, or `pre-commit-review.md`, the workflow
+ * records its position here. The next `/oss` run consults this state
+ * and offers "Resume / Restart / Discard" instead of restarting from
+ * the beginning.
+ *
+ * `stepData` is intentionally typed as `Record<string, unknown>` so
+ * each workflow can persist whatever per-step context it needs to
+ * resume cleanly (compliance-gap skip list, last review pass count,
+ * etc.) without forcing a tagged-union schema in shared state.
+ */
+export const WorkflowStateSchema = z.object({
+    workflowName: z.enum(['draft-first', 'work-through-issues', 'pre-commit-review']),
+    currentStep: z.string(),
+    branchName: z.string().optional(),
+    issueContext: z
+        .object({
+        title: z.string(),
+        url: z.string(),
+    })
+        .optional(),
+    completedSteps: z.array(z.string()).default([]),
+    stepData: z.record(z.string(), z.unknown()).default({}),
+    lastUpdatedAt: z.string().datetime(),
+});
 // ── 3. Contribution schemas ──────────────────────────────────────────
 export const ContributionGuidelinesSchema = z.object({
     branchNamingConvention: z.string().optional(),
@@ -161,6 +200,25 @@ export const AgentConfigSchema = z.object({
      * the hook does nothing on every push unless the user explicitly enables it.
      */
     autoFormatBeforePush: z.boolean().default(false),
+    /**
+     * Threshold (in minutes) for the SessionStart PR health one-liner (#1255).
+     * The cached digest only refreshes when the user runs `/oss`; SessionStart
+     * fires every session. Without a freshness gate the line drifts arbitrarily
+     * stale between runs. When the cache is older than this many minutes (and
+     * not yet 7 days old, which keeps the existing catch-up nudge), the line is
+     * suppressed entirely. Default 30 minutes.
+     */
+    healthCheckFreshnessMinutes: z.number().int().positive().default(30),
+    /**
+     * Convergence cap for the multi-agent review loop in
+     * `workflows/dispatch-review.md` (#1275). When unset, the workflow
+     * falls back to per-mode defaults (5 for diff, 3 for plan). Lower
+     * values shorten the loop at the cost of skipping later iterations
+     * if findings persist; higher values give the loop more chances to
+     * converge before bailing. Optional — leave unset to use the
+     * defaults.
+     */
+    reviewMaxPasses: z.number().int().positive().optional(),
     /**
      * Optional Ollama model for SLM pre-triage during issue vetting (#1122).
      * Empty disables the feature. Recommended: `gemma4:e4b` (default for
@@ -236,4 +294,21 @@ export const AgentStateSchema = z.object({
     closedPRs: z.array(StoredClosedPRSchema).optional(),
     analyzedIssueConversations: z.array(AnalyzedIssueConversationSchema).optional(),
     activeIssues: z.array(TrackedIssueSchema).default([]),
+    /**
+     * Per-PR follow-up history (#1277). Keyed by PR URL. Each entry
+     * records a tier-bucketed follow-up that the user drafted (and
+     * presumably posted via `draft-review-post`). The dormant-pr
+     * workflow reads this before drafting to enforce the
+     * one-follow-up-per-timeframe rule documented in
+     * `skills/pr-etiquette/SKILL.md`.
+     */
+    prFollowUpHistory: z.record(z.string(), z.array(FollowUpEntrySchema)).optional(),
+    /**
+     * Pause-point snapshot for resumable workflows (#1280). Set when
+     * the user picks "Done for now" mid-workflow; cleared when the
+     * workflow completes or the user explicitly discards. The router
+     * reads this on every `/oss` invocation and offers Resume /
+     * Restart / Discard when present.
+     */
+    workflowState: WorkflowStateSchema.optional(),
 });

package/dist/core/strategy.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Contribution strategy compute (#1243).
+ *
+ * Extracts the deterministic compute layer from
+ * `agents/contribution-strategist.md` so the categorization,
+ * trajectory detection, and capacity overextension rules are typed,
+ * unit-testable, and consumable both by the agent (synthesis layer)
+ * and a future auto-display in `/oss`.
+ *
+ * Same architectural shape as success-grade (#858), linked-PR
+ * classifier (#910), and compliance-score (#1245). Pure function — no
+ * I/O, no global state, no LLM. The interpretive narrative ("you're
+ * doing X well, here's a growth opportunity") stays in the agent
+ * prompt.
+ */
+import type { AgentState } from './state-schema.js';
+export type ContributorStyle = 'maintainer' | 'explorer' | 'specialist' | 'generalist';
+export type TrajectoryDirection = 'growing' | 'steady' | 'declining';
+export type CapacityAction = 'open_more' | 'follow_up_dormant' | 'wait_on_maintainers' | null;
+export interface StrategyProfile {
+    style: ContributorStyle;
+    totalPRs: number;
+    mergedCount: number;
+    /** Merge rate as a 0-1 fraction. `0` when no PRs are tracked. */
+    mergeRate: number;
+    /** Top languages by repo PR count, descending. Empty when language data
+     * is not available in repoScores. */
+    primaryLanguages: string[];
+    /** Top repos by merged PR count, descending. */
+    favoriteRepos: string[];
+}
+export interface StrategyCapacity {
+    openPRCount: number;
+    dormantPRCount: number;
+    /** True when dormant PRs span >=2 distinct repos (a signal that the
+     * contributor is awaiting reviews from multiple maintainers, not just
+     * one slow project). */
+    overExtended: boolean;
+    /** The single highest-priority next action — null when state is too
+     * thin to recommend anything. */
+    suggestedAction: CapacityAction;
+}
+export interface StrategyPatterns {
+    prTypeDistribution: {
+        docs: number;
+        fixes: number;
+        features: number;
+        refactors: number;
+        tests: number;
+        other: number;
+    };
+    trajectoryDirection: TrajectoryDirection;
+    averagePRSize: number;
+}
+export interface StrategyRecommendations {
+    languages: string[];
+    repos: string[];
+    issueTypes: string[];
+    avoidPatterns: string[];
+}
+export interface StrategyResult {
+    profile: StrategyProfile;
+    capacity: StrategyCapacity;
+    patterns: StrategyPatterns;
+    recommendations: StrategyRecommendations;
+}
+/** Minimum tracked PR history before strategy output is meaningful (#1243). */
+export declare const STRATEGY_MIN_PRS = 10;
+/**
+ * Compute the deterministic strategy signal from agent state. Returns
+ * null when state is thinner than {@link STRATEGY_MIN_PRS} merged PRs —
+ * the auto-display surface uses this null sentinel as the
+ * minimum-data gate (#1243).
+ */
+export declare function computeStrategy(state: AgentState): StrategyResult | null;