@oss-autopilot/core 3.0.1 → 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/commands/scout-bridge.d.ts

@@ -2,7 +2,18 @@
  * Bridge between oss-autopilot's AgentState and oss-scout's OssScout API.
  * Maps state fields and creates scout instances for search/vet commands.
  */
-import { type OssScout, type ScoutState } from '@oss-scout/core';
+import { type LinkedPR as ScoutLinkedPR, type OssScout, type ScoutState } from '@oss-scout/core';
+import type { LinkedPR } from '../core/linked-pr-classification.js';
+/**
+ * Convert scout 0.6.0's `LinkedPR` (separate `state` + `merged`) into the
+ * shape `classifyLinkedPR` expects (`state` already folded with `merged`).
+ *
+ * Scout exposes the raw GitHub fields verbatim, but the classifier was
+ * written before scout surfaced this data and uses a tri-state
+ * `'open' | 'closed' | 'merged'` enum. Folding `merged` into the state
+ * preserves the function's existing contract + tests.
+ */
+export declare function adaptScoutLinkedPR(scoutLinkedPR: ScoutLinkedPR | null | undefined): LinkedPR | null;
 /**
  * Build a ScoutState from the current AgentState.
  * Maps oss-autopilot's config and state fields to oss-scout's state format.

package/dist/commands/scout-bridge.js

@@ -5,6 +5,23 @@
 import { createScout } from '@oss-scout/core';
 import { getStateManager, requireGitHubToken } from '../core/index.js';
 import { loadSkippedIssues } from './skip-file-parser.js';
+/**
+ * Convert scout 0.6.0's `LinkedPR` (separate `state` + `merged`) into the
+ * shape `classifyLinkedPR` expects (`state` already folded with `merged`).
+ *
+ * Scout exposes the raw GitHub fields verbatim, but the classifier was
+ * written before scout surfaced this data and uses a tri-state
+ * `'open' | 'closed' | 'merged'` enum. Folding `merged` into the state
+ * preserves the function's existing contract + tests.
+ */
+export function adaptScoutLinkedPR(scoutLinkedPR) {
+    if (!scoutLinkedPR)
+        return null;
+    return {
+        author: { login: scoutLinkedPR.author },
+        state: scoutLinkedPR.merged ? 'merged' : scoutLinkedPR.state,
+    };
+}
 /**
  * Build a ScoutState from the current AgentState.
  * Maps oss-autopilot's config and state fields to oss-scout's state format.
@@ -31,6 +48,8 @@ export function buildScoutState() {
             broadPhaseDelayMs: 90000,
             skipBroadWhenSufficientResults: 15,
             persistence: config.persistence,
+            slmTriageModel: config.slmTriageModel,
+            slmTriageHost: config.slmTriageHost,
         },
         repoScores: state.repoScores,
         starredRepos: config.starredRepos,

package/dist/commands/vet-list.js

@@ -3,11 +3,11 @@
  * Re-vets all available issues in a curated issue list file via @oss-scout/core.
  */
 import * as fs from 'fs';
-import { createAutopilotScout } from './scout-bridge.js';
+import { adaptScoutLinkedPR, createAutopilotScout } from './scout-bridge.js';
 import { runParseList, pruneIssueList } from './parse-list.js';
 import { detectIssueList } from './startup.js';
 import { computeSuccessGrade, gradeFromCandidate } from '../core/issue-grading.js';
-import { getStateManager } from '../core/index.js';
+import { getStateManager, classifyLinkedPR } from '../core/index.js';
 const UNKNOWN_GRADE = computeSuccessGrade({ avgResponseDays: null, mergeRate: null, daysSinceLastCommit: null });
 const KNOWN_SKIP_REASONS = new Set([
     'issue_closed',
@@ -117,6 +117,11 @@ export async function runVetList(options = {}) {
                     projectHealth: candidate.projectHealth,
                     getRepoScore: (repo) => getStateManager().getRepoScore(repo),
                 });
+                const userLogin = getStateManager().getState().config.githubUsername;
+                const linkedPRClassification = classifyLinkedPR({
+                    linkedPR: adaptScoutLinkedPR(candidate.vettingResult.linkedPR),
+                    userLogin,
+                });
                 const vetResult = {
                     issue: {
                         repo: candidate.issue.repo,
@@ -130,6 +135,9 @@ export async function runVetList(options = {}) {
                     reasonsToSkip: candidate.reasonsToSkip,
                     projectHealth: candidate.projectHealth,
                     vettingResult: candidate.vettingResult,
+                    antiLLMPolicy: candidate.antiLLMPolicy,
+                    linkedPRClassification,
+                    slmTriage: candidate.slmTriage ?? null,
                     grade,
                 };
                 results.push({

package/dist/commands/vet.js

@@ -5,7 +5,8 @@
 import { createAutopilotScout } from './scout-bridge.js';
 import { ISSUE_URL_PATTERN, validateGitHubUrl, validateUrl } from './validation.js';
 import { gradeFromCandidate } from '../core/issue-grading.js';
-import { getStateManager } from '../core/index.js';
+import { getStateManager, classifyLinkedPR } from '../core/index.js';
+import { adaptScoutLinkedPR } from './scout-bridge.js';
 /**
  * Vet a specific GitHub issue for claimability and project health.
  *
@@ -24,6 +25,11 @@ export async function runVet(options) {
         projectHealth: candidate.projectHealth,
         getRepoScore: (repo) => getStateManager().getRepoScore(repo),
     });
+    const userLogin = getStateManager().getState().config.githubUsername;
+    const linkedPRClassification = classifyLinkedPR({
+        linkedPR: adaptScoutLinkedPR(candidate.vettingResult.linkedPR),
+        userLogin,
+    });
     return {
         issue: {
             repo: candidate.issue.repo,
@@ -37,6 +43,9 @@ export async function runVet(options) {
         reasonsToSkip: candidate.reasonsToSkip,
         projectHealth: candidate.projectHealth,
         vettingResult: candidate.vettingResult,
+        antiLLMPolicy: candidate.antiLLMPolicy,
+        linkedPRClassification,
+        slmTriage: candidate.slmTriage ?? null,
         grade,
     };
 }

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';