@reneturcios/greenlight 0.18.0 → 0.19.0

package/dist/friction.js

@@ -1,5 +1,5 @@
 import { gateLabel, parseGatesFromSources } from "./gates.js";
-import { fetchPolicySources, detectRepoPolicy, countStarterIssues, resolveCanonicalRepo, } from "./github.js";
+import { fetchPolicySourcesWithProvenance, detectRepoPolicy, countStarterIssues, countStarterCandidates, resolveCanonicalRepo, } from "./github.js";
 import { fetchMergeVelocity } from "./merge-velocity.js";
 import { detectBehavioralGate } from "./behavior.js";
 const GATE_WEIGHTS = {
@@ -106,9 +106,22 @@ export function attachOutsiderShare(report) {
  * and docs/, plus the org-level AI_POLICY.md), starter-issue count, and
  * merge velocity as a best-effort signal. Shared by the CLI, the MCP
  * repo_friction tool, and the protocol preflight (which pairs it with
- * the issue status).
+ * the issue status). Every report carries policy_provenance: whether
+ * each policy source was read, absent, or a fetch error.
+ *
+ * v0.19.0 lite mode (opts.lite, friction --lite) is the canonical
+ * lightweight computation: policy gates ONLY. It runs the policy-source
+ * fetch plus parseGatesFromSources (and the collaboratorsOnly push from
+ * detectRepoPolicy, which is free), and scores with scoreFriction using
+ * all outcome signals null and behavioralGate null, so the score is
+ * 100 + gate weights, clamped, with the same GATE_WEIGHTS. It skips the
+ * behavioral pass, merge velocity, and the starter-issue count, marks
+ * the report lite: true, and sets signals.note to "lite". Repo rename
+ * resolution stays: it is one cheap call and name correctness matters
+ * for the scanner.
  */
 export async function fetchFrictionSummary(owner, repo, opts = {}) {
+    const lite = opts.lite === true;
     // v0.18.0 (item 15): renamed repos (dbt-labs/dbt-core -> dbt-labs/dbt)
     // 422 search and confuse every name-based flow; resolve once, use the
     // canonical name everywhere below, and carry the old name in
@@ -117,16 +130,24 @@ export async function fetchFrictionSummary(owner, repo, opts = {}) {
     const resolvedFrom = canon.renamed ? `${owner}/${repo}` : undefined;
     owner = canon.owner;
     repo = canon.repo;
-    const [sources, policy, starterCount, mergeVelocity] = await Promise.all([
-        fetchPolicySources(owner, repo),
-        detectRepoPolicy(owner, repo),
-        countStarterIssues(owner, repo),
-        // v0.18.0 (item 11): merge velocity feeds the documented external
-        // merge-rate score term (see the formula in the module header).
-        // Best-effort: a failed fetch leaves the term null and unscored,
-        // never fabricated.
-        fetchMergeVelocity(owner, repo).catch(() => null),
-    ]);
+    const [sourcesResult, policy, starterCount, mergeVelocity] = lite
+        ? await Promise.all([
+            fetchPolicySourcesWithProvenance(owner, repo),
+            detectRepoPolicy(owner, repo),
+            Promise.resolve(null),
+            Promise.resolve(null),
+        ])
+        : await Promise.all([
+            fetchPolicySourcesWithProvenance(owner, repo),
+            detectRepoPolicy(owner, repo),
+            countStarterIssues(owner, repo),
+            // v0.18.0 (item 11): merge velocity feeds the documented external
+            // merge-rate score term (see the formula in the module header).
+            // Best-effort: a failed fetch leaves the term null and unscored,
+            // never fabricated.
+            fetchMergeVelocity(owner, repo).catch(() => null),
+        ]);
+    const sources = sourcesResult.sources;
     const gates = parseGatesFromSources(sources);
     if (policy.collaboratorsOnly && !gates.some((g) => g.kind === "collaborators_only" && g.detected)) {
         gates.push({
@@ -137,9 +158,9 @@ export async function fetchFrictionSummary(owner, repo, opts = {}) {
     }
     // Behavioral gate is a signal, best-effort and silent on failure: a
     // dead pass must never fabricate a hostile verdict, and a missing one
-    // must never hide an actual gate.
+    // must never hide an actual gate. Lite mode skips it entirely.
     let behavioralGate = null;
-    if (opts.behavioral !== false) {
+    if (!lite && opts.behavioral !== false) {
         try {
             behavioralGate = await detectBehavioralGate(owner, repo);
         }
@@ -147,6 +168,19 @@ export async function fetchFrictionSummary(owner, repo, opts = {}) {
             behavioralGate = null;
         }
     }
+    // v0.19.0 (item 16): when the classic starter labels read exactly 0,
+    // one bounded fallback estimates open unassigned candidates under a
+    // wider label set. The estimate is reported next to the label count,
+    // never merged into it and never scored.
+    let starterCandidateEstimate = null;
+    if (starterCount === 0) {
+        try {
+            starterCandidateEstimate = await countStarterCandidates(owner, repo);
+        }
+        catch {
+            starterCandidateEstimate = null;
+        }
+    }
     const signals = {
         owner,
         repo,
@@ -156,11 +190,17 @@ export async function fetchFrictionSummary(owner, repo, opts = {}) {
         medianFirstReviewHours: null,
         maintainerIssueResponseHours: null,
         openGoodFirstIssueCount: starterCount,
+        starterLabelCount: starterCount,
+        starterCandidateEstimate,
         behavioralGate,
-        note: "live",
+        note: lite ? "lite" : "live",
     };
     const report = attachBehavioralGate(scoreFriction(signals), behavioralGate);
     report.mergeVelocity = mergeVelocity;
+    // v0.19.0 (item 7): every report says how its policy sources were obtained.
+    report.policy_provenance = sourcesResult.provenance;
+    if (lite)
+        report.lite = true;
     if (resolvedFrom)
         report.resolvedFrom = resolvedFrom;
     return attachOutsiderShare(report);

package/dist/friction.js.map

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

package/dist/github.d.ts

@@ -1,4 +1,4 @@
-import type { IssueSnapshot, LinkedPR, CommentSignal, GateKind, Gate, MentionedPR, DuplicateTarget } from "./types.js";
+import type { IssueSnapshot, LinkedPR, CommentSignal, GateKind, Gate, MentionedPR, DuplicateTarget, PolicySourceProvenance } from "./types.js";
 import { type WorkflowFile } from "./gates.js";
 /**
  * The GitHub API base in use. Reads GREENLIGHT_GITHUB_BASE_URL so a
@@ -105,11 +105,31 @@ export interface MentionedPRDeps {
  */
 export declare const HOUSE_RULE_FILES: readonly ["CONTRIBUTING.md", ".github/CONTRIBUTING.md", "docs/CONTRIBUTING.md", "contributing.md", "docs/development/contributing.mdx", "docs/development/contributing.md", "AGENTS.md", ".github/AGENTS.md", "docs/AGENTS.md", "CLAUDE.md", ".github/CLAUDE.md", "docs/CLAUDE.md", "AI_POLICY.md", ".github/AI_POLICY.md", "docs/AI_POLICY.md"];
 export interface HouseRuleDeps {
-    /** Test seam: fetch a repo-root file's raw text, or undefined when absent. */
+    /**
+     * Test seam: fetch a repo-root file's raw text, or undefined when absent.
+     * v0.19.0: a fetchRaw that throws surfaces as a provenance "error" (with
+     * the error as the kind string), never as "absent".
+     */
     fetchRaw?: (file: string) => Promise<string | undefined>;
     /** Test seam: fetch the org's AI_POLICY.md text, or undefined when absent. */
     fetchOrgPolicy?: (owner: string) => Promise<string | undefined>;
 }
+/**
+ * v0.19.0: the detailed outcome of one raw policy-file fetch. The old
+ * fetchRawFile collapsed "no such file" and "the fetch failed" into the
+ * same undefined, so friction could not tell a repo with no policy from
+ * a repo whose policy read broke. "error" carries a short kind string
+ * (e.g. "rate limited", "http 500", "network error").
+ */
+export type RawFileFetchStatus = {
+    status: "read";
+    text: string;
+} | {
+    status: "absent";
+} | {
+    status: "error";
+    error: string;
+};
 /**
  * v0.9.3: org-level AI policy. Binding agent rules sometimes live in the
  * org's `.github` repo rather than the project repo (astral-sh's
@@ -117,17 +137,77 @@ export interface HouseRuleDeps {
  * CONTRIBUTING only links to mastodon/.github's AI_POLICY.md). Probed
  * once per org and cached under its own key so a sweep over N repos from
  * one org costs one fetch, not N.
+ *
+ * v0.19.0: the cache entry now carries the full detailed outcome
+ * (read/absent/error); entries written before v0.19.0 (a bare text or
+ * empty string) are treated as a miss and re-fetched.
  */
+export declare function fetchOrgAiPolicyDetailed(owner: string, deps?: HouseRuleDeps): Promise<{
+    file: string;
+    outcome: RawFileFetchStatus;
+}>;
+/** Org-level AI policy text, or undefined when absent or unreadable. */
 export declare function fetchOrgAiPolicy(owner: string, deps?: HouseRuleDeps): Promise<string | undefined>;
 /**
  * v0.9.3: the full policy source set for gate detection: house-rules
  * files (first hit per filename across root, .github/, docs/) plus the
  * org-level AI_POLICY.md when the org publishes one.
+ *
+ * v0.19.0: fetchPolicySourcesWithProvenance adds the read provenance
+ * friction reports; this plain variant delegates and returns the sources
+ * alone, so its callers do not change.
  */
+export declare function fetchPolicySourcesWithProvenance(owner: string, repo: string, deps?: HouseRuleDeps): Promise<{
+    sources: {
+        file: string;
+        text: string;
+    }[];
+    provenance: PolicySourceProvenance[];
+}>;
 export declare function fetchPolicySources(owner: string, repo: string, deps?: HouseRuleDeps): Promise<{
     file: string;
     text: string;
 }[]>;
+/**
+ * v0.9.3: fetch one policy file's raw text, honoring the API base
+ * override. In proxy mode (GREENLIGHT_GITHUB_BASE_URL set) the raw host
+ * is unreachable with the surrogate credential, so policy files are read
+ * through the contents API instead; otherwise the raw host is used as
+ * before.
+ *
+ * v0.19.0: fetchRawFileDetailed distinguishes three outcomes: read,
+ * absent (the file genuinely is not there), and error (the fetch
+ * failed). fetchRawFile stays as a thin wrapper that returns the text
+ * only when the fetch read, so its callers do not change.
+ */
+export declare function fetchRawFileDetailed(owner: string, repo: string, file: string, headers: Record<string, string>): Promise<RawFileFetchStatus>;
+/**
+ * Fetch all existing house-rules files for a repo (best-effort, cached),
+ * with per-basename read provenance.
+ *
+ * v0.9.3: stop at the first hit per filename (root, then .github/, then
+ * docs/), so a repo with CONTRIBUTING.md at the root does not pay for
+ * two more 404s, and a repo with it only in docs/ is still found (the
+ * AFFiNE shape the 5k scan caught: root-only probing called it
+ * "no policy" while docs/CONTRIBUTING.md existed).
+ *
+ * v0.19.0: provenance carries ONE entry per basename probed: the path
+ * that was read (status "read"), the first candidate path with status
+ * "absent" when every location missed, or status "error" with the first
+ * error kind when a fetch failed before any hit. An error at one
+ * location does not stop the later locations: the read still wins when
+ * a later location has the file.
+ *
+ * The cache payload is { sources, provenance }; entries written before
+ * v0.19.0 (a bare sources array) count as a miss and are re-fetched.
+ */
+export declare function fetchHouseRulesDetailed(owner: string, repo: string, deps?: HouseRuleDeps): Promise<{
+    sources: {
+        file: string;
+        text: string;
+    }[];
+    provenance: PolicySourceProvenance[];
+}>;
 /** 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;
@@ -245,6 +325,23 @@ export declare function extractTimelineCrossRefPRs(events: Record<string, unknow
 }>;
 /** Count open issues labelled good-first-issue or help-wanted. */
 export declare function countStarterIssues(owner: string, repo: string): Promise<number | null>;
+/**
+ * v0.19.0 (item 16): the wider starter label set for the candidate
+ * estimate. Repos that never adopted the classic "good first issue" /
+ * "help wanted" pair often label starter work one of these instead.
+ */
+export declare const STARTER_CANDIDATE_LABELS: readonly ["beginner friendly", "beginner", "easy", "starter", "first-timers-only", "up-for-grabs", "good-first-issue"];
+export interface StarterSearchDeps {
+    /** Test seam: run a search query, return its total_count or null. */
+    searchCount?: (query: string) => Promise<number | null>;
+}
+/**
+ * Fallback starter-candidate estimate, used only when the classic
+ * label count is exactly 0. One search call: open, unassigned issues
+ * under the wider starter label set. An estimate for display, never a
+ * score input; null when the search itself fails.
+ */
+export declare function countStarterCandidates(owner: string, repo: string, deps?: StarterSearchDeps): 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;
@@ -292,6 +389,20 @@ export interface ScanCandidateList {
     /** True when the label pass came back empty and the fallback list was used. */
     fallbackUsed: boolean;
 }
+/**
+ * Default wall-time bound for `greenlight scan`, in seconds (v0.19.0,
+ * item 17): on mega-backlog repos the per-issue verdict pipeline ran
+ * about 25 minutes, so the scan stops with marked partial results when
+ * the budget runs out instead of running open-ended. Override per run
+ * with --max-time <seconds>.
+ */
+export declare const DEFAULT_SCAN_MAX_TIME_SEC = 600;
+/**
+ * Pure wall-time check for the scan loop (v0.19.0, item 17): true once
+ * the elapsed time since startedAtMs has reached the budget. Call with
+ * Date.now() for the nowMs argument. Exported for unit tests.
+ */
+export declare function scanBudgetExceeded(startedAtMs: number, maxTimeSec: number, nowMs: number): boolean;
 export interface ScanDeps {
     starter?: (owner: string, repo: string, limit: number) => Promise<ScanCandidate[]>;
     recent?: (owner: string, repo: string, cap: number) => Promise<ScanCandidate[]>;

package/dist/github.js

@@ -400,6 +400,17 @@ export const HOUSE_RULE_FILES = [
     ".github/AI_POLICY.md",
     "docs/AI_POLICY.md",
 ];
+/** Short kind string for a policy-file fetch failure (never the full stack). */
+function classifyFetchError(err) {
+    if (err instanceof RateLimitError)
+        return "rate limited";
+    if (err instanceof RequestTimeoutError)
+        return "timeout";
+    if (err instanceof Error && err.message) {
+        return err.message.length > 120 ? err.message.slice(0, 120) : err.message;
+    }
+    return "fetch error";
+}
 /**
  * v0.9.3: org-level AI policy. Binding agent rules sometimes live in the
  * org's `.github` repo rather than the project repo (astral-sh's
@@ -407,95 +418,203 @@ export const HOUSE_RULE_FILES = [
  * CONTRIBUTING only links to mastodon/.github's AI_POLICY.md). Probed
  * once per org and cached under its own key so a sweep over N repos from
  * one org costs one fetch, not N.
+ *
+ * v0.19.0: the cache entry now carries the full detailed outcome
+ * (read/absent/error); entries written before v0.19.0 (a bare text or
+ * empty string) are treated as a miss and re-fetched.
  */
-export async function fetchOrgAiPolicy(owner, deps = {}) {
+export async function fetchOrgAiPolicyDetailed(owner, deps = {}) {
+    const file = `AI_POLICY.md (org ${owner})`;
     if (!deps.fetchOrgPolicy) {
         const cached = cacheGet("org-ai-policy", [owner.toLowerCase()]);
-        if (cached !== undefined)
-            return cached || undefined;
+        if (cached !== undefined && typeof cached === "object")
+            return { file, outcome: cached };
     }
     const headers = { "User-Agent": "greenlight-cli" };
     const token = githubToken();
     if (token)
         headers["Authorization"] = `Bearer ${token}`;
-    const fetchOrgPolicy = deps.fetchOrgPolicy ??
-        ((o) => fetchRawFile(o, ".github", "AI_POLICY.md", headers));
-    const text = await fetchOrgPolicy(owner);
+    let outcome;
+    if (deps.fetchOrgPolicy) {
+        try {
+            const text = await deps.fetchOrgPolicy(owner);
+            outcome = text ? { status: "read", text } : { status: "absent" };
+        }
+        catch (err) {
+            outcome =
+                err instanceof ApiNotFoundError
+                    ? { status: "absent" }
+                    : { status: "error", error: classifyFetchError(err) };
+        }
+    }
+    else {
+        outcome = await fetchRawFileDetailed(owner, ".github", "AI_POLICY.md", headers);
+    }
     if (!deps.fetchOrgPolicy)
-        cacheSet("org-ai-policy", [owner.toLowerCase()], text ?? "");
-    return text;
+        cacheSet("org-ai-policy", [owner.toLowerCase()], outcome);
+    return { file, outcome };
+}
+/** Org-level AI policy text, or undefined when absent or unreadable. */
+export async function fetchOrgAiPolicy(owner, deps = {}) {
+    const { outcome } = await fetchOrgAiPolicyDetailed(owner, deps);
+    return outcome.status === "read" ? outcome.text : undefined;
 }
 /**
  * v0.9.3: the full policy source set for gate detection: house-rules
  * files (first hit per filename across root, .github/, docs/) plus the
  * org-level AI_POLICY.md when the org publishes one.
+ *
+ * v0.19.0: fetchPolicySourcesWithProvenance adds the read provenance
+ * friction reports; this plain variant delegates and returns the sources
+ * alone, so its callers do not change.
  */
+export async function fetchPolicySourcesWithProvenance(owner, repo, deps = {}) {
+    const [{ sources, provenance }, { file, outcome }] = await Promise.all([
+        fetchHouseRulesDetailed(owner, repo, deps),
+        fetchOrgAiPolicyDetailed(owner, deps),
+    ]);
+    if (outcome.status === "read")
+        sources.push({ file, text: outcome.text });
+    provenance.push(outcome.status === "read"
+        ? { file, scope: "org", status: "read" }
+        : outcome.status === "error"
+            ? { file, scope: "org", status: "error", error: outcome.error }
+            : { file, scope: "org", status: "absent" });
+    return { sources, provenance };
+}
 export async function fetchPolicySources(owner, repo, deps = {}) {
-    const rules = await fetchHouseRules(owner, repo, deps);
-    const orgPolicy = await fetchOrgAiPolicy(owner, deps);
-    if (orgPolicy)
-        rules.push({ file: `AI_POLICY.md (org ${owner})`, text: orgPolicy });
-    return rules;
+    const { sources } = await fetchPolicySourcesWithProvenance(owner, repo, deps);
+    return sources;
 }
 /**
  * v0.9.3: fetch one policy file's raw text, honoring the API base
  * override. In proxy mode (GREENLIGHT_GITHUB_BASE_URL set) the raw host
  * is unreachable with the surrogate credential, so policy files are read
  * through the contents API instead; otherwise the raw host is used as
- * before. Returns undefined when the file does not exist.
+ * before.
+ *
+ * v0.19.0: fetchRawFileDetailed distinguishes three outcomes: read,
+ * absent (the file genuinely is not there), and error (the fetch
+ * failed). fetchRawFile stays as a thin wrapper that returns the text
+ * only when the fetch read, so its callers do not change.
  */
-async function fetchRawFile(owner, repo, file, headers) {
+export async function fetchRawFileDetailed(owner, repo, file, headers) {
     if (githubApiBase() !== DEFAULT_API) {
         try {
             const data = (await apiGet(`/repos/${owner}/${repo}/contents/${file}`));
             if (typeof data.content === "string" && data.encoding === "base64") {
-                return Buffer.from(data.content, "base64").toString("utf8");
+                return { status: "read", text: Buffer.from(data.content, "base64").toString("utf8") };
             }
+            return { status: "absent" };
+        }
+        catch (err) {
+            if (err instanceof ApiNotFoundError)
+                return { status: "absent" };
+            return { status: "error", error: classifyFetchError(err) };
         }
-        catch { /* absent */ }
-        return undefined;
     }
     try {
-        const res = await fetch(`${RAW}/${owner}/${repo}/HEAD/${file}`, { headers });
+        const res = await activeFetch()(`${RAW}/${owner}/${repo}/HEAD/${file}`, { headers });
         if (res.ok)
-            return await res.text();
+            return { status: "read", text: await res.text() };
+        if (res.status === 404)
+            return { status: "absent" };
+        return { status: "error", error: `http ${res.status}` };
+    }
+    catch (err) {
+        return { status: "error", error: classifyFetchError(err) };
     }
-    catch { /* try next */ }
-    return undefined;
 }
-/** Fetch all existing house-rules files for a repo (best-effort, cached). */
-export async function fetchHouseRules(owner, repo, deps = {}) {
+/** Returns the file's text when the fetch reads it, otherwise undefined. */
+async function fetchRawFile(owner, repo, file, headers) {
+    const outcome = await fetchRawFileDetailed(owner, repo, file, headers);
+    return outcome.status === "read" ? outcome.text : undefined;
+}
+/**
+ * Fetch all existing house-rules files for a repo (best-effort, cached),
+ * with per-basename read provenance.
+ *
+ * v0.9.3: stop at the first hit per filename (root, then .github/, then
+ * docs/), so a repo with CONTRIBUTING.md at the root does not pay for
+ * two more 404s, and a repo with it only in docs/ is still found (the
+ * AFFiNE shape the 5k scan caught: root-only probing called it
+ * "no policy" while docs/CONTRIBUTING.md existed).
+ *
+ * v0.19.0: provenance carries ONE entry per basename probed: the path
+ * that was read (status "read"), the first candidate path with status
+ * "absent" when every location missed, or status "error" with the first
+ * error kind when a fetch failed before any hit. An error at one
+ * location does not stop the later locations: the read still wins when
+ * a later location has the file.
+ *
+ * The cache payload is { sources, provenance }; entries written before
+ * v0.19.0 (a bare sources array) count as a miss and are re-fetched.
+ */
+export async function fetchHouseRulesDetailed(owner, repo, deps = {}) {
     if (!deps.fetchRaw) {
         const cached = cacheGet("house-rules", [owner, repo]);
-        if (cached)
-            return cached;
+        if (cached && !Array.isArray(cached) && Array.isArray(cached.provenance)) {
+            return { sources: cached.sources, provenance: cached.provenance };
+        }
     }
     const headers = { "User-Agent": "greenlight-cli" };
     const token = githubToken();
     if (token)
         headers["Authorization"] = `Bearer ${token}`;
-    const fetchRaw = deps.fetchRaw ??
-        ((file) => fetchRawFile(owner, repo, file, headers));
-    // v0.9.3: stop at the first hit per filename (root, then .github/, then
-    // docs/), so a repo with CONTRIBUTING.md at the root does not pay for
-    // two more 404s, and a repo with it only in docs/ is still found (the
-    // AFFiNE shape the 5k scan caught: root-only probing called it
-    // "no policy" while docs/CONTRIBUTING.md existed).
-    const seenBasenames = new Set();
-    const out = [];
+    const fetchOne = async (file) => {
+        if (deps.fetchRaw) {
+            try {
+                const text = await deps.fetchRaw(file);
+                return text ? { status: "read", text } : { status: "absent" };
+            }
+            catch (err) {
+                if (err instanceof ApiNotFoundError)
+                    return { status: "absent" };
+                return { status: "error", error: classifyFetchError(err) };
+            }
+        }
+        return fetchRawFileDetailed(owner, repo, file, headers);
+    };
+    const sources = [];
+    const provenance = [];
     for (const file of HOUSE_RULE_FILES) {
         const base = file.split("/").pop().toLowerCase();
-        if (seenBasenames.has(base))
+        if (provenance.some((p) => p.file.split("/").pop().toLowerCase() === base && p.scope === "repo")) {
             continue;
-        const text = await fetchRaw(file);
-        if (text) {
-            out.push({ file, text });
-            seenBasenames.add(base);
+        }
+        let readAt;
+        let firstError;
+        for (const candidate of HOUSE_RULE_FILES) {
+            if (candidate.split("/").pop().toLowerCase() !== base)
+                continue;
+            const outcome = await fetchOne(candidate);
+            if (outcome.status === "read") {
+                readAt = { file: candidate, text: outcome.text };
+                break;
+            }
+            if (outcome.status === "error" && !firstError) {
+                firstError = { file: candidate, error: outcome.error };
+            }
+        }
+        if (readAt) {
+            sources.push(readAt);
+            provenance.push({ file: readAt.file, scope: "repo", status: "read" });
+        }
+        else if (firstError) {
+            provenance.push({ file: firstError.file, scope: "repo", status: "error", error: firstError.error });
+        }
+        else {
+            provenance.push({ file, scope: "repo", status: "absent" });
         }
     }
     if (!deps.fetchRaw)
-        cacheSet("house-rules", [owner, repo], out);
-    return out;
+        cacheSet("house-rules", [owner, repo], { sources, provenance });
+    return { sources, provenance };
+}
+/** Fetch all existing house-rules files for a repo (best-effort, cached). */
+export async function fetchHouseRules(owner, repo, deps = {}) {
+    const { sources } = await fetchHouseRulesDetailed(owner, repo, deps);
+    return sources;
 }
 /** Fetch CONTRIBUTING.md raw text; returns undefined when the repo has none. */
 export async function fetchContributing(owner, repo) {
@@ -888,6 +1007,40 @@ export async function countStarterIssues(owner, repo) {
         return null;
     }
 }
+/**
+ * v0.19.0 (item 16): the wider starter label set for the candidate
+ * estimate. Repos that never adopted the classic "good first issue" /
+ * "help wanted" pair often label starter work one of these instead.
+ */
+export const STARTER_CANDIDATE_LABELS = [
+    "beginner friendly",
+    "beginner",
+    "easy",
+    "starter",
+    "first-timers-only",
+    "up-for-grabs",
+    "good-first-issue",
+];
+/**
+ * Fallback starter-candidate estimate, used only when the classic
+ * label count is exactly 0. One search call: open, unassigned issues
+ * under the wider starter label set. An estimate for display, never a
+ * score input; null when the search itself fails.
+ */
+export async function countStarterCandidates(owner, repo, deps = {}) {
+    const labels = STARTER_CANDIDATE_LABELS.map((l) => `"${l}"`).join(",");
+    const query = `repo:${owner}/${repo} type:issue state:open no:assignee label:${labels}`;
+    if (deps.searchCount)
+        return deps.searchCount(query);
+    try {
+        const q = encodeURIComponent(query);
+        const data = (await apiGet(`/search/issues?q=${q}&per_page=1`));
+        return data.total_count ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Detect a collaborators-only PR creation policy via the community metrics endpoint. */
 export async function detectRepoPolicy(owner, repo) {
     // Best-effort: no public API exposes pull_request_creation_policy directly,
@@ -1042,6 +1195,22 @@ export async function listRecentUnassignedIssues(owner, repo, cap = 25) {
     const items = await paginate(`/repos/${owner}/${repo}/issues?state=open&sort=created&direction=desc`, 100, 3);
     return toScanCandidates(items).slice(0, cap);
 }
+/**
+ * Default wall-time bound for `greenlight scan`, in seconds (v0.19.0,
+ * item 17): on mega-backlog repos the per-issue verdict pipeline ran
+ * about 25 minutes, so the scan stops with marked partial results when
+ * the budget runs out instead of running open-ended. Override per run
+ * with --max-time <seconds>.
+ */
+export const DEFAULT_SCAN_MAX_TIME_SEC = 600;
+/**
+ * Pure wall-time check for the scan loop (v0.19.0, item 17): true once
+ * the elapsed time since startedAtMs has reached the budget. Call with
+ * Date.now() for the nowMs argument. Exported for unit tests.
+ */
+export function scanBudgetExceeded(startedAtMs, maxTimeSec, nowMs) {
+    return nowMs - startedAtMs >= maxTimeSec * 1000;
+}
 /**
  * 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