@oss-autopilot/core 3.4.1 → 3.6.0

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

@@ -0,0 +1,21 @@
+/**
+ * repo-vet command (#1271, follow-up to #1242).
+ *
+ * Fetches repo health signals via the GitHub API, runs the typed
+ * `computeRepoVet` core function, and returns the structured result.
+ * Used by the `repo-evaluator` agent (and the future `repo-vet` MCP tool)
+ * to replace per-prompt rubric assembly with a deterministic, testable
+ * evaluation.
+ *
+ * Same architectural shape as `compliance-score`: read-only API calls,
+ * no state mutation, runs against a public `owner/repo` slug.
+ */
+import type { RepoVetOutput } from '../formatters/json.js';
+/**
+ * Run the repo-vet evaluation against an `owner/repo` slug.
+ *
+ * @throws {ValidationError} If the repo identifier is malformed.
+ */
+export declare function runRepoVet(options: {
+    repo: string;
+}): Promise<RepoVetOutput>;

package/dist/commands/repo-vet.js

@@ -0,0 +1,215 @@
+/**
+ * repo-vet command (#1271, follow-up to #1242).
+ *
+ * Fetches repo health signals via the GitHub API, runs the typed
+ * `computeRepoVet` core function, and returns the structured result.
+ * Used by the `repo-evaluator` agent (and the future `repo-vet` MCP tool)
+ * to replace per-prompt rubric assembly with a deterministic, testable
+ * evaluation.
+ *
+ * Same architectural shape as `compliance-score`: read-only API calls,
+ * no state mutation, runs against a public `owner/repo` slug.
+ */
+import { getOctokit, requireGitHubToken } from '../core/index.js';
+import { errorMessage } from '../core/errors.js';
+import { warn } from '../core/logger.js';
+import { validateRepoIdentifier } from './validation.js';
+import { computeRepoVet } from '../core/repo-vet.js';
+const MODULE = 'repo-vet';
+const DAY_MS = 86400000;
+const COMMUNITY_HEALTH_PATHS = [
+    // Each entry can live at the repo root OR under .github/. We probe both
+    // because some repos prefer the visible-at-root convention and some
+    // prefer the .github/ folder convention.
+    { key: 'hasContributing', candidates: ['CONTRIBUTING.md', '.github/CONTRIBUTING.md'] },
+    { key: 'hasIssueTemplates', candidates: ['.github/ISSUE_TEMPLATE'] },
+    {
+        key: 'hasPRTemplate',
+        candidates: ['.github/pull_request_template.md', 'pull_request_template.md', 'PULL_REQUEST_TEMPLATE.md'],
+    },
+    { key: 'hasCodeOfConduct', candidates: ['CODE_OF_CONDUCT.md', '.github/CODE_OF_CONDUCT.md'] },
+];
+/**
+ * Returns true when the path exists. Treats 404 as "absent" (the only
+ * shape we care about for community-health flags). Re-throws everything
+ * else — auth/rate-limit failures must not silently scrub the
+ * `hasContributing` etc. flags to `false`, which would understate a
+ * repo's community health on a token that lacks scope or has been
+ * throttled mid-sequence.
+ */
+async function probePath(octokit, owner, repo, path) {
+    try {
+        await octokit.repos.getContent({ owner, repo, path });
+        return true;
+    }
+    catch (err) {
+        const status = err.status;
+        if (status === 404)
+            return false;
+        throw err;
+    }
+}
+/**
+ * Probe each community-health path. Treats 404 as "absent" (a definitive
+ * signal). On any other error (auth, rate-limit, 5xx) the per-key result
+ * stays `false` AND the whole-function `incomplete` flag is set so the
+ * caller knows community-health was unverified rather than confirmed-absent.
+ *
+ * This is the per-key analogue of the call-level catch: instead of either
+ * silently misclassifying 403 → absent OR aborting the entire repo-vet
+ * call, we degrade gracefully and surface the gap.
+ */
+async function checkCommunityHealth(octokit, owner, repo) {
+    const out = {
+        hasContributing: false,
+        hasIssueTemplates: false,
+        hasPRTemplate: false,
+        hasCodeOfConduct: false,
+    };
+    let incomplete = false;
+    await Promise.all(COMMUNITY_HEALTH_PATHS.map(async ({ key, candidates }) => {
+        let sawError = false;
+        for (const path of candidates) {
+            try {
+                if (await probePath(octokit, owner, repo, path)) {
+                    out[key] = true;
+                    return;
+                }
+            }
+            catch (err) {
+                // probePath only throws on non-404 errors. Don't abandon
+                // remaining candidates — `CONTRIBUTING.md` failing with 403
+                // does NOT imply `.github/CONTRIBUTING.md` will fail too. Mark
+                // the per-key probe as incomplete only if every candidate
+                // either errored or returned absent.
+                warn(MODULE, `community-health probe for ${owner}/${repo}/${path} failed: ${errorMessage(err)}`);
+                sawError = true;
+                continue;
+            }
+        }
+        // Reached only when no candidate hit. If any candidate errored,
+        // the absent flag is unreliable — surface that to the caller so
+        // the agent prompt distinguishes "probed all candidates and
+        // absent" from "couldn't tell".
+        if (sawError)
+            incomplete = true;
+    }));
+    return {
+        hasContributing: out.hasContributing,
+        hasIssueTemplates: out.hasIssueTemplates,
+        hasPRTemplate: out.hasPRTemplate,
+        hasCodeOfConduct: out.hasCodeOfConduct,
+        incomplete,
+    };
+}
+function summarizePRMerges(prs, windowDays, now) {
+    const cutoff = now.getTime() - windowDays * DAY_MS;
+    const prMergeTimesDays = [];
+    let mergedCount = 0;
+    let openedCount = 0;
+    for (const pr of prs) {
+        const createdAt = new Date(pr.created_at).getTime();
+        if (createdAt >= cutoff)
+            openedCount += 1;
+        if (pr.merged_at) {
+            const mergedAt = new Date(pr.merged_at).getTime();
+            if (mergedAt >= cutoff) {
+                mergedCount += 1;
+                const days = (mergedAt - createdAt) / DAY_MS;
+                if (Number.isFinite(days) && days >= 0)
+                    prMergeTimesDays.push(days);
+            }
+        }
+    }
+    return { prMergeTimesDays, mergedCount, openedCount };
+}
+function summarizeCommits(commits, now) {
+    const cutoff30 = now.getTime() - 30 * DAY_MS;
+    const cutoff90 = now.getTime() - 90 * DAY_MS;
+    const contributors90 = new Set();
+    let commitsLast30Days = 0;
+    let lastCommitMs = null;
+    for (const c of commits) {
+        const dateStr = c.commit.author?.date;
+        if (!dateStr)
+            continue;
+        const ts = new Date(dateStr).getTime();
+        if (Number.isNaN(ts))
+            continue;
+        if (lastCommitMs === null || ts > lastCommitMs)
+            lastCommitMs = ts;
+        if (ts >= cutoff30)
+            commitsLast30Days += 1;
+        if (ts >= cutoff90 && c.author?.login)
+            contributors90.add(c.author.login);
+    }
+    return {
+        commitsLast30Days,
+        contributorsLast90d: contributors90.size,
+        lastCommitISO: lastCommitMs ? new Date(lastCommitMs).toISOString() : null,
+    };
+}
+/**
+ * Run the repo-vet evaluation against an `owner/repo` slug.
+ *
+ * @throws {ValidationError} If the repo identifier is malformed.
+ */
+export async function runRepoVet(options) {
+    validateRepoIdentifier(options.repo);
+    const [owner, repo] = options.repo.split('/');
+    const token = requireGitHubToken();
+    const octokit = getOctokit(token);
+    const now = new Date();
+    const [repoMetaResp, closedPRsResp, commitsResp, releasesResp, communityHealthSummary] = await Promise.all([
+        octokit.repos.get({ owner, repo }),
+        octokit.pulls.list({ owner, repo, state: 'closed', sort: 'updated', direction: 'desc', per_page: 100 }),
+        octokit.repos.listCommits({ owner, repo, per_page: 100 }),
+        octokit.repos
+            .listReleases({ owner, repo, per_page: 1 })
+            .catch(() => ({ data: [] })),
+        checkCommunityHealth(octokit, owner, repo),
+    ]);
+    const prs = closedPRsResp.data.map((p) => ({
+        created_at: p.created_at,
+        merged_at: p.merged_at,
+        updated_at: p.updated_at,
+    }));
+    const { prMergeTimesDays, mergedCount, openedCount } = summarizePRMerges(prs, 90, now);
+    const commitSummary = summarizeCommits(commitsResp.data, now);
+    const releases = releasesResp.data;
+    const lastReleaseISO = releases.length > 0 ? (releases[0].published_at ?? releases[0].created_at ?? null) : null;
+    const input = {
+        stars: repoMetaResp.data.stargazers_count ?? 0,
+        forks: repoMetaResp.data.forks_count ?? 0,
+        openIssues: repoMetaResp.data.open_issues_count ?? 0,
+        watchers: repoMetaResp.data.subscribers_count ?? 0,
+        isArchived: repoMetaResp.data.archived ?? false,
+        lastPushed: repoMetaResp.data.pushed_at ?? new Date(0).toISOString(),
+        createdAt: repoMetaResp.data.created_at ?? new Date(0).toISOString(),
+        commitsLast30Days: commitSummary.commitsLast30Days,
+        prMergeTimesDays,
+        mergedCount90Days: mergedCount,
+        openedCount90Days: openedCount,
+        lastCommitISO: commitSummary.lastCommitISO,
+        contributorsLast90d: commitSummary.contributorsLast90d,
+        lastReleaseISO,
+        hasContributing: communityHealthSummary.hasContributing,
+        hasIssueTemplates: communityHealthSummary.hasIssueTemplates,
+        hasPRTemplate: communityHealthSummary.hasPRTemplate,
+        hasCodeOfConduct: communityHealthSummary.hasCodeOfConduct,
+    };
+    const result = computeRepoVet(input);
+    // The core function names its metadata object `repo`. Rename to `repoMeta`
+    // at the CLI boundary so the top-level slug doesn't collide with it.
+    // Also overlay the community-health `incomplete` flag the wrapper
+    // tracks (the core type doesn't carry it because computeRepoVet is
+    // pure — only the wrapper makes the API calls that can fail mid-probe).
+    const { repo: repoMeta, communityHealth, ...rest } = result;
+    return {
+        repoSlug: options.repo,
+        fetchedAt: now.toISOString(),
+        repoMeta,
+        communityHealth: { ...communityHealth, incomplete: communityHealthSummary.incomplete },
+        ...rest,
+    };
+}

package/dist/commands/startup.js

@@ -115,11 +115,33 @@ export function detectIssueList() {
         // Matches the sibling warn at line 64 for `issueListPath` read failures.
         warn('startup', `Could not read skippedIssuesPath from state: ${errorMessage(err)}`);
     }
-    // Probe default path: same directory as issue list, named skipped-issues.md
+    // Probe default path: same directory as issue list, named skipped-issues.md.
+    // When found, also persist to state.config so downstream commands
+    // (`skip-add`, `scout search`'s skip-list filter) read the same path
+    // instead of silently no-opping with "No skipped-issues path configured"
+    // (#1330). Without persistence, the auto-detect printed the path on
+    // every startup but nothing else honored it — search would re-surface
+    // already-skipped candidates round after round.
     if (!skippedIssuesPath && issueListPath) {
         const defaultSkipPath = path.join(path.dirname(issueListPath), 'skipped-issues.md');
         if (fs.existsSync(defaultSkipPath)) {
             skippedIssuesPath = defaultSkipPath;
+            try {
+                const stateManager = getStateManager();
+                // Only write when config actually doesn't have one — re-running
+                // startup shouldn't trigger an autoSave on every run if the
+                // value is already there.
+                const current = stateManager.getState().config.skippedIssuesPath;
+                if (!current) {
+                    stateManager.updateConfig({ skippedIssuesPath: defaultSkipPath });
+                }
+            }
+            catch (err) {
+                // Persistence is best-effort — startup still surfaces the path
+                // in its return value so the current run benefits, but the next
+                // run won't. Log so the failure is debuggable.
+                warn('startup', `Could not persist auto-detected skippedIssuesPath: ${errorMessage(err)}`);
+            }
         }
     }
     return { path: issueListPath, source, availableCount, completedCount, skippedIssuesPath };
@@ -277,6 +299,22 @@ export async function runStartup() {
     }
     // 5. Detect issue list
     const issueList = detectIssueList();
+    // 6. Pass through dashboard-build status set by the workflow shell (#1293).
+    // The workflow runs the SPA build BEFORE invoking startup, so the status
+    // arrives here via env vars rather than being something runStartup itself
+    // computes. Validate the env value so a malformed export can't sneak an
+    // arbitrary string into a typed enum.
+    const rawBuildStatus = process.env.OSS_DASHBOARD_BUILD_STATUS;
+    const dashboardBuildStatus = rawBuildStatus === 'fresh' ||
+        rawBuildStatus === 'rebuilt' ||
+        rawBuildStatus === 'failed' ||
+        rawBuildStatus === 'missing-pnpm'
+        ? rawBuildStatus
+        : undefined;
+    const rawBuildErrorTail = process.env.OSS_DASHBOARD_BUILD_ERROR_TAIL;
+    const dashboardBuildErrorTail = (dashboardBuildStatus === 'failed' || dashboardBuildStatus === 'missing-pnpm') && rawBuildErrorTail
+        ? rawBuildErrorTail
+        : undefined;
     return {
         version,
         setupComplete: true,
@@ -284,6 +322,8 @@ export async function runStartup() {
         daily,
         dashboardUrl,
         dashboardError,
+        dashboardBuildStatus,
+        dashboardBuildErrorTail,
         issueList,
     };
 }

package/dist/core/anti-llm-policy.d.ts

@@ -1,26 +1,35 @@
 /**
- * Anti-LLM policy scan (#108, #911, #979).
+ * AI/LLM policy scans (#108, #911, #979, #1269).
  *
- * Scan concatenated repo docs (CONTRIBUTING.md, CODE_OF_CONDUCT.md,
- * README) for language that indicates the project does not accept
- * AI/LLM-generated contributions. Previously described as a keyword
- * table in prose in agents/issue-scout.md.
+ * Two complementary scanners over the same input (concatenated repo docs
+ * — CONTRIBUTING.md, CODE_OF_CONDUCT.md, README, etc.):
+ *
+ * 1. {@link scanForAntiLLMPolicy} — detects language indicating the
+ *    project does NOT accept AI/LLM-generated contributions. Used by
+ *    issue-scout / repo-evaluator to filter out repos where landing a
+ *    PR is impossible.
+ *
+ * 2. {@link scanAIDisclosureRequirement} — detects the opposite:
+ *    language requiring or inviting AI disclosure ("must disclose AI
+ *    use", "credit AI tools"). Used by pr-compliance-checker to decide
+ *    whether AI attribution should be flagged as a violation, encouraged,
+ *    or required (#1269 Improvement C).
  *
  * The long-term home for this logic is `@oss-scout/core`, where the
  * relevant files are already fetched during vetting. Keeping it here
  * for now lets the agent invoke it directly and gives scout a
  * reference implementation + test fixtures to adopt. See #979.
  *
- * Precision matters more than recall. False positives (flagging a
- * project that actually welcomes AI help) silently shrink the user's
- * contribution surface without recourse. We only match on phrases
- * that combine a rejection keyword (no / reject / will be closed /
- * don't accept) with an AI/LLM noun.
+ * Precision matters more than recall in both directions. A false
+ * positive on the anti-LLM side silently shrinks the user's
+ * contribution surface; a false positive on the disclosure side tells
+ * the user to add attribution that the maintainer didn't actually ask
+ * for. Patterns require an explicit verb-phrase + AI/LLM-noun pairing.
  *
  * **User-facing reference:** `docs/anti-llm-policy.md` — explains the
- * three categories, example phrases per category, and the false-positive-
- * resistance design (why "AI division will be closed at end of Q4"
- * does NOT match).
+ * three anti-LLM categories, example phrases per category, and the
+ * false-positive-resistance design (why "AI division will be closed at
+ * end of Q4" does NOT match).
  */
 export type AntiLLMCategory = 'explicit_ban' | 'tool_ban' | 'reject_framing';
 export interface AntiLLMMatch {
@@ -35,3 +44,23 @@ export interface AntiLLMScanResult {
     matches: AntiLLMMatch[];
 }
 export declare function scanForAntiLLMPolicy(text: string): AntiLLMScanResult;
+export type AIDisclosureCategory = 'mandatory' | 'recommended' | 'invited';
+export interface AIDisclosureMatch {
+    category: AIDisclosureCategory;
+    phrase: string;
+    excerpt: string;
+}
+export interface AIDisclosureScanResult {
+    matched: boolean;
+    matches: AIDisclosureMatch[];
+}
+/**
+ * Scan repo docs for language requiring or inviting AI disclosure (#1269).
+ *
+ * Mirrors {@link scanForAntiLLMPolicy}'s shape: same input contract,
+ * same false-positive-resistance discipline, same per-match excerpt for
+ * surfacing to the user. Categories are ordered by binding strength —
+ * callers that want to avoid false-positive flagging on weak invitations
+ * can filter to 'mandatory' / 'recommended' only.
+ */
+export declare function scanAIDisclosureRequirement(text: string): AIDisclosureScanResult;

package/dist/core/anti-llm-policy.js

@@ -1,26 +1,35 @@
 /**
- * Anti-LLM policy scan (#108, #911, #979).
+ * AI/LLM policy scans (#108, #911, #979, #1269).
  *
- * Scan concatenated repo docs (CONTRIBUTING.md, CODE_OF_CONDUCT.md,
- * README) for language that indicates the project does not accept
- * AI/LLM-generated contributions. Previously described as a keyword
- * table in prose in agents/issue-scout.md.
+ * Two complementary scanners over the same input (concatenated repo docs
+ * — CONTRIBUTING.md, CODE_OF_CONDUCT.md, README, etc.):
+ *
+ * 1. {@link scanForAntiLLMPolicy} — detects language indicating the
+ *    project does NOT accept AI/LLM-generated contributions. Used by
+ *    issue-scout / repo-evaluator to filter out repos where landing a
+ *    PR is impossible.
+ *
+ * 2. {@link scanAIDisclosureRequirement} — detects the opposite:
+ *    language requiring or inviting AI disclosure ("must disclose AI
+ *    use", "credit AI tools"). Used by pr-compliance-checker to decide
+ *    whether AI attribution should be flagged as a violation, encouraged,
+ *    or required (#1269 Improvement C).
  *
  * The long-term home for this logic is `@oss-scout/core`, where the
  * relevant files are already fetched during vetting. Keeping it here
  * for now lets the agent invoke it directly and gives scout a
  * reference implementation + test fixtures to adopt. See #979.
  *
- * Precision matters more than recall. False positives (flagging a
- * project that actually welcomes AI help) silently shrink the user's
- * contribution surface without recourse. We only match on phrases
- * that combine a rejection keyword (no / reject / will be closed /
- * don't accept) with an AI/LLM noun.
+ * Precision matters more than recall in both directions. A false
+ * positive on the anti-LLM side silently shrinks the user's
+ * contribution surface; a false positive on the disclosure side tells
+ * the user to add attribution that the maintainer didn't actually ask
+ * for. Patterns require an explicit verb-phrase + AI/LLM-noun pairing.
  *
  * **User-facing reference:** `docs/anti-llm-policy.md` — explains the
- * three categories, example phrases per category, and the false-positive-
- * resistance design (why "AI division will be closed at end of Q4"
- * does NOT match).
+ * three anti-LLM categories, example phrases per category, and the
+ * false-positive-resistance design (why "AI division will be closed at
+ * end of Q4" does NOT match).
  */
 const PATTERNS = [
     // Explicit "no X" bans against AI/LLM nouns.
@@ -104,3 +113,83 @@ export function scanForAntiLLMPolicy(text) {
     }
     return { matched: matches.length > 0, matches };
 }
+const DISCLOSURE_PATTERNS = [
+    // Mandatory: imperative verbs binding to an AI/LLM disclosure noun.
+    // Match shape: <verb-phrase> <AI noun> <disclosure noun>?
+    // Verb phrases: "must disclose", "required to disclose", "are required
+    // to indicate", "you must indicate". The optional disclosure-action
+    // noun catches "must disclose use of AI" without requiring a separate
+    // pattern. The AI noun can be plain "ai/llm" or a tool name.
+    {
+        category: 'mandatory',
+        regex: /\b(must|required\s+to|are\s+required\s+to)\s+(disclose|indicate|declare|note|state|mention|label|tag|credit|acknowledge)\s+(?:[a-z\s'-]{0,40}?\b)?(ai|llm|generative\s+ai|copilot|chatgpt|claude|cursor)\b/i,
+    },
+    // "PRs using AI must be labeled / tagged / disclosed"
+    {
+        category: 'mandatory',
+        regex: /\b(prs?|contributions?|commits?|code)\s+(using|generated\s+by|written\s+by|made\s+with)\s+(ai|llm|copilot|chatgpt|claude|cursor)\s+(?:tools?\s+)?(must\s+be|need\s+to\s+be|are\s+to\s+be)\s+(labeled|tagged|disclosed|marked|flagged|noted)\b/i,
+    },
+    // "Disclosure of AI assistance is required" — passive form
+    {
+        category: 'mandatory',
+        regex: /\b(disclosure|disclosing|labeling|labelling|tagging|crediting)\s+(of\s+)?(ai|llm|copilot|chatgpt|claude|cursor)(\s+(use|usage|assistance|tools?|contributions?|generated\s+code))?\s+(is\s+required|is\s+mandatory|must\s+be\s+included)\b/i,
+    },
+    // Recommended: softer "should" or "we ask" framing. Same noun anchors.
+    // Verb forms allow optional gerund (-ing) endings since "we strongly
+    // encourage acknowledging AI" reads naturally even though "acknowledge"
+    // is the bare verb in the imperative list.
+    {
+        category: 'recommended',
+        regex: /\b(should|we\s+ask\s+you\s+to|we\s+ask\s+that\s+you|we\s+(?:strongly\s+)?(?:encourage|recommend))\s+(disclose|disclosing|indicate|indicating|declare|declaring|note|noting|mention|mentioning|label|labeling|labelling|tag|tagging|credit|crediting|acknowledge|acknowledging)\s+(?:[a-z\s'-]{0,40}?\b)?(ai|llm|generative\s+ai|copilot|chatgpt|claude|cursor)\b/i,
+    },
+    // "credit AI tools you used" — direct imperative without "must/should"
+    {
+        category: 'recommended',
+        regex: /\b(credit|acknowledge|attribute)\s+(ai|llm|generative\s+ai)\s+(tools?|assistants?|use|usage|assistance)\b/i,
+    },
+    // Invited: permissive framing. Lower confidence.
+    // The "please" branch is dropped intentionally — bare "please mention X"
+    // doesn't carry enough policy weight on its own, and including it as
+    // `please\s+(?:feel\s+free\s+to)?\s+` introduces super-linear backtracking
+    // (regexp/no-super-linear-backtracking) because of the ambiguous \s+
+    // boundary on either side of the optional group.
+    {
+        category: 'invited',
+        regex: /\b(feel\s+free\s+to|please\s+feel\s+free\s+to|you('re|\s+are)\s+welcome\s+to|welcome\s+to)\s+(disclose|mention|note|indicate|label|tag|credit)\s+(?:[a-z\s'-]{0,40}?\b)?(ai|llm|generative\s+ai|copilot|chatgpt|claude|cursor)\b/i,
+    },
+];
+/**
+ * Scan repo docs for language requiring or inviting AI disclosure (#1269).
+ *
+ * Mirrors {@link scanForAntiLLMPolicy}'s shape: same input contract,
+ * same false-positive-resistance discipline, same per-match excerpt for
+ * surfacing to the user. Categories are ordered by binding strength —
+ * callers that want to avoid false-positive flagging on weak invitations
+ * can filter to 'mandatory' / 'recommended' only.
+ */
+export function scanAIDisclosureRequirement(text) {
+    if (typeof text !== 'string') {
+        throw new TypeError(`scanAIDisclosureRequirement: expected string, received ${typeof text}`);
+    }
+    if (text === '')
+        return { matched: false, matches: [] };
+    const normalized = normalizeText(text);
+    const seenLabels = new Set();
+    const matches = [];
+    for (const pattern of DISCLOSURE_PATTERNS) {
+        const hit = normalized.match(pattern.regex);
+        if (!hit || hit.index === undefined)
+            continue;
+        const phrase = hit[0];
+        const key = `${pattern.category}:${phrase.toLowerCase()}`;
+        if (seenLabels.has(key))
+            continue;
+        seenLabels.add(key);
+        matches.push({
+            category: pattern.category,
+            phrase,
+            excerpt: makeExcerpt(normalized, hit.index, phrase.length),
+        });
+    }
+    return { matched: matches.length > 0, matches };
+}

package/dist/core/ci-analysis.d.ts

@@ -3,7 +3,7 @@
  * Extracted from PRMonitor to isolate CI-related logic (#263).
  */
 import type { Octokit } from '@octokit/rest';
-import { CIFailureCategory, ClassifiedCheck, CIStatusResult } from './types.js';
+import { CIFailureCategory, ClassifiedCheck, CIStatusResult, CIStatus, CIStatusCategorization } from './types.js';
 /**
  * Classify a failing CI check as actionable, fork_limitation, auth_gate, or infrastructure (#81, #145, #743).
  * Default is 'actionable' — only known patterns get reclassified.
@@ -16,6 +16,37 @@ export declare function classifyCICheck(name: string, description?: string, conc
  * Accepts optional conclusion data to detect infrastructure failures and auth gates.
  */
 export declare function classifyFailingChecks(failingCheckNames: string[], conclusions?: Map<string, string>): ClassifiedCheck[];
+/**
+ * Map an aggregate `ciStatus + failingCheckNames + classifiedChecks` triple
+ * into one of five mutually exclusive overall states (#1272). The 5-row
+ * truth table previously lived as prose in `agents/pr-health-checker.md`;
+ * extracting it lets that agent (and any future consumer — dashboard,
+ * MCP, sibling agents that adopt the field) read a single typed value
+ * instead of re-deriving from `ciStatus + failingCheckNames + classifiedChecks`.
+ *
+ * Decision order (each branch is exclusive):
+ *   1. `passing`                      → `all_passing`
+ *   2. `pending`                      → `blocked` (awaiting trigger / completion)
+ *   3. `failing` + actionable         → `failing` (real test/lint/build issue)
+ *   4. `failing` + only infrastructure → `blocked` (cancelled/timed-out runner — needs rerun)
+ *   5. `failing` + only fork/auth     → `fork_limitation` (informational)
+ *   6. `failing` + zero classified    → `failing` w/ "details unavailable" summary
+ *   7. `unknown`                      → `not_running`
+ *
+ * Why infrastructure routes to `blocked` and not `fork_limitation`:
+ * a cancelled or timed-out runner is genuinely worth re-running; calling
+ * it "informational" would tell the agent to ignore something the user
+ * can fix with a rerun-request.
+ *
+ * The `summary` is short (≤180 char even for 10+ failing checks) and
+ * suitable for inline display. `action` is a hint, not enforcement —
+ * agents may still escalate based on other PR context.
+ */
+export declare function categorizeCIStatus(input: {
+    ciStatus: CIStatus;
+    failingCheckNames: string[];
+    classifiedChecks: ClassifiedCheck[];
+}): CIStatusCategorization;
 /**
  * Analyze check runs (GitHub Actions, etc.) and categorize them.
  * Returns flags for failing/pending/success and lists of failing check names + conclusions.

package/dist/core/ci-analysis.js

@@ -92,6 +92,98 @@ export function classifyFailingChecks(failingCheckNames, conclusions) {
         };
     });
 }
+/**
+ * Map an aggregate `ciStatus + failingCheckNames + classifiedChecks` triple
+ * into one of five mutually exclusive overall states (#1272). The 5-row
+ * truth table previously lived as prose in `agents/pr-health-checker.md`;
+ * extracting it lets that agent (and any future consumer — dashboard,
+ * MCP, sibling agents that adopt the field) read a single typed value
+ * instead of re-deriving from `ciStatus + failingCheckNames + classifiedChecks`.
+ *
+ * Decision order (each branch is exclusive):
+ *   1. `passing`                      → `all_passing`
+ *   2. `pending`                      → `blocked` (awaiting trigger / completion)
+ *   3. `failing` + actionable         → `failing` (real test/lint/build issue)
+ *   4. `failing` + only infrastructure → `blocked` (cancelled/timed-out runner — needs rerun)
+ *   5. `failing` + only fork/auth     → `fork_limitation` (informational)
+ *   6. `failing` + zero classified    → `failing` w/ "details unavailable" summary
+ *   7. `unknown`                      → `not_running`
+ *
+ * Why infrastructure routes to `blocked` and not `fork_limitation`:
+ * a cancelled or timed-out runner is genuinely worth re-running; calling
+ * it "informational" would tell the agent to ignore something the user
+ * can fix with a rerun-request.
+ *
+ * The `summary` is short (≤180 char even for 10+ failing checks) and
+ * suitable for inline display. `action` is a hint, not enforcement —
+ * agents may still escalate based on other PR context.
+ */
+export function categorizeCIStatus(input) {
+    const { ciStatus, failingCheckNames, classifiedChecks } = input;
+    if (ciStatus === 'passing') {
+        return { category: 'all_passing', summary: 'All checks passing', action: 'none' };
+    }
+    if (ciStatus === 'pending') {
+        // `mergeStatuses` currently sets `failingCheckNames: []` on pending,
+        // so the count branch is defensive — kept so a future caller that
+        // forwards pending names doesn't silently drop them.
+        const count = failingCheckNames.length;
+        const summary = count > 0 ? `${count} pending check(s); CI run incomplete` : 'CI checks pending';
+        return { category: 'blocked', summary, action: 'request_rerun' };
+    }
+    if (ciStatus === 'failing') {
+        const actionable = classifiedChecks.filter((c) => c.category === 'actionable');
+        if (actionable.length > 0) {
+            const preview = actionable
+                .slice(0, 3)
+                .map((c) => c.name)
+                .join(', ');
+            const more = actionable.length > 3 ? ` (+${actionable.length - 3} more)` : '';
+            return {
+                category: 'failing',
+                summary: `${actionable.length} actionable failure(s): ${preview}${more}`,
+                action: 'investigate',
+            };
+        }
+        // No actionable failures. Distinguish three sub-cases:
+        // (a) failing with zero classified checks: status came from the
+        //     legacy combined-status endpoint without per-check detail. Be
+        //     honest about the missing detail rather than asserting "fork
+        //     limitations" the caller can't verify.
+        if (classifiedChecks.length === 0) {
+            return {
+                category: 'failing',
+                summary: 'CI reported failure but no check details available',
+                action: 'investigate',
+            };
+        }
+        // (b) at least one infrastructure failure (cancelled / timed-out /
+        //     dependency-install). Re-running often fixes the issue, so
+        //     surface as `blocked` with `request_rerun` rather than
+        //     mislabeling as "fork limits / auth gates."
+        const hasInfrastructure = classifiedChecks.some((c) => c.category === 'infrastructure');
+        if (hasInfrastructure) {
+            const total = classifiedChecks.length;
+            return {
+                category: 'blocked',
+                summary: `${total} non-actionable failure(s) including infrastructure issues; rerun may resolve`,
+                action: 'request_rerun',
+            };
+        }
+        // (c) only fork-limitation / auth-gate failures — purely informational.
+        const total = classifiedChecks.length;
+        return {
+            category: 'fork_limitation',
+            summary: `${total} non-actionable failure(s) (fork limits / auth gates)`,
+            action: 'informational',
+        };
+    }
+    // ciStatus === 'unknown' — no checks reported, or status couldn't be
+    // determined. Treat both as not_running so callers don't have to
+    // distinguish the rare indeterminate case from the common "no CI
+    // configured" case.
+    return { category: 'not_running', summary: 'No CI checks reported', action: 'check_workflows' };
+}
 /**
  * Analyze check runs (GitHub Actions, etc.) and categorize them.
  * Returns flags for failing/pending/success and lists of failing check names + conclusions.