@oss-autopilot/core 3.1.0 → 3.2.0

package/dist/commands/guidelines.d.ts

@@ -0,0 +1,67 @@
+import { type PRCommentBundle } from '../core/pr-comments-fetcher.js';
+export interface GuidelinesViewOutput {
+    repo: string;
+    /** Markdown content, or null when the repo has no guidelines stored. */
+    content: string | null;
+    /** UTF-8 byte size of `content`, or 0 when content is null. */
+    byteSize: number;
+    /** Whether a guidelines file exists for this repo. */
+    exists: boolean;
+    /** Where the guidelines would be persisted if a write happened now. */
+    storageMode: 'gist' | 'local-unavailable';
+}
+export interface GuidelinesStoreOutput {
+    repo: string;
+    byteSize: number;
+    stored: boolean;
+}
+export interface GuidelinesResetOutput {
+    repo: string;
+    /** True when an existing file was tombstoned, false when no file existed. */
+    deleted: boolean;
+}
+export interface FetchCorpusOutput {
+    repo: string;
+    bundles: PRCommentBundle[];
+    /** How many PRs were considered after recency + already-fetched filtering. */
+    prCount: number;
+    /** PRs skipped because `commentsFetchedAt` is already set (without --force). */
+    skipped: number;
+}
+interface RepoOption {
+    repo: string;
+}
+interface FetchCorpusOptions extends RepoOption {
+    /** Cap on PRs to process. Defaults to 5; capped at 10 to bound prompt size. */
+    limit?: number;
+    /** Re-fetch even when commentsFetchedAt is already set. */
+    forceRefetch?: boolean;
+}
+interface StoreOptions extends RepoOption {
+    content: string;
+}
+/** Read the per-repo guidelines for `repo`. Returns a `local-unavailable` envelope in non-Gist mode. */
+export declare function runGuidelinesView(options: RepoOption): Promise<GuidelinesViewOutput>;
+/**
+ * Persist per-repo guidelines for `repo`. Throws when not in Gist mode or
+ * when content exceeds the byte budget — the CLI surface relies on the
+ * outputJson error envelope to surface that to the host cleanly.
+ */
+export declare function runGuidelinesStore(options: StoreOptions): Promise<GuidelinesStoreOutput>;
+/** Tombstone the guidelines file for `repo`. */
+export declare function runGuidelinesReset(options: RepoOption): Promise<GuidelinesResetOutput>;
+/**
+ * Fetch raw PR comment bundles for the most recent merged/closed PRs in `repo`
+ * that haven't already been processed. Returns a serializable corpus for the
+ * host's extract-learnings prompt.
+ *
+ * Filters applied at the CLI layer (not the fetcher):
+ * - Only PRs in the requested `repo`
+ * - PRs older than 12 months are dropped (recency cliff)
+ * - PRs with `commentsFetchedAt` already set are skipped unless `forceRefetch`
+ * - Capped at `limit` (default 5, max 10)
+ *
+ * Stamps `commentsFetchedAt` on every PR that was successfully fetched.
+ */
+export declare function runFetchCorpus(options: FetchCorpusOptions): Promise<FetchCorpusOutput>;
+export {};

package/dist/commands/guidelines.js

@@ -0,0 +1,147 @@
+/**
+ * Guidelines CLI commands (#867 PR 4).
+ *
+ * `guidelines view`        — read the per-repo guidelines file from the Gist.
+ * `guidelines store`       — overwrite the per-repo guidelines file.
+ * `guidelines reset`       — tombstone the file so subsequent reads return null.
+ * `guidelines fetch-corpus` — pull raw PR comment bundles for the host's
+ *                              extract-learnings prompt to consume.
+ *
+ * The CLI layer is pure data plumbing — extraction is the host's job.
+ * Standalone-mode users see "not available" on store/reset/fetch-corpus
+ * because per-repo guidelines require Gist persistence to be useful.
+ */
+import { getStateManager, requireGitHubToken, getOctokit, GuidelinesNotAvailableError } from '../core/index.js';
+import { fetchPRCommentBundlesBatch } from '../core/pr-comments-fetcher.js';
+import { warn } from '../core/logger.js';
+const MODULE = 'guidelines';
+const REPO_ID_PATTERN = /^[^/]+\/[^/]+$/;
+const DEFAULT_FETCH_LIMIT = 5;
+const MAX_FETCH_LIMIT = 10;
+/**
+ * Cliff at 12 months: PRs older than this are excluded from corpus fetches
+ * (#867 design decision §5). Computed at call time, not module load.
+ */
+const RECENCY_CLIFF_MS = 365 * 24 * 60 * 60 * 1000;
+function validateRepo(repo) {
+    if (!REPO_ID_PATTERN.test(repo)) {
+        throw new Error(`Invalid repo identifier "${repo}". Expected "owner/repo" format.`);
+    }
+}
+/** Read the per-repo guidelines for `repo`. Returns a `local-unavailable` envelope in non-Gist mode. */
+export async function runGuidelinesView(options) {
+    validateRepo(options.repo);
+    const sm = getStateManager();
+    const content = sm.getGuidelines(options.repo);
+    return {
+        repo: options.repo,
+        content,
+        byteSize: content === null ? 0 : Buffer.byteLength(content, 'utf-8'),
+        exists: content !== null,
+        storageMode: sm.isGuidelinesAvailable() ? 'gist' : 'local-unavailable',
+    };
+}
+/**
+ * Persist per-repo guidelines for `repo`. Throws when not in Gist mode or
+ * when content exceeds the byte budget — the CLI surface relies on the
+ * outputJson error envelope to surface that to the host cleanly.
+ */
+export async function runGuidelinesStore(options) {
+    validateRepo(options.repo);
+    if (!options.content || options.content.length === 0) {
+        throw new Error('Cannot store empty content. Use `guidelines reset` to delete a guidelines file.');
+    }
+    const sm = getStateManager();
+    // Throws GuidelinesNotAvailableError or GuidelinesTooLargeError on failure.
+    sm.setGuidelines(options.repo, options.content);
+    return {
+        repo: options.repo,
+        byteSize: Buffer.byteLength(options.content, 'utf-8'),
+        stored: true,
+    };
+}
+/** Tombstone the guidelines file for `repo`. */
+export async function runGuidelinesReset(options) {
+    validateRepo(options.repo);
+    const sm = getStateManager();
+    if (!sm.isGuidelinesAvailable()) {
+        throw new GuidelinesNotAvailableError();
+    }
+    const existed = sm.getGuidelines(options.repo) !== null;
+    if (existed) {
+        sm.deleteGuidelines(options.repo);
+    }
+    return { repo: options.repo, deleted: existed };
+}
+/**
+ * Fetch raw PR comment bundles for the most recent merged/closed PRs in `repo`
+ * that haven't already been processed. Returns a serializable corpus for the
+ * host's extract-learnings prompt.
+ *
+ * Filters applied at the CLI layer (not the fetcher):
+ * - Only PRs in the requested `repo`
+ * - PRs older than 12 months are dropped (recency cliff)
+ * - PRs with `commentsFetchedAt` already set are skipped unless `forceRefetch`
+ * - Capped at `limit` (default 5, max 10)
+ *
+ * Stamps `commentsFetchedAt` on every PR that was successfully fetched.
+ */
+export async function runFetchCorpus(options) {
+    validateRepo(options.repo);
+    const limit = clampLimit(options.limit);
+    const sm = getStateManager();
+    const merged = sm.getMergedPRs() ?? [];
+    const closed = sm.getClosedPRs() ?? [];
+    const cutoffMs = Date.now() - RECENCY_CLIFF_MS;
+    /** Treat both merged and closed-without-merge PRs as candidates. */
+    const candidates = [
+        ...merged.map((pr) => ({ url: pr.url, timestamp: pr.mergedAt, alreadyFetched: !!pr.commentsFetchedAt })),
+        ...closed.map((pr) => ({ url: pr.url, timestamp: pr.closedAt, alreadyFetched: !!pr.commentsFetchedAt })),
+    ];
+    const repoUrlPrefix = `https://github.com/${options.repo}/`;
+    const eligible = candidates.filter((c) => {
+        if (!c.url.startsWith(repoUrlPrefix))
+            return false;
+        if (Date.parse(c.timestamp || '') < cutoffMs)
+            return false;
+        return true;
+    });
+    // Skipped count tracks ONLY the eligibility-passing PRs that were excluded
+    // for already-fetched. PRs filtered by repo/recency aren't "skipped" — they
+    // just don't apply to this repo or cutoff.
+    const skipped = options.forceRefetch ? 0 : eligible.filter((c) => c.alreadyFetched).length;
+    const toFetch = (options.forceRefetch ? eligible : eligible.filter((c) => !c.alreadyFetched))
+        // Most-recent first so the host always sees the freshest signal in its corpus window.
+        .sort((a, b) => Date.parse(b.timestamp || '') - Date.parse(a.timestamp || ''))
+        .slice(0, limit);
+    if (toFetch.length === 0) {
+        return { repo: options.repo, bundles: [], prCount: 0, skipped };
+    }
+    const token = requireGitHubToken();
+    const octokit = getOctokit(token);
+    const username = sm.getState().config.githubUsername;
+    if (!username) {
+        warn(MODULE, 'githubUsername is not set; bot/own-comment filtering will be incomplete');
+    }
+    const bundles = await fetchPRCommentBundlesBatch(octokit, toFetch.map((c) => c.url), username);
+    // Stamp commentsFetchedAt on each PR we successfully fetched — the bundle
+    // list mirrors the input order until paginateAll fan-out, so we mark on
+    // a per-bundle basis to be safe.
+    const now = new Date().toISOString();
+    for (const bundle of bundles) {
+        sm.markPRCommentsFetched(bundle.prUrl, now);
+    }
+    return {
+        repo: options.repo,
+        bundles,
+        prCount: bundles.length,
+        skipped,
+    };
+}
+function clampLimit(limit) {
+    if (limit === undefined)
+        return DEFAULT_FETCH_LIMIT;
+    if (!Number.isFinite(limit) || limit < 1)
+        return DEFAULT_FETCH_LIMIT;
+    return Math.min(limit, MAX_FETCH_LIMIT);
+}

package/dist/commands/index.d.ts

@@ -53,6 +53,14 @@ export { runInit } from './init.js';
 export { runSetup } from './setup.js';
 /** Check whether setup has been completed. */
 export { runCheckSetup } from './setup.js';
+/** Read the guidelines file for a repo. */
+export { runGuidelinesView } from './guidelines.js';
+/** Persist a guidelines file for a repo (overwrites on subsequent calls). */
+export { runGuidelinesStore } from './guidelines.js';
+/** Tombstone a guidelines file so subsequent reads return null. */
+export { runGuidelinesReset } from './guidelines.js';
+/** Fetch raw PR comment bundles for the host's extract-learnings prompt. */
+export { runFetchCorpus } from './guidelines.js';
 /** Show current persistence mode, Gist ID, and sync status. */
 export { runStateShow } from './state-cmd.js';
 /** Force push state to the backing Gist (no-op in local mode). */
@@ -78,6 +86,7 @@ export type { VetOutput, CommentsOutput, PostOutput, ClaimOutput, VetListOutput,
 export type { ConfigOutput, DetectFormattersOutput, ParseIssueListOutput, ParsedIssueItem, CheckIntegrationOutput, LocalReposOutput, } from '../formatters/json.js';
 export type { ShelveOutput, UnshelveOutput } from './shelve.js';
 export type { MoveOutput, MoveTarget } from './move.js';
+export type { GuidelinesViewOutput, GuidelinesStoreOutput, GuidelinesResetOutput, FetchCorpusOutput, } from './guidelines.js';
 export type { DismissOutput, UndismissOutput } from './dismiss.js';
 export type { InitOutput } from './init.js';
 export type { ConfigSetOutput, ConfigCommandOutput } from './config.js';

package/dist/commands/index.js

@@ -57,6 +57,15 @@ export { runInit } from './init.js';
 export { runSetup } from './setup.js';
 /** Check whether setup has been completed. */
 export { runCheckSetup } from './setup.js';
+// ── Per-Repo Guidelines (#867) ──────────────────────────────────────────────
+/** Read the guidelines file for a repo. */
+export { runGuidelinesView } from './guidelines.js';
+/** Persist a guidelines file for a repo (overwrites on subsequent calls). */
+export { runGuidelinesStore } from './guidelines.js';
+/** Tombstone a guidelines file so subsequent reads return null. */
+export { runGuidelinesReset } from './guidelines.js';
+/** Fetch raw PR comment bundles for the host's extract-learnings prompt. */
+export { runFetchCorpus } from './guidelines.js';
 // ── State Persistence ────────────────────────────────────────────────────────
 /** Show current persistence mode, Gist ID, and sync status. */
 export { runStateShow } from './state-cmd.js';

package/dist/core/gist-state-store.d.ts

@@ -200,7 +200,7 @@ export declare class GistStateStore {
     private fetchAndCache;
     /**
      * Parse `state.json` from the in-memory cache. Handles v2 migration
-     * by running through the Zod schema (which requires version: 3).
+     * by running through the Zod schema (which requires version: 4).
      * Falls back to fresh state if the file is missing or unparseable.
      */
     private parseStateFromCache;

package/dist/core/gist-state-store.js

@@ -33,7 +33,7 @@
  */
 import * as fs from 'fs';
 import { AgentStateSchema } from './state-schema.js';
-import { atomicWriteFileSync, createFreshState, migrateV1ToV2, migrateV2ToV3 } from './state-persistence.js';
+import { atomicWriteFileSync, createFreshState, migrateV1ToV2, migrateV2ToV3, migrateV3ToV4, } from './state-persistence.js';
 import { getGistIdPath, getStateCachePath } from './paths.js';
 import { debug, warn } from './logger.js';
 import { GistPermissionError, GistConcurrencyError, isRateLimitError } from './errors.js';
@@ -127,6 +127,8 @@ export class GistStateStore {
                             obj = migrateV1ToV2(record);
                         if (obj.version === 2)
                             obj = migrateV2ToV3(obj);
+                        if (obj.version === 3)
+                            obj = migrateV3ToV4(obj);
                     }
                     const cachedState = AgentStateSchema.parse(obj);
                     debug(MODULE, 'Loaded state from local cache in degraded mode');
@@ -197,6 +199,8 @@ export class GistStateStore {
                             obj = migrateV1ToV2(record);
                         if (obj.version === 2)
                             obj = migrateV2ToV3(obj);
+                        if (obj.version === 3)
+                            obj = migrateV3ToV4(obj);
                     }
                     const cachedState = AgentStateSchema.parse(obj);
                     debug(MODULE, 'bootstrapWithMigration: loaded state from local cache in degraded mode');
@@ -433,7 +437,7 @@ export class GistStateStore {
     }
     /**
      * Parse `state.json` from the in-memory cache. Handles v2 migration
-     * by running through the Zod schema (which requires version: 3).
+     * by running through the Zod schema (which requires version: 4).
      * Falls back to fresh state if the file is missing or unparseable.
      */
     parseStateFromCache() {
@@ -451,6 +455,8 @@ export class GistStateStore {
                     obj = migrateV1ToV2(record);
                 if (obj.version === 2)
                     obj = migrateV2ToV3(obj);
+                if (obj.version === 3)
+                    obj = migrateV3ToV4(obj);
             }
             return AgentStateSchema.parse(obj);
         }

package/dist/core/guidelines-store.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Per-repo guidelines persistence on top of the Gist freeform-document API
+ * (#867 PR 2).
+ *
+ * Each repo gets one markdown file named `guidelines--{owner}--{repo}.md`
+ * stored in the user's oss-autopilot Gist alongside `state.json`. The file
+ * holds extracted guidance from past PR review feedback. Reads and writes go
+ * through the in-memory cache that `GistStateStore` already maintains; the
+ * file persists on the next `push()`.
+ *
+ * The byte cap (8 KB) is enforced at write time to keep claim-time context
+ * injection small. Larger guidance should be split across categories or
+ * deferred to a follow-up consolidation pass.
+ */
+import type { GistStateStore } from './gist-state-store.js';
+import { OssAutopilotError } from './errors.js';
+/** Filename prefix shared by every guidelines file in the Gist. */
+export declare const GUIDELINES_FILE_PREFIX = "guidelines--";
+/** Hard byte budget for a single guidelines file (#867 design log §1). */
+export declare const GUIDELINES_MAX_BYTES = 8192;
+/**
+ * Convert an `owner/repo` pair into the filename used inside the Gist.
+ * Slashes are escaped as `--` so the filename is filesystem-safe and
+ * unambiguous when parsing back to a repo string.
+ */
+export declare function guidelinesFilename(repo: string): string;
+/**
+ * Inverse of {@link guidelinesFilename}. Returns null when the filename
+ * doesn't match the guidelines convention.
+ */
+export declare function repoFromGuidelinesFilename(filename: string): string | null;
+/**
+ * Thrown by {@link setGuidelines} / {@link deleteGuidelines} when the
+ * StateManager is not in Gist mode. Catch + degrade gracefully when surfacing
+ * to user-facing flows: per-repo guidelines simply aren't available without a
+ * Gist to store them in.
+ */
+export declare class GuidelinesNotAvailableError extends OssAutopilotError {
+    constructor(message?: string);
+}
+/**
+ * Thrown by {@link setGuidelines} when content exceeds {@link GUIDELINES_MAX_BYTES}.
+ * Surfaced separately from generic validation errors so consumers can prompt the
+ * user with a "trim or split" UX rather than a generic shape rejection.
+ */
+export declare class GuidelinesTooLargeError extends OssAutopilotError {
+    constructor(byteSize: number, max?: number);
+}
+/**
+ * Read the guidelines file for a repo from the Gist cache. Returns null when
+ * the store is not in Gist mode, the file does not exist, or the file is
+ * present but empty (treated as a tombstone left by {@link deleteGuidelines}).
+ */
+export declare function getGuidelines(store: GistStateStore | null, repo: string): string | null;
+/**
+ * Write or replace the guidelines file for a repo. Throws if the store is not
+ * in Gist mode or the content exceeds the byte budget.
+ */
+export declare function setGuidelines(store: GistStateStore | null, repo: string, content: string): void;
+/**
+ * Delete the guidelines file for a repo. No-op if the file doesn't exist.
+ * Implementation: write an empty string. The Gist API treats files with
+ * empty content as deletions on the next push, matching the existing
+ * single-source-of-truth model.
+ */
+export declare function deleteGuidelines(store: GistStateStore | null, repo: string): void;
+/**
+ * List every repo (as `owner/repo`) that has a non-empty guidelines file in
+ * the cache. Tombstoned (empty-content) files are excluded so the result
+ * matches what {@link getGuidelines} would actually return.
+ *
+ * Returns an empty array when the store is null or no files exist.
+ */
+export declare function listGuidelinesRepos(store: GistStateStore | null): string[];

package/dist/core/guidelines-store.js

@@ -0,0 +1,130 @@
+import { OssAutopilotError } from './errors.js';
+/** Filename prefix shared by every guidelines file in the Gist. */
+export const GUIDELINES_FILE_PREFIX = 'guidelines--';
+/** Hard byte budget for a single guidelines file (#867 design log §1). */
+export const GUIDELINES_MAX_BYTES = 8_192;
+/** Suffix appended to the filename so it renders as markdown in Gist. */
+const GUIDELINES_FILE_SUFFIX = '.md';
+/**
+ * Convert an `owner/repo` pair into the filename used inside the Gist.
+ * Slashes are escaped as `--` so the filename is filesystem-safe and
+ * unambiguous when parsing back to a repo string.
+ */
+export function guidelinesFilename(repo) {
+    if (!repo.includes('/')) {
+        throw new OssAutopilotError(`Invalid repo identifier "${repo}". Expected "owner/repo" format.`, 'INVALID_REPO_ID');
+    }
+    // GitHub forbids `/` in owner and repo, so the only `/` is the separator.
+    const [owner, name] = repo.split('/');
+    return `${GUIDELINES_FILE_PREFIX}${owner}--${name}${GUIDELINES_FILE_SUFFIX}`;
+}
+/**
+ * Inverse of {@link guidelinesFilename}. Returns null when the filename
+ * doesn't match the guidelines convention.
+ */
+export function repoFromGuidelinesFilename(filename) {
+    if (!filename.startsWith(GUIDELINES_FILE_PREFIX))
+        return null;
+    if (!filename.endsWith(GUIDELINES_FILE_SUFFIX))
+        return null;
+    const middle = filename.slice(GUIDELINES_FILE_PREFIX.length, filename.length - GUIDELINES_FILE_SUFFIX.length);
+    // Only split on the FIRST `--` separator. Repo names with `--` are rare
+    // but legal; owner names cannot contain `--` per GitHub username rules.
+    const sep = middle.indexOf('--');
+    if (sep === -1)
+        return null;
+    const owner = middle.slice(0, sep);
+    const name = middle.slice(sep + 2);
+    if (!owner || !name)
+        return null;
+    return `${owner}/${name}`;
+}
+/**
+ * Thrown by {@link setGuidelines} / {@link deleteGuidelines} when the
+ * StateManager is not in Gist mode. Catch + degrade gracefully when surfacing
+ * to user-facing flows: per-repo guidelines simply aren't available without a
+ * Gist to store them in.
+ */
+export class GuidelinesNotAvailableError extends OssAutopilotError {
+    constructor(message) {
+        super(message ??
+            'Per-repo guidelines require Gist persistence. Run `oss-autopilot setup` to enable Gist sync, then retry.', 'GUIDELINES_NOT_AVAILABLE');
+        this.name = 'GuidelinesNotAvailableError';
+    }
+}
+/**
+ * Thrown by {@link setGuidelines} when content exceeds {@link GUIDELINES_MAX_BYTES}.
+ * Surfaced separately from generic validation errors so consumers can prompt the
+ * user with a "trim or split" UX rather than a generic shape rejection.
+ */
+export class GuidelinesTooLargeError extends OssAutopilotError {
+    constructor(byteSize, max = GUIDELINES_MAX_BYTES) {
+        super(`Guidelines content is ${byteSize} bytes, exceeding the ${max}-byte cap. ` + `Trim or split across categories.`, 'GUIDELINES_TOO_LARGE');
+        this.name = 'GuidelinesTooLargeError';
+    }
+}
+/**
+ * Read the guidelines file for a repo from the Gist cache. Returns null when
+ * the store is not in Gist mode, the file does not exist, or the file is
+ * present but empty (treated as a tombstone left by {@link deleteGuidelines}).
+ */
+export function getGuidelines(store, repo) {
+    if (!store)
+        return null;
+    const content = store.getDocument(guidelinesFilename(repo));
+    if (content === null || content === '')
+        return null;
+    return content;
+}
+/**
+ * Write or replace the guidelines file for a repo. Throws if the store is not
+ * in Gist mode or the content exceeds the byte budget.
+ */
+export function setGuidelines(store, repo, content) {
+    if (!store)
+        throw new GuidelinesNotAvailableError();
+    const byteSize = Buffer.byteLength(content, 'utf-8');
+    if (byteSize > GUIDELINES_MAX_BYTES) {
+        throw new GuidelinesTooLargeError(byteSize);
+    }
+    store.setDocument(guidelinesFilename(repo), content);
+}
+/**
+ * Delete the guidelines file for a repo. No-op if the file doesn't exist.
+ * Implementation: write an empty string. The Gist API treats files with
+ * empty content as deletions on the next push, matching the existing
+ * single-source-of-truth model.
+ */
+export function deleteGuidelines(store, repo) {
+    if (!store)
+        throw new GuidelinesNotAvailableError();
+    // setDocument('') is interpreted as deletion; the GistStateStore push path
+    // already strips empty-content files before sending to the Gist API.
+    store.setDocument(guidelinesFilename(repo), '');
+}
+/**
+ * List every repo (as `owner/repo`) that has a non-empty guidelines file in
+ * the cache. Tombstoned (empty-content) files are excluded so the result
+ * matches what {@link getGuidelines} would actually return.
+ *
+ * Returns an empty array when the store is null or no files exist.
+ */
+export function listGuidelinesRepos(store) {
+    if (!store)
+        return [];
+    const filenames = store.listDocuments(GUIDELINES_FILE_PREFIX);
+    const repos = [];
+    for (const filename of filenames) {
+        const repo = repoFromGuidelinesFilename(filename);
+        // Skip files we can't decode (e.g. older formats, hand-edited) — better
+        // than throwing and breaking listGuidelinesRepos for everyone.
+        if (!repo)
+            continue;
+        // Skip tombstones — empty content means the user deleted these guidelines.
+        const content = store.getDocument(filename);
+        if (content === null || content === '')
+            continue;
+        repos.push(repo);
+    }
+    return repos.sort();
+}

package/dist/core/index.d.ts

@@ -4,6 +4,7 @@
  */
 export { StateManager, getStateManager, getStateManagerAsync, ensureGistPersistence, maybeCheckpoint, resetStateManager, type Stats, } from './state.js';
 export { GistStateStore } from './gist-state-store.js';
+export { guidelinesFilename, repoFromGuidelinesFilename, GUIDELINES_FILE_PREFIX, GUIDELINES_MAX_BYTES, GuidelinesNotAvailableError, GuidelinesTooLargeError, } from './guidelines-store.js';
 export { PRMonitor, type PRCheckFailure, type FetchPRsResult, computeDisplayLabel, classifyCICheck, classifyFailingChecks, } from './pr-monitor.js';
 export { IssueConversationMonitor } from './issue-conversation.js';
 export { isBotAuthor, isAcknowledgmentComment } from './comment-utils.js';

package/dist/core/index.js

@@ -4,6 +4,7 @@
  */
 export { StateManager, getStateManager, getStateManagerAsync, ensureGistPersistence, maybeCheckpoint, resetStateManager, } from './state.js';
 export { GistStateStore } from './gist-state-store.js';
+export { guidelinesFilename, repoFromGuidelinesFilename, GUIDELINES_FILE_PREFIX, GUIDELINES_MAX_BYTES, GuidelinesNotAvailableError, GuidelinesTooLargeError, } from './guidelines-store.js';
 export { PRMonitor, computeDisplayLabel, classifyCICheck, classifyFailingChecks, } from './pr-monitor.js';
 // Search/vetting now delegated to @oss-scout/core via commands/scout-bridge.ts
 export { IssueConversationMonitor } from './issue-conversation.js';

package/dist/core/pr-comments-fetcher.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Fetch the raw review-comment bundle for a PR (#867 PR 3).
+ *
+ * Returns reviews, inline review comments, and issue-level comments for a
+ * single PR with the contributor's own comments + bots filtered out. The
+ * `authorAssociation` field is preserved on every entry so the host's
+ * extraction prompt can weight maintainer voices (OWNER/MEMBER/COLLABORATOR)
+ * differently from community feedback (CONTRIBUTOR/NONE).
+ *
+ * No LLM calls happen here — this is the data layer feeding the host's
+ * `extract-learnings` prompt. The bundle structure is the contract; the
+ * extraction is the host's responsibility.
+ */
+import type { Octokit } from '@octokit/rest';
+/** A single review (top-level) on a PR. */
+export interface PRReviewEntry {
+    author: string;
+    authorAssociation: string;
+    body: string;
+    submittedAt: string;
+}
+/** An inline review comment (anchored to a file/line) on a PR. */
+export interface PRReviewCommentEntry {
+    author: string;
+    authorAssociation: string;
+    body: string;
+    path: string;
+    createdAt: string;
+}
+/** An issue-level comment posted on the PR thread. */
+export interface PRIssueCommentEntry {
+    author: string;
+    authorAssociation: string;
+    body: string;
+    createdAt: string;
+}
+/**
+ * The full comment bundle returned for a single PR. Field order matches
+ * the typical narrative arc of a PR review (top-level reviews → inline
+ * comments → general thread chatter), so the host's extraction prompt can
+ * walk the bundle linearly.
+ */
+export interface PRCommentBundle {
+    prUrl: string;
+    prTitle: string;
+    repo: string;
+    /** ISO-8601 timestamp the PR was merged or closed; whichever applies. */
+    mergedAt: string;
+    reviews: PRReviewEntry[];
+    reviewComments: PRReviewCommentEntry[];
+    issueComments: PRIssueCommentEntry[];
+}
+/**
+ * Fetch a single PR's comment bundle. Filters out the authenticated user's
+ * own comments and bots. Throws {@link ValidationError} on a non-PR URL.
+ */
+export declare function fetchPRCommentBundle(octokit: Octokit, prUrl: string, githubUsername: string): Promise<PRCommentBundle>;
+/**
+ * Fetch comment bundles for many PRs with a small concurrency cap (default 3).
+ *
+ * Failures on individual PRs are logged and skipped — the batch returns a
+ * shorter array rather than aborting. Rationale: extraction quality is
+ * already a partial-information problem (users contribute to many repos and
+ * many PRs), so a single 404 / rate limit on one PR should not deny the
+ * host the corpus from the other 4.
+ */
+export declare function fetchPRCommentBundlesBatch(octokit: Octokit, prUrls: string[], githubUsername: string, concurrency?: number): Promise<PRCommentBundle[]>;