@oss-autopilot/core 3.1.0 → 3.3.0

package/dist/core/auth.js

@@ -6,7 +6,7 @@
  *
  * Extracted from utils.ts under #1116.
  */
-import { execFileSync, execFile } from 'child_process';
+import { execFileSync, execFile } from 'node:child_process';
 import { ConfigurationError } from './errors.js';
 import { debug } from './logger.js';
 const MODULE = 'auth';
@@ -36,7 +36,7 @@ export function getGitHubToken() {
     }
     try {
         const token = execFileSync('gh', ['auth', 'token'], {
-            encoding: 'utf-8',
+            encoding: 'utf8',
             stdio: ['pipe', 'pipe', 'pipe'],
             timeout: 2000,
         }).trim();
@@ -101,7 +101,7 @@ export async function getGitHubTokenAsync() {
     }
     try {
         const token = await new Promise((resolve, reject) => {
-            execFile('gh', ['auth', 'token'], { encoding: 'utf-8', timeout: 2000 }, (error, stdout) => {
+            execFile('gh', ['auth', 'token'], { encoding: 'utf8', timeout: 2000 }, (error, stdout) => {
                 if (error) {
                     reject(error);
                 }
@@ -126,7 +126,7 @@ export async function getGitHubTokenAsync() {
  * Usernames must start with an alphanumeric character, can contain hyphens
  * (but not consecutive ones and not at the end), and be 1-39 characters.
  */
-const GITHUB_USERNAME_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38}$/;
+const GITHUB_USERNAME_RE = /^[\da-z](?:[\da-z]|-(?=[\da-z])){0,38}$/i;
 /**
  * Detect the authenticated GitHub username via the `gh` CLI.
  *
@@ -137,7 +137,7 @@ const GITHUB_USERNAME_RE = /^[a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38}$/
 export async function detectGitHubUsername() {
     try {
         const login = await new Promise((resolve, reject) => {
-            execFile('gh', ['api', 'user', '--jq', '.login'], { encoding: 'utf-8', timeout: 5000 }, (error, stdout) => {
+            execFile('gh', ['api', 'user', '--jq', '.login'], { encoding: 'utf8', timeout: 5000 }, (error, stdout) => {
                 if (error) {
                     reject(error);
                 }

package/dist/core/daily-logic.js

@@ -232,37 +232,41 @@ export function collectActionableIssues(prs, lastDigestAt) {
             let label;
             let type;
             switch (reason) {
-                case 'needs_response':
+                case 'needs_response': {
                     label = '[Needs Response]';
                     type = 'needs_response';
                     break;
-                case 'needs_changes':
+                }
+                case 'needs_changes': {
                     label = '[Needs Changes]';
                     type = 'needs_changes';
                     break;
+                }
                 case 'failing_ci': {
                     const checkInfo = pr.failingCheckNames.length > 0 ? ` (${pr.failingCheckNames.join(', ')})` : '';
                     label = `[CI Failing${checkInfo}]`;
                     type = 'ci_failing';
                     break;
                 }
-                case 'merge_conflict':
+                case 'merge_conflict': {
                     label = '[Merge Conflict]';
                     type = 'merge_conflict';
                     break;
+                }
                 case 'incomplete_checklist': {
                     const stats = pr.checklistStats ? ` (${pr.checklistStats.checked}/${pr.checklistStats.total})` : '';
                     label = `[Incomplete Checklist${stats}]`;
                     type = 'incomplete_checklist';
                     break;
                 }
-                default:
+                default: {
                     // Defensive fallback for ActionReason values not explicitly handled
                     // above (e.g. ci_not_running, needs_rebase, missing_required_files).
                     // These aren't in reasonOrder today but this guards future additions.
                     warn('daily-logic', `Unhandled ActionReason "${reason}" for PR ${pr.url} — falling back to needs_response`);
                     label = `[${reason}]`;
                     type = 'needs_response';
+                }
             }
             // A PR is "new" if it was created after the last daily digest (first time seen).
             // If there's no previous digest (first run) or createdAt is invalid, assume new.

package/dist/core/dates.js

@@ -30,9 +30,9 @@ export function formatRelativeTime(dateStr) {
     const diffMs = Date.now() - date.getTime();
     if (diffMs < 0)
         return 'just now';
-    const diffMins = Math.floor(diffMs / 60000);
-    const diffHours = Math.floor(diffMs / 3600000);
-    const diffDays = Math.floor(diffMs / 86400000);
+    const diffMins = Math.floor(diffMs / 60_000);
+    const diffHours = Math.floor(diffMs / 3_600_000);
+    const diffDays = Math.floor(diffMs / 86_400_000);
     if (diffMins < 60)
         return `${diffMins}m ago`;
     if (diffHours < 24)

package/dist/core/errors.d.ts

@@ -32,6 +32,20 @@ export declare class ValidationError extends OssAutopilotError {
 export declare class GistPermissionError extends ConfigurationError {
     constructor(message?: string);
 }
+/**
+ * Thrown when state.json fetched from a Gist is malformed or fails Zod
+ * validation. The Gist content is preserved as a `.rejected-<ts>.json` file
+ * in the local cache directory so the user can inspect or recover from it
+ * before the next push overwrites the Gist with fresh state.
+ *
+ * See issue #1201.
+ */
+export declare class GistCorruptError extends ConfigurationError {
+    readonly gistId: string;
+    readonly rejectedPath: string | null;
+    readonly cause: unknown;
+    constructor(gistId: string, rejectedPath: string | null, cause: unknown);
+}
 /**
  * Thrown when an optimistic compare-and-swap on state.json detects that
  * another process wrote the file between load and save. See issue #1030.
@@ -73,6 +87,21 @@ export declare function getHttpStatusCode(error: unknown): number | undefined;
 export declare function isRateLimitError(error: unknown): boolean;
 /** Return true for errors that should propagate (not degrade gracefully): rate limits, auth failures, abuse detection. */
 export declare function isRateLimitOrAuthError(err: unknown): boolean;
+/**
+ * Check if an error is a transient network/server-side failure that's safe
+ * to retry or fall back from (vs. a permanent error that should surface).
+ *
+ * Returns true for:
+ * - Node socket errors: ECONNRESET, ETIMEDOUT, ENETUNREACH, ENOTFOUND, ECONNREFUSED
+ * - HTTP 5xx (server errors)
+ * - AbortError (timeout)
+ *
+ * Returns false for everything else (including 4xx, schema errors, config errors).
+ *
+ * Used by {@link getStateManagerAsync} to decide whether a Gist init failure
+ * is recoverable enough to silently fall back to local-only mode (#1202).
+ */
+export declare function isTransientNetworkError(err: unknown): boolean;
 /**
  * Build a `.catch()` handler for the "non-fatal parallel fetch" pattern used
  * by daily.ts and dashboard-data.ts (#960). When a sibling fetch fails during

package/dist/core/errors.js

@@ -49,6 +49,31 @@ export class GistPermissionError extends ConfigurationError {
         this.name = 'GistPermissionError';
     }
 }
+/**
+ * Thrown when state.json fetched from a Gist is malformed or fails Zod
+ * validation. The Gist content is preserved as a `.rejected-<ts>.json` file
+ * in the local cache directory so the user can inspect or recover from it
+ * before the next push overwrites the Gist with fresh state.
+ *
+ * See issue #1201.
+ */
+export class GistCorruptError extends ConfigurationError {
+    gistId;
+    rejectedPath;
+    cause;
+    constructor(gistId, rejectedPath, cause) {
+        const causeMsg = cause instanceof Error ? cause.message : String(cause);
+        const recoverHint = rejectedPath
+            ? `\nCorrupt content preserved at: ${rejectedPath}\n` +
+                'Inspect or restore manually, then re-run. Falling back to a fresh state would overwrite your Gist.'
+            : '\nCould not preserve the rejected content; do not push without inspecting the Gist manually.';
+        super(`Gist ${gistId} state.json is corrupt or fails schema validation: ${causeMsg}${recoverHint}`);
+        this.gistId = gistId;
+        this.rejectedPath = rejectedPath;
+        this.cause = cause;
+        this.name = 'GistCorruptError';
+    }
+}
 /**
  * Thrown when an optimistic compare-and-swap on state.json detects that
  * another process wrote the file between load and save. See issue #1030.
@@ -128,6 +153,44 @@ export function isRateLimitOrAuthError(err) {
     }
     return false;
 }
+/**
+ * Check if an error is a transient network/server-side failure that's safe
+ * to retry or fall back from (vs. a permanent error that should surface).
+ *
+ * Returns true for:
+ * - Node socket errors: ECONNRESET, ETIMEDOUT, ENETUNREACH, ENOTFOUND, ECONNREFUSED
+ * - HTTP 5xx (server errors)
+ * - AbortError (timeout)
+ *
+ * Returns false for everything else (including 4xx, schema errors, config errors).
+ *
+ * Used by {@link getStateManagerAsync} to decide whether a Gist init failure
+ * is recoverable enough to silently fall back to local-only mode (#1202).
+ */
+export function isTransientNetworkError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const status = getHttpStatusCode(err);
+    if (typeof status === 'number' && status >= 500 && status < 600)
+        return true;
+    // Node socket-level errors expose `code`
+    const code = err.code;
+    if (typeof code === 'string') {
+        if (code === 'ECONNRESET' ||
+            code === 'ETIMEDOUT' ||
+            code === 'ENETUNREACH' ||
+            code === 'ENOTFOUND' ||
+            code === 'ECONNREFUSED' ||
+            code === 'EAI_AGAIN') {
+            return true;
+        }
+    }
+    // Octokit's RequestError surfaces the underlying name; fetch timeout is AbortError
+    const name = err.name;
+    if (typeof name === 'string' && (name === 'AbortError' || name === 'TimeoutError'))
+        return true;
+    return false;
+}
 /**
  * Build a `.catch()` handler for the "non-fatal parallel fetch" pattern used
  * by daily.ts and dashboard-data.ts (#960). When a sibling fetch fails during

package/dist/core/formatter-detection.js

@@ -4,8 +4,8 @@
  * Programmatically detects formatters/linters configured in a local repo directory
  * and diagnoses CI formatting failures from log output.
  */
-import * as fs from 'fs';
-import * as path from 'path';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 import { debug } from './logger.js';
 const MODULE = 'formatter-detection';
 // ── Prettier config file patterns ──────────────────────────────────────────
@@ -42,7 +42,7 @@ const FORMAT_SCRIPT_NAMES = ['lint:fix', 'format', 'fmt', 'lint', 'format:check'
 const CI_PATTERNS = [
     {
         formatter: 'prettier',
-        patterns: [/Code style issues found/i, /Forgot to run Prettier/i, /prettier --check/i],
+        patterns: [/code style issues found/i, /forgot to run prettier/i, /prettier --check/i],
     },
     {
         formatter: 'ruff',
@@ -50,19 +50,19 @@ const CI_PATTERNS = [
     },
     {
         formatter: 'black',
-        patterns: [/Oh no! .* files? would be reformatted/i, /black --check/i],
+        patterns: [/oh no! .* files? would be reformatted/i, /black --check/i],
     },
     {
         formatter: 'rustfmt',
-        patterns: [/Diff in .*\.rs/i, /rustfmt --check/i, /cargo fmt.*--check/i],
+        patterns: [/diff in .*\.rs/i, /rustfmt --check/i, /cargo fmt.*--check/i],
     },
     {
         formatter: 'biome',
-        patterns: [/biome check/i, /biome ci/i, /Found \d+ fixable diagnostics?/i],
+        patterns: [/biome check/i, /biome ci/i, /found \d+ fixable diagnostics?/i],
     },
     {
         formatter: 'eslint',
-        patterns: [/eslint.*--fix/i, /eslint.*\d+ problems?/i],
+        patterns: [/eslint.*--fix/i, /eslint\D+\d+ problems?/i],
     },
     {
         formatter: 'gofmt',
@@ -82,7 +82,7 @@ const CI_PATTERNS = [
  */
 function readJsonFile(filePath) {
     try {
-        const content = fs.readFileSync(filePath, 'utf-8');
+        const content = fs.readFileSync(filePath, 'utf8');
         return JSON.parse(content);
     }
     catch (err) {
@@ -95,7 +95,7 @@ function readJsonFile(filePath) {
  */
 function readTextFile(filePath) {
     try {
-        return fs.readFileSync(filePath, 'utf-8');
+        return fs.readFileSync(filePath, 'utf8');
     }
     catch (err) {
         debug(MODULE, `Failed to read ${filePath}: ${err instanceof Error ? err.message : String(err)}`);

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

@@ -121,6 +121,14 @@ export declare class GistStateStore {
     private readonly octokit;
     private lastRefreshAt;
     private static readonly REFRESH_THROTTLE_MS;
+    /**
+     * Most recent error from a `refreshFromGist()` attempt, or `null` when the
+     * last attempt succeeded or was skipped by the throttle. Lets callers
+     * (StateManager) distinguish "throttled, nothing new to see" from "fetch
+     * failed, you're now operating on stale state" without changing the
+     * existing boolean return contract (#1193).
+     */
+    lastRefreshError: Error | null;
     constructor(octokit: OctokitLike);
     /**
      * Bootstrap the Gist store: locate or create the backing Gist,
@@ -199,9 +207,17 @@ 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).
-     * Falls back to fresh state if the file is missing or unparseable.
+     * Parse `state.json` from the in-memory cache. Handles v1→v4 migration
+     * by running through the Zod schema (which requires version: 4).
+     *
+     * Throws {@link GistCorruptError} on parse or schema-validation failure.
+     * The corrupt raw content is preserved as `<state-cache-path>.rejected-<ts>`
+     * so the caller can recover (#1201).
+     *
+     * Returning fresh state on failure (the previous behavior) is unsafe in
+     * Gist mode because the next `push()` would overwrite the Gist with the
+     * empty fallback, silently destroying repoScores, dismissedIssues,
+     * guidelines pointers, and digest history.
      */
     private parseStateFromCache;
     /**

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

@@ -31,12 +31,12 @@
  *  cells, which matches the "last-write-wins by intent" model the rest of
  *  oss-autopilot already assumes for state.json.
  */
-import * as fs from 'fs';
+import * as fs from 'node: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';
+import { GistPermissionError, GistConcurrencyError, GistCorruptError, isRateLimitError } from './errors.js';
 const MODULE = 'gist-store';
 /**
  * Extract the ETag header from an Octokit response, tolerating both lower-
@@ -48,6 +48,24 @@ function extractEtag(headers) {
         return null;
     return headers.etag ?? headers.ETag ?? null;
 }
+/**
+ * Preserve corrupt Gist content for user recovery. Returns the path written,
+ * or null if the preservation itself failed (logged at warn). Mirrors the
+ * pattern in state-persistence.ts:401-407 for the local-state path.
+ *
+ * See {@link GistCorruptError} and issue #1201.
+ */
+function preserveRejectedGistContent(raw, gistId) {
+    try {
+        const rejectedPath = `${getStateCachePath()}.rejected-${Date.now()}`;
+        fs.writeFileSync(rejectedPath, raw, { encoding: 'utf8', mode: 0o600 });
+        return rejectedPath;
+    }
+    catch (err) {
+        warn(MODULE, `Could not preserve rejected Gist content for ${gistId}: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
 /** Well-known Gist description used for search-based discovery. */
 export const GIST_DESCRIPTION = 'oss-autopilot-state';
 /** Primary state file name inside the Gist. */
@@ -70,6 +88,14 @@ export class GistStateStore {
     octokit;
     lastRefreshAt = 0;
     static REFRESH_THROTTLE_MS = 30_000;
+    /**
+     * Most recent error from a `refreshFromGist()` attempt, or `null` when the
+     * last attempt succeeded or was skipped by the throttle. Lets callers
+     * (StateManager) distinguish "throttled, nothing new to see" from "fetch
+     * failed, you're now operating on stale state" without changing the
+     * existing boolean return contract (#1193).
+     */
+    lastRefreshError = null;
     constructor(octokit) {
         this.octokit = octokit;
     }
@@ -116,10 +142,12 @@ export class GistStateStore {
             // All API paths failed — enter degraded mode
             warn(MODULE, 'All Gist API paths failed, entering degraded mode', err);
             // Try reading from local cache file
+            const cachePath = getStateCachePath();
+            let cacheRaw = null;
             try {
-                const cachePath = getStateCachePath();
                 if (fs.existsSync(cachePath)) {
-                    let obj = JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
+                    cacheRaw = fs.readFileSync(cachePath, 'utf8');
+                    let obj = JSON.parse(cacheRaw);
                     // Chain migrations
                     if (typeof obj === 'object' && obj !== null) {
                         const record = obj;
@@ -127,6 +155,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');
@@ -134,7 +164,16 @@ export class GistStateStore {
                 }
             }
             catch (cacheErr) {
-                debug(MODULE, `Failed to read local cache in degraded mode: ${cacheErr}`);
+                // Promote to warn (#1201) and preserve corrupt cache so fresh-state
+                // fallback doesn't silently destroy recoverable data on next push.
+                if (cacheRaw) {
+                    const rejectedPath = preserveRejectedGistContent(cacheRaw, 'local-cache');
+                    warn(MODULE, `Local state cache failed to parse in degraded mode: ${cacheErr instanceof Error ? cacheErr.message : String(cacheErr)}. ` +
+                        `Corrupt cache preserved at: ${rejectedPath ?? '(could not preserve)'}`);
+                }
+                else {
+                    warn(MODULE, `Failed to read local cache in degraded mode: ${cacheErr instanceof Error ? cacheErr.message : String(cacheErr)}`);
+                }
             }
             // No cache either — return fresh state in degraded mode
             debug(MODULE, 'No local cache found, returning fresh state in degraded mode');
@@ -186,10 +225,12 @@ export class GistStateStore {
             // All API paths failed — enter degraded mode
             warn(MODULE, 'bootstrapWithMigration: all Gist API paths failed, entering degraded mode', err);
             // Try reading from local cache file
+            const cachePath = getStateCachePath();
+            let cacheRaw = null;
             try {
-                const cachePath = getStateCachePath();
                 if (fs.existsSync(cachePath)) {
-                    let obj = JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
+                    cacheRaw = fs.readFileSync(cachePath, 'utf8');
+                    let obj = JSON.parse(cacheRaw);
                     // Chain migrations
                     if (typeof obj === 'object' && obj !== null) {
                         const record = obj;
@@ -197,6 +238,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');
@@ -204,7 +247,14 @@ export class GistStateStore {
                 }
             }
             catch (cacheErr) {
-                debug(MODULE, `bootstrapWithMigration: failed to read local cache in degraded mode: ${cacheErr}`);
+                if (cacheRaw) {
+                    const rejectedPath = preserveRejectedGistContent(cacheRaw, 'local-cache');
+                    warn(MODULE, `bootstrapWithMigration: local cache failed to parse: ${cacheErr instanceof Error ? cacheErr.message : String(cacheErr)}. ` +
+                        `Corrupt cache preserved at: ${rejectedPath ?? '(could not preserve)'}`);
+                }
+                else {
+                    warn(MODULE, `bootstrapWithMigration: failed to read local cache: ${cacheErr instanceof Error ? cacheErr.message : String(cacheErr)}`);
+                }
             }
             // No cache either — use the provided existingState in degraded mode
             debug(MODULE, 'bootstrapWithMigration: no local cache found, returning existing state in degraded mode');
@@ -377,15 +427,19 @@ export class GistStateStore {
         if (!this.gistId)
             return false;
         const now = Date.now();
+        // Throttle hits are not failures — preserve any previous lastRefreshError
+        // for the caller to inspect.
         if (now - this.lastRefreshAt < GistStateStore.REFRESH_THROTTLE_MS)
             return false;
         try {
             await this.fetchAndCache(this.gistId);
             this.lastRefreshAt = now;
+            this.lastRefreshError = null;
             return true;
         }
         catch (err) {
             warn(MODULE, `refreshFromGist failed: ${err}`);
+            this.lastRefreshError = err instanceof Error ? err : new Error(String(err));
             return false;
         }
     }
@@ -432,9 +486,17 @@ export class GistStateStore {
         return state;
     }
     /**
-     * Parse `state.json` from the in-memory cache. Handles v2 migration
-     * by running through the Zod schema (which requires version: 3).
-     * Falls back to fresh state if the file is missing or unparseable.
+     * Parse `state.json` from the in-memory cache. Handles v1→v4 migration
+     * by running through the Zod schema (which requires version: 4).
+     *
+     * Throws {@link GistCorruptError} on parse or schema-validation failure.
+     * The corrupt raw content is preserved as `<state-cache-path>.rejected-<ts>`
+     * so the caller can recover (#1201).
+     *
+     * Returning fresh state on failure (the previous behavior) is unsafe in
+     * Gist mode because the next `push()` would overwrite the Gist with the
+     * empty fallback, silently destroying repoScores, dismissedIssues,
+     * guidelines pointers, and digest history.
      */
     parseStateFromCache() {
         const raw = this.cachedFiles.get(STATE_FILE_NAME);
@@ -451,12 +513,16 @@ export class GistStateStore {
                     obj = migrateV1ToV2(record);
                 if (obj.version === 2)
                     obj = migrateV2ToV3(obj);
+                if (obj.version === 3)
+                    obj = migrateV3ToV4(obj);
             }
             return AgentStateSchema.parse(obj);
         }
         catch (err) {
-            warn(MODULE, `Failed to parse state.json from Gist: ${err}`);
-            return createFreshState();
+            const rejectedPath = preserveRejectedGistContent(raw, this.gistId ?? 'unknown');
+            warn(MODULE, `Gist state.json failed to parse — refusing to overwrite with fresh state. ` +
+                `Corrupt content preserved at: ${rejectedPath ?? '(could not preserve)'}`);
+            throw new GistCorruptError(this.gistId ?? 'unknown', rejectedPath, err);
         }
     }
     /**
@@ -535,7 +601,7 @@ export class GistStateStore {
         try {
             const gistIdPath = getGistIdPath();
             if (fs.existsSync(gistIdPath)) {
-                const id = fs.readFileSync(gistIdPath, 'utf-8').trim();
+                const id = fs.readFileSync(gistIdPath, 'utf8').trim();
                 return id || null;
             }
         }

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[];