@oss-autopilot/core 3.4.1 → 3.6.0

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
@@ -227,6 +285,15 @@ export const AgentStateSchema = z.object({
     config: AgentConfigSchema.default(() => AgentConfigSchema.parse({})),
     lastRunAt: z.string().default(() => new Date().toISOString()),
     lastDigestAt: z.string().optional(),
+    /**
+     * ISO timestamp of the most recent {@link computeStrategy} invocation
+     * embedded in a daily run output (#1270). The cadence gate in
+     * `daily.ts` consults this — strategy snapshots fire every 30 days OR
+     * when 5+ PRs have merged since the last snapshot, whichever comes
+     * first. Below {@link STRATEGY_MIN_PRS} merged PRs the gate stays
+     * silent regardless of cadence.
+     */
+    lastStrategyAt: z.string().optional(),
     lastDigest: DailyDigestSchema.optional(),
     monthlyMergedCounts: z.record(z.string(), z.number()).optional(),
     monthlyClosedCounts: z.record(z.string(), z.number()).optional(),
@@ -236,4 +303,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/state.d.ts

@@ -174,6 +174,13 @@ export declare class StateManager {
      * @param digest - The daily digest to store
      */
     setLastDigest(digest: DailyDigest): void;
+    /**
+     * Persist the timestamp of the most recent strategy snapshot embedded
+     * in a daily run output (#1270). Called from the daily pipeline after
+     * `computeStrategy()` succeeds; the cadence gate in
+     * {@link shouldComputeStrategy} reads this on the next run.
+     */
+    setLastStrategyAt(iso: string): void;
     /**
      * Update monthly merged PR counts for dashboard display.
      * @param counts - Monthly merged PR counts keyed by YYYY-MM

package/dist/core/state.js

@@ -416,6 +416,16 @@ export class StateManager {
         this.state.lastDigestAt = digest.generatedAt;
         this.autoSave();
     }
+    /**
+     * Persist the timestamp of the most recent strategy snapshot embedded
+     * in a daily run output (#1270). Called from the daily pipeline after
+     * `computeStrategy()` succeeds; the cadence gate in
+     * {@link shouldComputeStrategy} reads this on the next run.
+     */
+    setLastStrategyAt(iso) {
+        this.state.lastStrategyAt = iso;
+        this.autoSave();
+    }
     /**
      * Update monthly merged PR counts for dashboard display.
      * @param counts - Monthly merged PR counts keyed by YYYY-MM

package/dist/core/strategy.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 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;
+    /** Distinct repos hosting at least one dormant PR. Surfaces alongside
+     * `dormantPRCount` so consumers can render "N PRs across M repos"
+     * without re-deriving from `openPRs` themselves. */
+    dormantRepoCount: 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). Equivalent to `dormantPRCount >= 2 &&
+     * dormantRepoCount >= 2` — exposed as a separate boolean so callers
+     * with a strict yes/no presentation don't have to recompute. */
+    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;
+/** Cadence trigger thresholds for the auto-display in `/oss` (#1270). */
+export declare const STRATEGY_CADENCE_DAYS = 30;
+export declare const STRATEGY_CADENCE_MERGED_DELTA = 5;
+/**
+ * Decide whether a strategy snapshot should be embedded in this daily run.
+ * Returns true when EITHER 30 days have elapsed since the last snapshot OR
+ * 5+ PRs have merged since then, AND the merge floor in
+ * {@link STRATEGY_MIN_PRS} is met. The caller is responsible for calling
+ * {@link computeStrategy} when this returns true and for persisting
+ * `state.lastStrategyAt` after a successful compute.
+ *
+ * `nowIso` is injected so tests can pin time without mocking `Date`.
+ */
+export declare function shouldComputeStrategy(state: AgentState, nowIso: string): boolean;

package/dist/core/strategy.js

@@ -0,0 +1,270 @@
+/**
+ * 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.
+ */
+/** Minimum tracked PR history before strategy output is meaningful (#1243). */
+export const STRATEGY_MIN_PRS = 10;
+/** How many top-N items each "primary" / "favorite" list returns. */
+const TOP_N = 5;
+/** Days since `mergedAt` after which a PR no longer counts as recent for
+ * the active-now PR-type distribution. 90 days matches the issue's
+ * proposed trajectory window. */
+const RECENT_WINDOW_DAYS = 90;
+/** Match repo from a GitHub URL: `https://github.com/owner/repo/pull/N`. */
+const REPO_FROM_URL = /https:\/\/github\.com\/([^/]+)\/([^/]+)\/(?:issues|pull)\/\d+/i;
+function parseRepo(url) {
+    const m = url.match(REPO_FROM_URL);
+    return m ? `${m[1]}/${m[2]}` : null;
+}
+function classifyTitle(title) {
+    const t = title.trim().toLowerCase();
+    // Match Conventional Commits prefix first; fall back to keyword search
+    // in the title body.
+    const prefix = t.match(/^(feat|fix|docs|refactor|test|perf|chore|build|ci|style|revert)(?:\([^)]+\))?!?:/);
+    const tag = prefix?.[1];
+    if (tag === 'docs')
+        return 'docs';
+    if (tag === 'fix' || tag === 'perf')
+        return 'fixes';
+    if (tag === 'feat')
+        return 'features';
+    if (tag === 'refactor')
+        return 'refactors';
+    if (tag === 'test')
+        return 'tests';
+    // Heuristic fallbacks for non-conventional titles.
+    if (/\b(?:doc|readme|comment|typo)\b/i.test(t))
+        return 'docs';
+    if (/\b(?:fix|bug|crash|regression|broken)\b/i.test(t))
+        return 'fixes';
+    if (/\b(?:add|implement|introduce|support|new)\b/i.test(t))
+        return 'features';
+    if (/\b(?:refactor|cleanup|extract|simplify|rename)\b/i.test(t))
+        return 'refactors';
+    if (/\btest|spec\b/i.test(t))
+        return 'tests';
+    return 'other';
+}
+function topNByCount(counts, n) {
+    return Object.entries(counts)
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, n)
+        .map(([name]) => name);
+}
+function determineStyle(_totalPRs, primaryLanguages, favoriteRepos) {
+    // `totalPRs` is reserved for future "explorer" classification (low-volume
+    // contributors). Today the function is only reachable from `computeStrategy`
+    // which gates at `merged.length >= STRATEGY_MIN_PRS` (10), so a `totalPRs < 5`
+    // branch could never fire — removed to avoid misleading future readers.
+    // Heavy concentration in 1-2 repos → maintainer; spread across many → generalist.
+    if (favoriteRepos.length === 1)
+        return 'maintainer';
+    if (primaryLanguages.length === 1 && favoriteRepos.length >= 2 && favoriteRepos.length <= 3) {
+        return 'specialist';
+    }
+    if (favoriteRepos.length >= 4)
+        return 'generalist';
+    return 'specialist';
+}
+function determineTrajectory(state) {
+    // Compare the last three months' merged PR counts against the prior
+    // three months. If each window has at least one merge, ratio >1.2 is
+    // growing, <0.8 is declining, otherwise steady.
+    const counts = state.monthlyMergedCounts ?? {};
+    const months = Object.keys(counts).sort();
+    if (months.length < 6)
+        return 'steady';
+    const recent = months.slice(-3).reduce((sum, m) => sum + (counts[m] ?? 0), 0);
+    const prior = months.slice(-6, -3).reduce((sum, m) => sum + (counts[m] ?? 0), 0);
+    if (prior === 0)
+        return recent > 0 ? 'growing' : 'steady';
+    const ratio = recent / prior;
+    if (ratio >= 1.2)
+        return 'growing';
+    if (ratio <= 0.8)
+        return 'declining';
+    return 'steady';
+}
+function recommendForOverExtension(openPRCount, dormantPRCount, overExtended) {
+    if (overExtended)
+        return 'follow_up_dormant';
+    if (dormantPRCount > 0 && openPRCount > 5)
+        return 'wait_on_maintainers';
+    if (openPRCount === 0)
+        return 'open_more';
+    return null;
+}
+/**
+ * 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 function computeStrategy(state) {
+    const merged = state.mergedPRs ?? [];
+    const closed = state.closedPRs ?? [];
+    const totalPRs = merged.length + closed.length;
+    if (merged.length < STRATEGY_MIN_PRS)
+        return null;
+    // Per-repo PR counts (merged). Used both for "favorite repos" and to
+    // back-fill primary languages from `repoScores` entries that overlap.
+    const mergedByRepo = {};
+    for (const pr of merged) {
+        const repo = parseRepo(pr.url);
+        if (!repo)
+            continue;
+        mergedByRepo[repo] = (mergedByRepo[repo] ?? 0) + 1;
+    }
+    const favoriteRepos = topNByCount(mergedByRepo, TOP_N);
+    // Languages: weight a repo's language by that repo's merged count so
+    // `vercel/next.js` (TypeScript) counts more than a one-off PR to a
+    // Lua project even if both repos are in `repoScores`.
+    const languageCounts = {};
+    for (const [repo, count] of Object.entries(mergedByRepo)) {
+        const score = state.repoScores[repo];
+        const lang = score?.language;
+        if (!lang)
+            continue;
+        languageCounts[lang] = (languageCounts[lang] ?? 0) + count;
+    }
+    const primaryLanguages = topNByCount(languageCounts, TOP_N);
+    // PR-type distribution over the recent window.
+    const distribution = {
+        docs: 0,
+        fixes: 0,
+        features: 0,
+        refactors: 0,
+        tests: 0,
+        other: 0,
+    };
+    const cutoff = Date.now() - RECENT_WINDOW_DAYS * 86400000;
+    for (const pr of merged) {
+        const mergedAt = Date.parse(pr.mergedAt);
+        if (Number.isNaN(mergedAt) || mergedAt < cutoff)
+            continue;
+        distribution[classifyTitle(pr.title)] += 1;
+    }
+    // Capacity: read from the last digest. When no digest exists yet,
+    // default to zero (the agent has nothing to recommend without a
+    // digest). The DailyDigest schema does not store a `dormantCount`
+    // directly — derive it from the `waitingOnMaintainerPRs` array,
+    // which is the "PR flagged as awaiting maintainer review" bucket
+    // produced by `pr-monitor`.
+    const summary = state.lastDigest?.summary;
+    const openPRCount = summary?.totalActivePRs ?? 0;
+    const waiting = state.lastDigest?.waitingOnMaintainerPRs ?? [];
+    const dormantPRCount = waiting.length;
+    // Overextended: dormant PRs spread across 2+ repos. Same definition
+    // the issue body uses.
+    const dormantRepos = new Set(waiting
+        .map((pr) => (typeof pr.url === 'string' ? parseRepo(pr.url) : null))
+        .filter((r) => r !== null));
+    const overExtended = dormantPRCount >= 2 && dormantRepos.size >= 2;
+    const profile = {
+        style: determineStyle(totalPRs, primaryLanguages, favoriteRepos),
+        totalPRs,
+        mergedCount: merged.length,
+        mergeRate: totalPRs === 0 ? 0 : merged.length / totalPRs,
+        primaryLanguages,
+        favoriteRepos,
+    };
+    const capacity = {
+        openPRCount,
+        dormantPRCount,
+        dormantRepoCount: dormantRepos.size,
+        overExtended,
+        suggestedAction: recommendForOverExtension(openPRCount, dormantPRCount, overExtended),
+    };
+    const patterns = {
+        prTypeDistribution: distribution,
+        trajectoryDirection: determineTrajectory(state),
+        // Without per-PR diff size in StoredMergedPR, a true "average PR
+        // size" lookup is out of scope until that data is captured (#1243
+        // explicitly defers this). Surface 0 so downstream callers know the
+        // signal is unavailable rather than fabricating a value.
+        averagePRSize: 0,
+    };
+    const recommendations = {
+        // The deterministic recommendations layer reuses the profile
+        // signals — the agent's coaching prose layers on top of these.
+        languages: primaryLanguages,
+        repos: favoriteRepos,
+        issueTypes: deriveIssueTypePreferences(distribution),
+        avoidPatterns: deriveAvoidPatterns(capacity, patterns),
+    };
+    return { profile, capacity, patterns, recommendations };
+}
+/** Cadence trigger thresholds for the auto-display in `/oss` (#1270). */
+export const STRATEGY_CADENCE_DAYS = 30;
+export const STRATEGY_CADENCE_MERGED_DELTA = 5;
+/**
+ * Decide whether a strategy snapshot should be embedded in this daily run.
+ * Returns true when EITHER 30 days have elapsed since the last snapshot OR
+ * 5+ PRs have merged since then, AND the merge floor in
+ * {@link STRATEGY_MIN_PRS} is met. The caller is responsible for calling
+ * {@link computeStrategy} when this returns true and for persisting
+ * `state.lastStrategyAt` after a successful compute.
+ *
+ * `nowIso` is injected so tests can pin time without mocking `Date`.
+ */
+export function shouldComputeStrategy(state, nowIso) {
+    const merged = state.mergedPRs ?? [];
+    if (merged.length < STRATEGY_MIN_PRS)
+        return false;
+    const lastIso = state.lastStrategyAt;
+    if (!lastIso)
+        return true;
+    // Time-based trigger: 30+ days since last snapshot.
+    const lastMs = Date.parse(lastIso);
+    const nowMs = Date.parse(nowIso);
+    if (Number.isFinite(lastMs) && Number.isFinite(nowMs)) {
+        const daysSince = (nowMs - lastMs) / (1000 * 60 * 60 * 24);
+        if (daysSince >= STRATEGY_CADENCE_DAYS)
+            return true;
+    }
+    else {
+        // Unparseable timestamps — fail open and recompute rather than
+        // silently never re-firing. The lastStrategyAt write below will
+        // refresh to a valid ISO string.
+        return true;
+    }
+    // Merge-count trigger: count PRs merged after `lastStrategyAt`.
+    // `mergedAt` is required on StoredMergedPRSchema; `Date.parse` returns
+    // NaN for malformed-but-stored data and Number.isFinite excludes those.
+    const mergedSince = merged.filter((pr) => {
+        const mergedMs = Date.parse(pr.mergedAt);
+        return Number.isFinite(mergedMs) && mergedMs > lastMs;
+    }).length;
+    return mergedSince >= STRATEGY_CADENCE_MERGED_DELTA;
+}
+function deriveIssueTypePreferences(distribution) {
+    // Recommend the user's two strongest PR types — they have a track
+    // record there, so issues in those buckets are higher-yield.
+    const ranked = Object.entries(distribution)
+        .filter(([type]) => type !== 'other')
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 2)
+        .map(([type]) => type);
+    return ranked;
+}
+function deriveAvoidPatterns(capacity, patterns) {
+    const out = [];
+    if (capacity.overExtended) {
+        out.push('opening new PRs while dormant ones await review across multiple repos');
+    }
+    if (patterns.trajectoryDirection === 'declining') {
+        out.push('drifting away from a previously productive cadence — capacity may be saturated');
+    }
+    return out;
+}

package/dist/core/types.d.ts

@@ -19,6 +19,46 @@ export interface ClassifiedCheck {
     category: CIFailureCategory;
     conclusion?: string;
 }
+/**
+ * Mutually exclusive overall-CI categories produced by
+ * {@link categorizeCIStatus} (#1272). The 5-row truth table that lived
+ * as prose in `agents/pr-health-checker.md` — extracted so any consumer
+ * (the agent, the dashboard, future MCP surfaces) reads one typed field
+ * instead of re-deriving the table.
+ *
+ * - `all_passing` — every reported check is green
+ * - `failing` — at least one actionable failure (real test/lint/build
+ *   issue), OR ciStatus reported failing without per-check detail (the
+ *   honest answer when the legacy combined-status endpoint can't tell
+ *   us what failed)
+ * - `fork_limitation` — failures exist but ALL of them are
+ *   `fork_limitation` / `auth_gate` (Vercel preview, internal CI) — purely
+ *   informational
+ * - `blocked` — checks are pending (awaiting trigger / completion), OR
+ *   non-actionable failures include `infrastructure` (cancelled /
+ *   timed-out runner — re-running often resolves)
+ * - `not_running` — no checks reported
+ */
+export type CIStatusCategory = 'all_passing' | 'failing' | 'fork_limitation' | 'blocked' | 'not_running';
+/**
+ * Suggested action for the {@link CIStatusCategorization}. Hint, not
+ * enforcement — the consuming agent may still escalate or skip based on
+ * other PR context.
+ */
+export type CIStatusAction = 'none' | 'investigate' | 'request_rerun' | 'check_workflows' | 'informational';
+/**
+ * Aggregate CI status produced by {@link categorizeCIStatus} (#1272).
+ * Derived from `ciStatus + failingCheckNames + classifiedChecks` —
+ * exposed on {@link FetchedPR} so agents read a single field instead
+ * of re-implementing the truth table.
+ */
+export interface CIStatusCategorization {
+    category: CIStatusCategory;
+    /** Short human-readable summary suitable for inline display. */
+    summary: string;
+    /** Suggested next action (hint, not enforcement). */
+    action: CIStatusAction;
+}
 /** CI status result returned by getCIStatus(). */
 export interface CIStatusResult {
     status: CIStatus;
@@ -115,6 +155,15 @@ export interface FetchedPR {
     failingCheckNames: string[];
     /** Failing checks with category classification (#81). Separates actionable failures from fork limitations and auth gates. */
     classifiedChecks: ClassifiedCheck[];
+    /**
+     * Aggregate 5-state CI categorization (#1272). Derived from `ciStatus`,
+     * `failingCheckNames`, and `classifiedChecks` via `categorizeCIStatus()`
+     * — agents read this directly instead of re-deriving the truth table.
+     * Always populated on a fresh fetch (v2 architecture has no cached
+     * `FetchedPR` to migrate); pr-monitor's `fetchPRDetails` sets it on
+     * every PR before construction.
+     */
+    ciCategorization: CIStatusCategorization;
     hasMergeConflict: boolean;
     reviewDecision: ReviewDecision;
     /** How many commits the PR branch is behind the base branch. */
@@ -207,6 +256,8 @@ interface CommentedIssueBase {
     title: string;
     url: string;
     userLastCommentedAt: string;
+    /** User's most recent comment body, truncated to 200 chars (+ "..." suffix when truncated). #1290 */
+    userLastCommentBody: string;
     labels: string[];
     daysSinceUserComment: number;
 }

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

@@ -0,0 +1,56 @@
+/**
+ * Workflow-state helpers (#1280).
+ *
+ * Centralizes the read/write logic for `state.workflowState`. Used
+ * by `draft-first-workflow.md`, `work-through-issues.md`, and
+ * `pre-commit-review.md` to record pause points and offer
+ * Resume / Restart / Discard at the next `/oss` invocation.
+ *
+ * Pure functions — callers manage state I/O. Same architectural
+ * shape as the recent #1277 (follow-up-history) helpers.
+ */
+import type { AgentState, WorkflowState } from './state-schema.js';
+export type WorkflowName = WorkflowState['workflowName'];
+/**
+ * Snapshot the user's current workflow position. Returns the
+ * patched state; callers persist via `StateManager.save()` (or the
+ * gist `checkpoint()` path).
+ */
+export declare function recordWorkflowPause(state: AgentState, next: Omit<WorkflowState, 'lastUpdatedAt'>, now?: Date): AgentState;
+/**
+ * Read the current workflow snapshot, or null when no pause is
+ * recorded.
+ */
+export declare function getWorkflowState(state: AgentState): WorkflowState | null;
+/**
+ * Discard the current pause snapshot. Used by:
+ *  - the workflow completing normally,
+ *  - the user picking "Discard and start fresh" at the resume
+ *    prompt,
+ *  - any consumer that detects the snapshot has gone stale (branch
+ *    deleted, repo no longer reachable).
+ */
+export declare function clearWorkflowState(state: AgentState): AgentState;
+/**
+ * Append a step name to `completedSteps` and update `currentStep`
+ * to the supplied next step. Convenience wrapper around the immer-
+ * style read/replace pattern. Returns the patched state.
+ */
+export declare function advanceWorkflowStep(state: AgentState, nextStep: string, now?: Date): AgentState;
+/**
+ * Merge per-step data into `stepData` without overwriting other
+ * keys. Useful when a workflow's resume needs to restore non-trivial
+ * context (skipped compliance items, last review pass count, etc.).
+ */
+export declare function setStepData(state: AgentState, step: string, data: unknown, now?: Date): AgentState;
+/**
+ * Read step data for a specific step, or undefined when none was
+ * stored. Callers typically narrow the unknown via a type guard.
+ */
+export declare function getStepData(state: AgentState, step: string): unknown;
+/**
+ * Whether the recorded pause is on the supplied workflow. Useful
+ * for the router to decide whether to offer Resume vs ignore the
+ * snapshot when the current `/oss` invocation is unrelated.
+ */
+export declare function isPausedIn(state: AgentState, workflowName: WorkflowName): boolean;