@reneturcios/greenlight 0.0.0-stage → 0.3.2

package/dist/friction-index.js

@@ -0,0 +1,152 @@
+/**
+ * Friction index generator: `npm run index`.
+ *
+ * Builds data/friction-index.json for the repos we hand-vetted on
+ * 2026-10-13. For each repo it tries the live CONTRIBUTING.md parse first;
+ * when the API is unreachable or rate-limited it falls back to the
+ * hand-verified gate list below and labels the entry accordingly.
+ *
+ * Rule: fields we cannot compute live stay null with a note. We never
+ * fabricate numbers.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseGates, hardGates } from "./gates.js";
+import { scoreFriction } from "./friction.js";
+import { fetchContributing } from "./github.js";
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+function gate(kind, evidence) {
+    return { kind, detected: true, evidence };
+}
+const HAND = [
+    {
+        owner: "PrefectHQ", repo: "fastmcp",
+        gates: [gate("assignment_required", "hand-verified 2026-10-13: issue must be assigned or carry a 'prs welcome' label (PrefectHQ/fastmcp PR #4557)")],
+        note: "hand-verified 2026-10-13",
+    },
+    {
+        owner: "modelcontextprotocol", repo: "inspector",
+        gates: [gate("collaborators_only", "hand-verified 2026-10-15: AGENTS.md states PRs are opened by repo maintainers only; outsiders file detailed issues (verified while working #2723)")],
+        note: "hand-verified 2026-10-15",
+    },
+    {
+        owner: "modelcontextprotocol", repo: "servers",
+        gates: [gate("collaborators_only", "hand-verified 2026-10-15: CONTRIBUTING.md states 'We accept issues, not pull requests'; outsiders share the prompt behind a local fix (verified while working #5153)")],
+        note: "hand-verified 2026-10-15",
+    },
+    {
+        owner: "triggerdotdev", repo: "trigger.dev",
+        gates: [gate("vouch_required", "hand-verified 2026-10-13: unvouched-author PRs auto-closed; vouch-request issue required first")],
+        note: "hand-verified 2026-10-13",
+    },
+    {
+        owner: "langchain-ai", repo: "langchain",
+        gates: [],
+        note: "hand-verified 2026-10-13: no codified gate found, but reporters routinely request assignment before coding",
+    },
+    {
+        owner: "langchain-ai", repo: "deepagents",
+        gates: [],
+        note: "hand-verified 2026-10-13: no codified gate found; assignment-request culture in comments",
+    },
+    {
+        owner: "openclaw", repo: "openclaw",
+        gates: [],
+        note: "hand-verified 2026-10-13: heavy bot triage (ClawSweeper) is advisory only; no hard pre-PR gate",
+    },
+    {
+        owner: "batrapulkit", repo: "squidbrake",
+        gates: [gate("claim_first", "hand-verified 2026-10-14: maintainer asks contributors to comment to claim before starting")],
+        note: "hand-verified 2026-10-13",
+    },
+    {
+        owner: "reticlehq", repo: "reticle",
+        gates: [],
+        note: "hand-verified 2026-10-13: PR policy 'all', no pre-PR gate",
+    },
+    {
+        owner: "shadcn-labs", repo: "pdfcn",
+        gates: [],
+        note: "hand-verified 2026-10-13: no formal gate, but good-first-issues are claimed within hours (claim speed is the game)",
+    },
+    {
+        owner: "GustavoBaranda", repo: "chatflow-agent",
+        gates: [],
+        note: "hand-verified 2026-10-13: no pre-PR gate observed",
+    },
+    {
+        owner: "modelcontextprotocol", repo: "typescript-sdk",
+        gates: [gate("assignment_required", "hand-verified 2026-10-13: SDKs expect a linked assigned or 'help wanted' issue, or an assignment comment")],
+        note: "hand-verified 2026-10-13",
+    },
+    {
+        owner: "modelcontextprotocol", repo: "python-sdk",
+        gates: [gate("assignment_required", "hand-verified 2026-10-13: same assignment culture as the other MCP SDKs")],
+        note: "hand-verified 2026-10-13",
+    },
+    {
+        owner: "modelcontextprotocol", repo: "servers",
+        gates: [gate("collaborators_only", "hand-verified 2026-10-13: PR creation policy collaborators_only")],
+        note: "hand-verified 2026-10-13",
+    },
+];
+/** Merge live-parsed gates with hand-verified gates: hand data wins on kind, live can add new kinds. */
+function mergeGates(hand, live) {
+    const byKind = new Map();
+    for (const g of live)
+        byKind.set(g.kind, g);
+    for (const g of hand)
+        byKind.set(g.kind, g); // hand-verified takes precedence
+    const all = [];
+    const seen = new Set();
+    for (const g of [...hand, ...live]) {
+        if (seen.has(g.kind))
+            continue;
+        seen.add(g.kind);
+        all.push(byKind.get(g.kind));
+    }
+    return all;
+}
+async function main() {
+    const reports = [];
+    let liveOk = 0;
+    let liveFailed = 0;
+    for (const entry of HAND) {
+        let contributing;
+        let liveNote = entry.note;
+        try {
+            contributing = await fetchContributing(entry.owner, entry.repo);
+            liveOk++;
+            liveNote = "live 2026-10-13, merged with hand-verified gates";
+        }
+        catch {
+            liveFailed++;
+            contributing = undefined;
+        }
+        const liveGates = parseGates(contributing);
+        const gates = mergeGates(entry.gates, liveGates);
+        const report = scoreFriction({
+            owner: entry.owner,
+            repo: entry.repo,
+            gates,
+            externalPRMergeRate: null,
+            medianFirstReviewHours: null,
+            maintainerIssueResponseHours: null,
+            openGoodFirstIssueCount: null,
+            note: liveNote,
+        });
+        // Surface the hard gates in reasons even when score math already did.
+        const hard = hardGates(gates);
+        if (hard.length > 0)
+            report.reasons.unshift(`HARD GATE: ${hard.map((g) => g.kind).join(", ")}`);
+        reports.push(report);
+    }
+    reports.sort((a, b) => b.score - a.score);
+    const outDir = join(ROOT, "data");
+    mkdirSync(outDir, { recursive: true });
+    writeFileSync(join(outDir, "friction-index.json"), JSON.stringify({ generated: new Date().toISOString(), repos: reports }, null, 2), "utf8");
+    console.log(`wrote data/friction-index.json with ${reports.length} repos (live fetch ok: ${liveOk}, fallback: ${liveFailed})`);
+}
+await main();
+//# sourceMappingURL=friction-index.js.map

package/dist/friction-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"friction-index.js","sourceRoot":"","sources":["../src/friction-index.ts"],"names":[],"mappings":"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"}

package/dist/friction.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Repo friction score: 0-100, where 100 = easiest place for an outsider
+ * to land a PR.
+ *
+ * Formula (documented, deterministic):
+ *   start at 100
+ *   gates:
+ *     assignment_required  -25
+ *     vouch_required       -35
+ *     collaborators_only   -50
+ *     discussion_first     -10
+ *     claim_first           -5
+ *     cla_required          -5
+ *     dco_required          -5
+ *   outcome signals (only when computed, never guessed):
+ *     external PR merge rate: +(rate - 0.5) * 40
+ *       (a 100% external merge rate adds 20; 0% subtracts 20)
+ *     median hours to first review: -min(hours / 24, 14)
+ *       (a week of waiting costs 7 points, capped at 14)
+ *     maintainer hours to first issue response: -min(hours / 48, 10)
+ *   opportunity:
+ *     open good-first-issue count: +min(count, 20) * 0.5 (max +10)
+ *   clamp to [0, 100], rounded.
+ *
+ * Null signals are simply skipped: the index never fabricates numbers.
+ */
+import type { FrictionReport, RepoSignals } from "./types.js";
+export declare function scoreFriction(signals: RepoSignals): FrictionReport;

package/dist/friction.js

@@ -0,0 +1,54 @@
+import { gateLabel } from "./gates.js";
+const GATE_WEIGHTS = {
+    assignment_required: -25,
+    vouch_required: -35,
+    collaborators_only: -50,
+    discussion_first: -10,
+    claim_first: -5,
+    cla_required: -5,
+    dco_required: -5,
+};
+function clamp(n, lo, hi) {
+    return Math.max(lo, Math.min(hi, n));
+}
+export function scoreFriction(signals) {
+    let score = 100;
+    const reasons = [];
+    for (const gate of signals.gates) {
+        if (!gate.detected)
+            continue;
+        const w = GATE_WEIGHTS[gate.kind] ?? 0;
+        score += w;
+        reasons.push(`${gateLabel(gate.kind)} (${w})`);
+    }
+    if (signals.externalPRMergeRate !== undefined && signals.externalPRMergeRate !== null) {
+        const delta = (signals.externalPRMergeRate - 0.5) * 40;
+        score += delta;
+        reasons.push(`external PR merge rate ${Math.round(signals.externalPRMergeRate * 100)}% (${delta >= 0 ? "+" : ""}${delta.toFixed(1)})`);
+    }
+    if (signals.medianFirstReviewHours !== undefined && signals.medianFirstReviewHours !== null) {
+        const penalty = -Math.min(signals.medianFirstReviewHours / 24, 14);
+        score += penalty;
+        reasons.push(`median first review ${signals.medianFirstReviewHours.toFixed(1)}h (${penalty.toFixed(1)})`);
+    }
+    if (signals.maintainerIssueResponseHours !== undefined && signals.maintainerIssueResponseHours !== null) {
+        const penalty = -Math.min(signals.maintainerIssueResponseHours / 48, 10);
+        score += penalty;
+        reasons.push(`maintainer issue response ${signals.maintainerIssueResponseHours.toFixed(1)}h (${penalty.toFixed(1)})`);
+    }
+    if (signals.openGoodFirstIssueCount !== undefined && signals.openGoodFirstIssueCount !== null) {
+        const bonus = Math.min(signals.openGoodFirstIssueCount, 20) * 0.5;
+        score += bonus;
+        if (bonus > 0)
+            reasons.push(`${signals.openGoodFirstIssueCount} open good-first-issues (+${bonus.toFixed(1)})`);
+    }
+    return {
+        owner: signals.owner,
+        repo: signals.repo,
+        score: Math.round(clamp(score, 0, 100)),
+        gates: signals.gates,
+        reasons,
+        signals,
+    };
+}
+//# sourceMappingURL=friction.js.map

package/dist/friction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"friction.js","sourceRoot":"","sources":["../src/friction.ts"],"names":[],"mappings":"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"}

package/dist/gates.d.ts

@@ -0,0 +1,51 @@
+/**
+ * CONTRIBUTING.md gate parser.
+ *
+ * Problem this solves: repos have unwritten rituals before an outside PR is
+ * even allowed, and they differ per repo. FastMCP requires assignment
+ * (PrefectHQ/fastmcp#4557). trigger.dev auto-closes PRs from unvouched
+ * authors. modelcontextprotocol/servers and
+ * openai/openai-agents-python are collaborators-only for PR creation.
+ * shadcn-labs/pdfcn asks contributors to comment before starting work:
+ * that is a soft claim-first ritual, satisfied by posting a comment, not a
+ * hard assignment gate. This parser extracts those gates from contributing
+ * text so the verdict engine can flag GATED instead of letting you code
+ * first and get rejected, while soft gates like claim_first only add a note.
+ */
+import type { Gate, GateKind } from "./types.js";
+export interface ParseOptions {
+    /** Repo-level policy passed in when detectable (e.g. from repo metadata). */
+    collaboratorsOnlyPolicy?: boolean;
+}
+/** One policy file's raw text: CONTRIBUTING variants, AGENTS.md, CLAUDE.md. */
+export interface PolicySource {
+    file: string;
+    text: string;
+}
+/**
+ * Parse several policy files at once. Binding rules increasingly live in
+ * house-rules files that CONTRIBUTING only links to (reticle keeps its
+ * claim-first, DCO, .changes and `pnpm verify` rules in AGENTS.md), so the
+ * same gate rules run over all of them. Sources are merged without
+ * duplicating kinds: CONTRIBUTING variants win ties, and each detected gate
+ * records the file its evidence came from.
+ */
+export declare function parseGatesFromSources(sources: PolicySource[]): Gate[];
+/**
+ * Parse contributing text into a gate list. Always returns all seven gates
+ * with detected true/false, plus an evidence snippet when detected.
+ */
+export declare function parseGates(text: string | undefined, options?: ParseOptions): Gate[];
+/**
+ * Parse a gatefile contribution-gates.json document into Greenlight gates.
+ * gatefile (the companion tool) extracts a repo's gates once and commits
+ * them as JSON; a repo that carries that file has already answered the gate
+ * question, so its verdicts should use the committed answer instead of
+ * re-deriving it from prose. Returns only the detected gates, each with its
+ * evidence prefixed so a verdict can say where the gate came from. Unknown
+ * kinds are skipped; malformed JSON throws.
+ */
+export declare function parseGatefileJson(text: string): Gate[];
+export declare function hardGates(gates: Gate[]): Gate[];
+/** Human-friendly name for a gate kind. */
+export declare function gateLabel(kind: GateKind): string;

package/dist/gates.js

@@ -0,0 +1,198 @@
+const RULES = [
+    {
+        kind: "assignment_required",
+        regexes: [
+            /ask (to be|for) (assigned|assignment)/i,
+            /request (an )?assignment/i,
+            /must (also )?be assigned/i,
+            /assign.*before (submitting|opening|a PR)/i,
+            /please (wait|hold) (for|until).*assign/i,
+            /\bgood first issue\b.{0,40}\bassign/i,
+        ],
+    },
+    {
+        // Soft ritual: comment (or claim) on the issue before starting work.
+        // Satisfied by posting a comment; never a hard block.
+        kind: "claim_first",
+        regexes: [
+            /comment.{0,60}before (starting|working|opening)/i,
+            /claim.*before (you )?start/i,
+            /comment.{0,60}before you (start|code|submit)/i,
+        ],
+    },
+    {
+        kind: "vouch_required",
+        regexes: [/\bvouch/i, /vouched (author|contributor)/i],
+    },
+    {
+        kind: "cla_required",
+        regexes: [
+            /contributor license agreement/i,
+            /\bcla\b.{0,20}(sign|require)/i,
+            /sign.{0,20}\bcla\b/i,
+        ],
+    },
+    {
+        kind: "dco_required",
+        regexes: [
+            /\bdco\b/i,
+            /developer certificate of origin/i,
+            /sign-?off.*commit/i,
+            /signed-off-by/i,
+        ],
+    },
+    {
+        kind: "discussion_first",
+        regexes: [
+            /discuss.*before (opening|submitting|a PR)/i,
+            /open an issue before/i,
+            /proposal.*(first|before)/i,
+            /rfc.*(first|before)/i,
+            /start (a |with a )?discussion/i,
+        ],
+    },
+    {
+        kind: "collaborators_only",
+        regexes: [
+            /collaborators only/i,
+            /collaborators-only/i,
+            /only (repo )?collaborators/i,
+            /external (prs|pull requests) (are not|will not be) accepted/i,
+            // Maintainer-only PR shops (field cases 2026-10-15): the MCP inspector
+            // and servers repos take issues and prompts, not outside PRs, and say
+            // so in workflow language rather than gate language — "Pull requests
+            // against this repo are opened by the repo maintainers only" and
+            // "We accept issues, not pull requests". Both scored GO with "no
+            // blocking gates" until these phrasings were added. The optional
+            // asterisks tolerate the Markdown bold both repos wrap the words in.
+            /pull requests? (against|in|on) this (repo|repository) are opened by (the )?(\*\*)?(repo |repository )?maintainers(\*\*)? only/i,
+            /accept issues, not pull requests?/i,
+        ],
+    },
+];
+/** Cut a short evidence snippet around the first regex match. */
+function snippet(text, regex) {
+    const match = regex.exec(text);
+    if (!match)
+        return "";
+    const idx = Math.max(0, match.index - 60);
+    const raw = text.slice(idx, idx + 160).replace(/\s+/g, " ").trim();
+    return raw.length > 140 ? raw.slice(0, 140) + "..." : raw;
+}
+/**
+ * Parse several policy files at once. Binding rules increasingly live in
+ * house-rules files that CONTRIBUTING only links to (reticle keeps its
+ * claim-first, DCO, .changes and `pnpm verify` rules in AGENTS.md), so the
+ * same gate rules run over all of them. Sources are merged without
+ * duplicating kinds: CONTRIBUTING variants win ties, and each detected gate
+ * records the file its evidence came from.
+ */
+export function parseGatesFromSources(sources) {
+    const contributingFirst = (f) => (f.toLowerCase().includes("contributing") ? 0 : 1);
+    const ordered = [...sources].sort((a, b) => contributingFirst(a.file) - contributingFirst(b.file));
+    const merged = RULES.map((r) => ({
+        kind: r.kind,
+        detected: false,
+        evidence: "",
+        source: undefined,
+    }));
+    for (const src of ordered) {
+        const gates = parseGates(src.text);
+        for (const g of gates) {
+            if (!g.detected)
+                continue;
+            const m = merged.find((x) => x.kind === g.kind);
+            if (m && !m.detected) {
+                m.detected = true;
+                m.evidence = g.evidence;
+                m.source = src.file;
+            }
+        }
+    }
+    return merged;
+}
+/**
+ * Parse contributing text into a gate list. Always returns all seven gates
+ * with detected true/false, plus an evidence snippet when detected.
+ */
+export function parseGates(text, options = {}) {
+    const body = text ?? "";
+    return RULES.map((rule) => {
+        const found = rule.regexes.find((re) => re.test(body));
+        if (rule.kind === "collaborators_only" && options.collaboratorsOnlyPolicy) {
+            return {
+                kind: rule.kind,
+                detected: true,
+                evidence: "repo policy: PR creation restricted to collaborators",
+            };
+        }
+        return {
+            kind: rule.kind,
+            detected: Boolean(found),
+            evidence: found ? snippet(body, found) : "",
+        };
+    });
+}
+/**
+ * gatefile's contribution-gates.json kinds mapped onto Greenlight kinds.
+ * The two tools share a taxonomy with a few aliases: gatefile's
+ * discuss_first and issue_first are Greenlight's discussion_first, and its
+ * no_direct_prs is the hard block Greenlight calls collaborators_only.
+ */
+const GATEFILE_KIND_MAP = {
+    claim_first: "claim_first",
+    assignment_required: "assignment_required",
+    vouch_required: "vouch_required",
+    collaborators_only: "collaborators_only",
+    dco_required: "dco_required",
+    cla_required: "cla_required",
+    discuss_first: "discussion_first",
+    issue_first: "discussion_first",
+    no_direct_prs: "collaborators_only",
+};
+/**
+ * Parse a gatefile contribution-gates.json document into Greenlight gates.
+ * gatefile (the companion tool) extracts a repo's gates once and commits
+ * them as JSON; a repo that carries that file has already answered the gate
+ * question, so its verdicts should use the committed answer instead of
+ * re-deriving it from prose. Returns only the detected gates, each with its
+ * evidence prefixed so a verdict can say where the gate came from. Unknown
+ * kinds are skipped; malformed JSON throws.
+ */
+export function parseGatefileJson(text) {
+    const doc = JSON.parse(text);
+    if (!doc || !Array.isArray(doc.gates)) {
+        throw new Error("not a contribution-gates.json document (no gates array)");
+    }
+    const out = [];
+    for (const g of doc.gates) {
+        const kind = g.kind ? GATEFILE_KIND_MAP[g.kind] : undefined;
+        if (!kind || out.some((x) => x.kind === kind))
+            continue;
+        out.push({
+            kind,
+            detected: true,
+            evidence: `gatefile: ${g.evidence ?? g.kind}`,
+            source: g.source ?? "contribution-gates.json",
+        });
+    }
+    return out;
+}
+/** Gates that block an outside PR before it can even be opened. */
+const HARD_GATES = ["assignment_required", "vouch_required", "collaborators_only"];
+export function hardGates(gates) {
+    return gates.filter((g) => g.detected && HARD_GATES.includes(g.kind));
+}
+/** Human-friendly name for a gate kind. */
+export function gateLabel(kind) {
+    switch (kind) {
+        case "assignment_required": return "assignment required before PR";
+        case "claim_first": return "comment first before starting";
+        case "vouch_required": return "vouch required before PR";
+        case "cla_required": return "CLA signature required";
+        case "dco_required": return "DCO sign-off required";
+        case "discussion_first": return "discussion first";
+        case "collaborators_only": return "PR creation restricted to collaborators";
+    }
+}
+//# sourceMappingURL=gates.js.map

package/dist/gates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gates.js","sourceRoot":"","sources":["../src/gates.ts"],"names":[],"mappings":"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"}

package/dist/github.d.ts

@@ -0,0 +1,155 @@
+import type { IssueSnapshot, LinkedPR, CommentSignal, GateKind, MentionedPR } from "./types.js";
+export declare class RateLimitError extends Error {
+    constructor(message: string);
+}
+/** Thrown by apiGet/apiPost for HTTP 404, so callers can treat "missing" as data. */
+export declare class ApiNotFoundError extends Error {
+    constructor(path: string);
+}
+export declare function githubToken(): string | undefined;
+export declare function apiGet(path: string): Promise<unknown>;
+/** POST helper for write operations (automation commands). Read paths use apiGet. */
+export declare function apiPost(path: string, body: unknown): Promise<unknown>;
+export interface IssueURL {
+    owner: string;
+    repo: string;
+    number: number;
+}
+export declare function parseIssueUrl(url: string): IssueURL;
+/** Fetch issue comments for claim detection. */
+export declare function fetchComments(owner: string, repo: string, number: number): Promise<CommentSignal[]>;
+/**
+ * Find PRs that reference an issue. Timeline cross-references and a text
+ * search for the issue number are discovery only: every candidate PR is
+ * then fetched individually and scored with classifyLinkStrength, so a PR
+ * that merely lists a sibling issue (e.g. pdfcn #91 closing #70 while
+ * mentioning #61) is stored as a "mention", not a "closing" PR. See issue #1.
+ */
+export declare function fetchLinkedPRs(owner: string, repo: string, number: number): Promise<LinkedPR[]>;
+/** Minimal PR detail needed for the comment-mention cross-check. */
+export interface PullRefDetail {
+    number: number;
+    state: "open" | "closed";
+    merged: boolean;
+    title: string;
+    body: string;
+    url: string;
+}
+export interface MentionedPRDeps {
+    fetchPull?: (owner: string, repo: string, number: number) => Promise<PullRefDetail | null>;
+}
+/**
+ * Policy files fetched for gate extraction. Binding contribution rules
+ * increasingly live in house-rules files that CONTRIBUTING only links to
+ * (reticle keeps its claim-first, DCO, .changes and `pnpm verify` rules in
+ * AGENTS.md), so CONTRIBUTING variants are fetched together with AGENTS.md
+ * and CLAUDE.md at the root and under .github/. fastmcp moved its rules
+ * again in 2026, into docs/development/contributing.mdx behind a pointer
+ * CONTRIBUTING.md, which is why the development-guide paths are here too.
+ */
+export declare const HOUSE_RULE_FILES: readonly ["CONTRIBUTING.md", "contributing.md", ".github/CONTRIBUTING.md", "docs/development/contributing.mdx", "docs/development/contributing.md", "AGENTS.md", "CLAUDE.md", ".github/AGENTS.md", ".github/CLAUDE.md"];
+export interface HouseRuleDeps {
+    /** Test seam: fetch a repo-root file's raw text, or undefined when absent. */
+    fetchRaw?: (file: string) => Promise<string | undefined>;
+}
+/** Fetch all existing house-rules files for a repo (best-effort, cached). */
+export declare function fetchHouseRules(owner: string, repo: string, deps?: HouseRuleDeps): Promise<{
+    file: string;
+    text: string;
+}[]>;
+/** Fetch CONTRIBUTING.md raw text; returns undefined when the repo has none. */
+export declare function fetchContributing(owner: string, repo: string): Promise<string | undefined>;
+/**
+ * Extract PR references from comment bodies: bare #NNN mentions and full
+ * github.com/<owner>/<repo>/pull/NNN URLs. Returns deduplicated numbers in
+ * order of first appearance.
+ */
+export declare function extractPRReferences(comments: CommentSignal[], owner: string, repo: string): number[];
+/**
+ * PR references per citing comment author: number -> first comment author
+ * that cited it. Used to tag MentionedPRs with fromAuthor.
+ */
+export declare function extractPRReferenceAuthors(comments: CommentSignal[], owner: string, repo: string): Map<number, string>;
+/**
+ * Cross-check PR references found in comments against the PR API.
+ *
+ * Motivation: reticlehq/reticle#691 got a clean GO verdict while its comments
+ * contained a partial claim ("Taking the remaining fallback ask") and a
+ * heads-up that PR #861 covers that work. Neither signal existed in the
+ * timeline or the issue-number search, so both were missed.
+ *
+ * All comments are scanned (PR references are cheap to extract), but each
+ * result records whether the citing comment came from the issue author.
+ * The open-PR downgrade (rule 11) only trusts non-author heads-ups; the
+ * partially-addressed rule (rule 12) also reads the author's, because the
+ * maintainer narrating what already shipped is usually the issue author.
+ * References already found via the timeline/search, and the issue's own
+ * number, are skipped. Bounded at 5 PR fetches per call; the walk is
+ * best-effort and cached like the rest of the issue data.
+ */
+export declare function fetchCommentMentionedPRs(owner: string, repo: string, issueNumber: number, comments: CommentSignal[], knownPRNumbers: number[], deps?: MentionedPRDeps & {
+    issueAuthor?: string;
+}): Promise<MentionedPR[]>;
+/** Count open issues labelled good-first-issue or help-wanted. */
+export declare function countStarterIssues(owner: string, repo: string): Promise<number | null>;
+/** Detect a collaborators-only PR creation policy via the community metrics endpoint. */
+export declare function detectRepoPolicy(owner: string, repo: string): Promise<{
+    collaboratorsOnly: boolean;
+}>;
+/** Build a full IssueSnapshot from the live API. */
+export declare function buildIssueSnapshot(owner: string, repo: string, number: number): Promise<IssueSnapshot>;
+export interface ScanCandidate {
+    number: number;
+    title: string;
+    url: string;
+    labels: string[];
+    updatedAt: string;
+}
+/** List open good-first-issue / help-wanted issues for scan mode. */
+export declare function listStarterIssues(owner: string, repo: string, limit?: number): Promise<ScanCandidate[]>;
+/** Raw issue-list item shape from GET /repos/:o/:r/issues. */
+interface IssueListItem {
+    number: number;
+    title: string;
+    html_url: string;
+    labels: Array<{
+        name: string;
+    }>;
+    updated_at: string;
+    pull_request?: unknown;
+    assignees?: Array<{
+        login: string;
+    }>;
+}
+/**
+ * Filter raw issue-list items down to scan candidates: real issues (not
+ * pull requests) with no assignees, newest first. Pure so tests can drive
+ * it with fixtures.
+ */
+export declare function toScanCandidates(items: IssueListItem[]): ScanCandidate[];
+/**
+ * Fallback candidate list for scan mode: the most recent open unassigned
+ * issues in the repo, for repos whose landable issues do not carry
+ * good-first-issue / help-wanted labels. Lists broadly (up to `cap`) so
+ * the caller can take the newest slice.
+ */
+export declare function listRecentUnassignedIssues(owner: string, repo: string, cap?: number): Promise<ScanCandidate[]>;
+export interface ScanCandidateList {
+    issues: ScanCandidate[];
+    /** True when the label pass came back empty and the fallback list was used. */
+    fallbackUsed: boolean;
+}
+export interface ScanDeps {
+    starter?: (owner: string, repo: string, limit: number) => Promise<ScanCandidate[]>;
+    recent?: (owner: string, repo: string, cap: number) => Promise<ScanCandidate[]>;
+}
+/**
+ * Scan candidates for a repo: the label-tagged starter list first; when it
+ * is empty, fall back to recent open unassigned issues (opt out with
+ * fallback: false). Injectable deps keep tests offline.
+ */
+export declare function scanCandidates(owner: string, repo: string, opts?: {
+    fallback?: boolean;
+    limit?: number;
+}, deps?: ScanDeps): Promise<ScanCandidateList>;
+export type { GateKind };