@oss-autopilot/core 3.4.1 → 3.5.0

package/dist/core/compliance-score.js

@@ -0,0 +1,277 @@
+/**
+ * PR compliance scoring (#1245).
+ *
+ * Extracted from `agents/pr-compliance-checker.md`'s in-prompt scoring
+ * tables so the weights, thresholds, and per-check rules are
+ * deterministic, unit-testable, and tunable without editing markdown.
+ * Same architectural shape as success-grade (#858), linked-PR
+ * classifier (#910), and anti-AI scan (#911).
+ *
+ * The function intentionally does not fetch PR data — callers (the MCP
+ * tool, the CLI command, the agent) supply pre-fetched metadata so the
+ * score is reproducible against fixture data and the same input shape
+ * works for both live PRs and historical replay.
+ */
+/**
+ * After how many days a closed-issue reference flips from "warn"
+ * (probably still relevant) to "fail" (probably stale). Exported so
+ * callers can document the cutoff (#1246).
+ */
+export const CLOSED_ISSUE_RECENT_DAYS = 30;
+const WEIGHTS = {
+    issueReference: 25,
+    description: 25,
+    focusedChanges: 20,
+    tests: 15,
+    title: 10,
+    branch: 5,
+};
+const STATUS_TO_FRACTION = {
+    pass: 1,
+    warn: 0.5,
+    fail: 0,
+};
+// Pull canonical rubric thresholds from the single source of truth
+// (#1252). Re-exported so existing consumers of compliance-score
+// (tests, agent prompts) keep working without touching their imports.
+import { TITLE_LENGTH_BUDGET, FOCUSED_CHANGES_THRESHOLDS } from './pr-quality-rubric.js';
+/** Title byte budget — Conventional Commits style fits comfortably under 72. */
+export { TITLE_LENGTH_BUDGET } from './pr-quality-rubric.js';
+/** "Focused changes" thresholds. Source of truth lives in pr-quality-rubric.ts. */
+export const FOCUSED_CHANGES = FOCUSED_CHANGES_THRESHOLDS;
+/** Score → rating cutoffs. */
+export const RATING_CUTOFFS = {
+    ready: 90,
+    minor: 75,
+    fixFirst: 60,
+};
+/**
+ * Detect a closing or referencing keyword in the PR body. GitHub's own
+ * auto-close keyword set: close, closes, closed, fix, fixes, fixed,
+ * resolve, resolves, resolved.
+ */
+const CLOSING_KEYWORDS = /\b(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#\d+/i;
+const REFERENCE_KEYWORDS = /\b(?:relates?\s+to|see|refs?|references?)\s+#\d+/i;
+const ISSUE_URL = /https?:\/\/github\.com\/[^/]+\/[^/]+\/issues\/\d+/i;
+/**
+ * If verified linked-issue state is available, derive a status from
+ * the worst single reference (#1246 Improvement B). Returns `null` when
+ * no validation data is supplied — the caller falls back to the
+ * regex-only result.
+ *
+ * Failure modes the precedence ranks (worst first):
+ *   1. `not_found` — referenced issue doesn't exist (typo, wrong repo)
+ *   2. `closed` more than {@link CLOSED_ISSUE_RECENT_DAYS} days ago
+ *   3. `closed` recently — probably still relevant but worth confirming
+ *   4. `open` cross-repo — caller should sanity-check the link applies
+ *   5. `open` same-repo — canonical pass.
+ */
+function evaluateLinkedIssues(weight, linkedIssues) {
+    if (linkedIssues.length === 0)
+        return null;
+    const notFound = linkedIssues.find((li) => li.state === 'not_found');
+    if (notFound) {
+        const tag = notFound.crossRepo ? `${notFound.repo}#${notFound.number}` : `#${notFound.number}`;
+        return {
+            status: 'fail',
+            weight,
+            detail: `linked issue ${tag} does not exist — typo or wrong repo?`,
+        };
+    }
+    // If every entry is unverifiable (and none were found-and-known-bad),
+    // neither pass nor fail — return a `warn` so the caller surfaces the
+    // gap without downgrading a valid PR's score. A rate-limit on a single
+    // reference shouldn't make a perfectly good PR look broken. Mixed sets
+    // fall through to the verifiable-state checks below; unverifiable
+    // entries are silently dropped from the worst-of-precedence ranking.
+    const verifiable = linkedIssues.filter((li) => li.state !== 'unverifiable');
+    if (verifiable.length === 0) {
+        return {
+            status: 'warn',
+            weight,
+            detail: `linked issue${linkedIssues.length > 1 ? 's' : ''} could not be verified (rate limit or network) — confirm manually`,
+        };
+    }
+    const staleClosed = verifiable.find((li) => li.state === 'closed' && (li.closedDaysAgo ?? 0) > CLOSED_ISSUE_RECENT_DAYS);
+    if (staleClosed) {
+        return {
+            status: 'fail',
+            weight,
+            detail: `linked issue #${staleClosed.number} has been closed for ` +
+                `${staleClosed.closedDaysAgo} days — reference is probably stale`,
+        };
+    }
+    const recentClosed = verifiable.find((li) => li.state === 'closed');
+    if (recentClosed) {
+        return {
+            status: 'warn',
+            weight,
+            detail: `linked issue #${recentClosed.number} was closed ` +
+                `${recentClosed.closedDaysAgo ?? '?'} days ago — confirm this PR is still relevant`,
+        };
+    }
+    const crossRepo = verifiable.find((li) => li.crossRepo);
+    if (crossRepo) {
+        return {
+            status: 'warn',
+            weight,
+            detail: `cross-repo reference ${crossRepo.repo}#${crossRepo.number} — ` +
+                `verify the linked issue applies to changes in this repo`,
+        };
+    }
+    return {
+        status: 'pass',
+        weight,
+        detail: `linked issue${verifiable.length > 1 ? 's' : ''} verified open`,
+    };
+}
+function checkIssueReference(meta, repoContext) {
+    const weight = WEIGHTS.issueReference;
+    const hasClosing = CLOSING_KEYWORDS.test(meta.body);
+    // The parser's `linkedIssues` already captures cross-repo (`owner/repo#N`)
+    // and direct-URL references that the same-repo regex misses. Treat any
+    // parsed reference as "a reference exists" so cross-repo links don't
+    // collapse to a fail just because they didn't match the bare-ref regex.
+    const hasReference = hasClosing ||
+        REFERENCE_KEYWORDS.test(meta.body) ||
+        ISSUE_URL.test(meta.body) ||
+        (repoContext?.linkedIssues?.length ?? 0) > 0;
+    if (!hasReference) {
+        return { status: 'fail', weight, detail: 'no issue reference' };
+    }
+    // When the caller pre-fetched the linked issues' state, that
+    // verification supersedes the regex-only signal — a `Closes #999`
+    // pointing at a non-existent issue must not score as pass.
+    const verified = repoContext?.linkedIssues ? evaluateLinkedIssues(weight, repoContext.linkedIssues) : null;
+    if (verified)
+        return verified;
+    if (hasClosing) {
+        return { status: 'pass', weight, detail: 'closing keyword present' };
+    }
+    return {
+        status: 'warn',
+        weight,
+        detail: 'issue referenced without a closing keyword',
+    };
+}
+const SECTION_WHAT = /(?:^|\n)#{1,3}\s*(?:summary|overview|what(?:\s+changed)?)\b/i;
+const SECTION_WHY = /(?:^|\n)#{1,3}\s*(?:why|motivation|context|background|rationale)\b/i;
+const SECTION_TEST = /(?:^|\n)#{1,3}\s*(?:test\s*plan|how\s+to\s+test|testing|tests?)\b/i;
+function checkDescription(meta) {
+    const weight = WEIGHTS.description;
+    const trimmed = meta.body.trim();
+    if (trimmed.length === 0) {
+        return { status: 'fail', weight, detail: 'description is empty' };
+    }
+    const what = SECTION_WHAT.test(meta.body);
+    const why = SECTION_WHY.test(meta.body);
+    const test = SECTION_TEST.test(meta.body);
+    const present = [what, why, test].filter(Boolean).length;
+    if (present === 3) {
+        return { status: 'pass', weight, detail: 'what / why / test sections present' };
+    }
+    if (present >= 1 || trimmed.length >= 80) {
+        return {
+            status: 'warn',
+            weight,
+            detail: `${present} of 3 sections present (what/why/test)`,
+        };
+    }
+    return { status: 'fail', weight, detail: 'minimal description, no recognizable sections' };
+}
+function checkFocusedChanges(meta) {
+    const weight = WEIGHTS.focusedChanges;
+    const lines = meta.additions + meta.deletions;
+    const detail = `${meta.filesChangedCount} files, ${lines} lines`;
+    if (meta.filesChangedCount < FOCUSED_CHANGES.passFiles && lines < FOCUSED_CHANGES.passLines) {
+        return { status: 'pass', weight, detail };
+    }
+    if (meta.filesChangedCount > FOCUSED_CHANGES.warnFiles || lines > FOCUSED_CHANGES.warnLines) {
+        return { status: 'fail', weight, detail: `${detail} — needs splitting` };
+    }
+    return { status: 'warn', weight, detail };
+}
+const TEST_FILE_PATTERN = /(?:^|\/)(?:tests?|__tests__|spec)\/|\.(?:test|spec)\.[jt]sx?$|\.test_/i;
+function checkTests(meta, repoContext) {
+    const weight = WEIGHTS.tests;
+    const hasTestFile = meta.files.some((f) => TEST_FILE_PATTERN.test(f));
+    if (hasTestFile) {
+        return { status: 'pass', weight, detail: 'test file(s) touched' };
+    }
+    if (repoContext?.hasTestInfrastructure === false) {
+        return {
+            status: 'warn',
+            weight,
+            detail: 'no tests, but project has no visible test infrastructure',
+        };
+    }
+    return { status: 'fail', weight, detail: 'no test files in a test-requiring project' };
+}
+const CONVENTIONAL_TITLE = /^(?:feat|fix|chore|docs|refactor|test|perf|build|ci|style|revert)(?:\([^)]+\))?!?:\s+\S/i;
+const VAGUE_EXACT = new Set(['wip', 'test', 'hello', 'tmp', 'temp', 'untitled']);
+const ASDF_ONLY = /^[asdfqwer]+$/i;
+const NON_DESCRIPTIVE_UPDATE = /^update\s+\S+\s*$/i;
+function isVagueTitle(title) {
+    const trimmed = title.trim();
+    if (VAGUE_EXACT.has(trimmed.toLowerCase()))
+        return true;
+    if (ASDF_ONLY.test(trimmed))
+        return true;
+    if (NON_DESCRIPTIVE_UPDATE.test(trimmed))
+        return true;
+    return false;
+}
+function checkTitle(meta) {
+    const weight = WEIGHTS.title;
+    const len = meta.title.length;
+    if (isVagueTitle(meta.title)) {
+        return { status: 'fail', weight, detail: 'vague or placeholder title' };
+    }
+    if (len > TITLE_LENGTH_BUDGET) {
+        return { status: 'warn', weight, detail: `title is ${len} chars (budget: ${TITLE_LENGTH_BUDGET})` };
+    }
+    if (CONVENTIONAL_TITLE.test(meta.title)) {
+        return { status: 'pass', weight, detail: 'descriptive, conventional, within budget' };
+    }
+    return { status: 'warn', weight, detail: 'descriptive but not conventional commit format' };
+}
+const PATCH_NUM_BRANCH = /^patch-\d+$/i;
+const ROOT_BRANCH = /^(?:main|master)$/i;
+function checkBranch(meta) {
+    const weight = WEIGHTS.branch;
+    if (ROOT_BRANCH.test(meta.branch) || PATCH_NUM_BRANCH.test(meta.branch)) {
+        return { status: 'fail', weight, detail: `non-descriptive branch name "${meta.branch}"` };
+    }
+    // Treat anything containing a separator (`/`, `-`, `_`) as descriptive.
+    if (/[/_-]/.test(meta.branch)) {
+        return { status: 'pass', weight, detail: meta.branch };
+    }
+    return { status: 'warn', weight, detail: `branch "${meta.branch}" lacks a clear separator` };
+}
+function ratingFor(score) {
+    if (score >= RATING_CUTOFFS.ready)
+        return { rating: 'ready', emoji: '🌟' };
+    if (score >= RATING_CUTOFFS.minor)
+        return { rating: 'minor', emoji: '✅' };
+    if (score >= RATING_CUTOFFS.fixFirst)
+        return { rating: 'fix_first', emoji: '⚠️' };
+    return { rating: 'significant_work', emoji: '❌' };
+}
+/**
+ * Compute a compliance score from PR metadata, optionally fine-tuned by
+ * repo context (#1245). Pure function — no I/O, no global state.
+ */
+export function computeComplianceScore(meta, repoContext) {
+    const checks = {
+        issueReference: checkIssueReference(meta, repoContext),
+        description: checkDescription(meta),
+        focusedChanges: checkFocusedChanges(meta),
+        tests: checkTests(meta, repoContext),
+        title: checkTitle(meta),
+        branch: checkBranch(meta),
+    };
+    const weighted = Object.values(checks).reduce((acc, check) => acc + STATUS_TO_FRACTION[check.status] * check.weight, 0);
+    const score = Math.round(weighted);
+    const { rating, emoji } = ratingFor(score);
+    return { score, rating, emoji, checks };
+}

package/dist/core/config-registry.js

@@ -191,6 +191,18 @@ export const CONFIG_KEY_REGISTRY = [
         settableVia: 'setup',
         valueHint: 'true|false',
     },
+    {
+        key: 'healthCheckFreshnessMinutes',
+        description: 'Suppress the SessionStart PR health one-liner when the cached digest is older than this many minutes. The line silently disappears between /oss runs, so what remains is always current. Defaults to 30 minutes (#1255).',
+        settableVia: 'setup',
+        valueHint: 'positive integer',
+    },
+    {
+        key: 'reviewMaxPasses',
+        description: 'Convergence cap for the multi-agent review loop in workflows/dispatch-review.md. Optional; falls back to per-mode defaults (5 for diff, 3 for plan) when unset (#1275).',
+        settableVia: 'setup',
+        valueHint: 'positive integer',
+    },
     // ── Setup-only completion flag ──────────────────────────────────────
     {
         key: 'complete',

package/dist/core/contributing.d.ts

@@ -0,0 +1,52 @@
+/**
+ * CONTRIBUTING.md requirement extraction (#1279).
+ *
+ * Extracted from `workflows/draft-first-workflow.md` Step 1d so the
+ * heuristic that pulls actionable requirements out of a project's
+ * CONTRIBUTING file lives in typed code instead of workflow prose.
+ * Same architectural shape as compliance-score (#1245), repo-vet
+ * (#1242), strategy (#1243), and the recent #1252 / #1264 / #1286
+ * extractions.
+ *
+ * Pure typed helper — no I/O. Callers (the workflow runner, the
+ * `pr-compliance-checker` agent) read the file themselves and pass
+ * the contents in. The extraction step is heuristic regex matching
+ * over headings + bullet phrases; it intentionally over-recalls
+ * (some false positives) rather than under-recalling.
+ *
+ * Out of scope (deferred per #1279):
+ *  - `findContributingFile(repoPath)` — file-system search for the
+ *    guidelines file at one of seven well-known locations.
+ *  - `verifyRequirements(...)` — diff-aware satisfaction check per
+ *    requirement.
+ *  - `checkContributingCompliance(...)` — convenience wrapper that
+ *    calls all three.
+ *
+ * The remaining pieces plumb `extractRequirements()` into specific
+ * surfaces; each ships independently.
+ */
+export type ContributingCategory = 'tests' | 'documentation' | 'changelog' | 'code_style' | 'commit_format' | 'cla_dco' | 'branch_target' | 'scope';
+export interface ContributingRequirement {
+    category: ContributingCategory;
+    /** One-line description of what the project asks for. */
+    description: string;
+    /**
+     * The line that surfaced the requirement, lightly trimmed. Useful
+     * for explainability in agent output ("the project's CONTRIBUTING
+     * says: …").
+     */
+    evidence: string;
+}
+/**
+ * Extract structured requirements from a CONTRIBUTING.md (or
+ * similar) text. Each rule fires at most once per document — a
+ * project that says "tests are required" twice still surfaces a
+ * single tests requirement.
+ */
+export declare function extractRequirements(content: string): ContributingRequirement[];
+/**
+ * Convenience: dedupe a requirement list down to one entry per
+ * category. Useful for top-line summaries where the agent doesn't
+ * need to render every matched rule.
+ */
+export declare function dedupeByCategory(requirements: readonly ContributingRequirement[]): ContributingRequirement[];

package/dist/core/contributing.js

@@ -0,0 +1,139 @@
+/**
+ * CONTRIBUTING.md requirement extraction (#1279).
+ *
+ * Extracted from `workflows/draft-first-workflow.md` Step 1d so the
+ * heuristic that pulls actionable requirements out of a project's
+ * CONTRIBUTING file lives in typed code instead of workflow prose.
+ * Same architectural shape as compliance-score (#1245), repo-vet
+ * (#1242), strategy (#1243), and the recent #1252 / #1264 / #1286
+ * extractions.
+ *
+ * Pure typed helper — no I/O. Callers (the workflow runner, the
+ * `pr-compliance-checker` agent) read the file themselves and pass
+ * the contents in. The extraction step is heuristic regex matching
+ * over headings + bullet phrases; it intentionally over-recalls
+ * (some false positives) rather than under-recalling.
+ *
+ * Out of scope (deferred per #1279):
+ *  - `findContributingFile(repoPath)` — file-system search for the
+ *    guidelines file at one of seven well-known locations.
+ *  - `verifyRequirements(...)` — diff-aware satisfaction check per
+ *    requirement.
+ *  - `checkContributingCompliance(...)` — convenience wrapper that
+ *    calls all three.
+ *
+ * The remaining pieces plumb `extractRequirements()` into specific
+ * surfaces; each ships independently.
+ */
+/**
+ * Heuristic patterns. Each rule fires once if any line in the
+ * document matches its pattern. Rules are ordered by specificity:
+ * commit-format and CLA matchers are precise; the broader
+ * documentation/scope rules sit at the end so they don't shadow
+ * narrower categories.
+ */
+const RULES = [
+    {
+        category: 'tests',
+        pattern: /\b(?:add|include|write|provide|cover\s+with)\s+(?:unit\s+)?tests?\b/i,
+        description: 'Add tests covering the change',
+    },
+    {
+        category: 'tests',
+        pattern: /\btest(?:s|ing)?\s+(?:are|is)\s+required\b/i,
+        description: 'Tests are required',
+    },
+    {
+        category: 'documentation',
+        pattern: /\b(?:update|add|provide)\s+(?:the\s+)?(?:docs?|documentation)\b/i,
+        description: 'Update documentation when behavior changes',
+    },
+    {
+        category: 'changelog',
+        pattern: /\b(?:add|include|update)\s+(?:an?\s+)?(?:entry\s+(?:to|in)\s+)?(?:the\s+)?(?:changelog|CHANGELOG\.md|changeset)\b/i,
+        description: 'Add a changelog entry / changeset',
+    },
+    {
+        category: 'changelog',
+        pattern: /\bchange(?:log|set)\s+(?:entry|file)\s+(?:is\s+)?required\b/i,
+        description: 'Changelog entry / changeset is required',
+    },
+    {
+        category: 'code_style',
+        pattern: /\b(?:run|use)\s+(?:the\s+)?(?:linter|formatter|prettier|eslint|biome|black|ruff|gofmt|rustfmt|clang-format)\b/i,
+        description: 'Run the project formatter / linter before submitting',
+    },
+    {
+        category: 'commit_format',
+        pattern: /\bconventional\s+commits?\b/i,
+        description: 'Use Conventional Commits format',
+    },
+    {
+        category: 'commit_format',
+        pattern: /\bcommit\s+messages?\s+(?:must|should|need)\b/i,
+        description: 'Project enforces a commit-message convention',
+    },
+    {
+        category: 'cla_dco',
+        pattern: /\b(?:CLA|contributor\s+license\s+agreement|DCO|sign(?:ed)?-off-by|signoff)\b/i,
+        description: 'Contributor license / DCO sign-off required',
+    },
+    {
+        category: 'branch_target',
+        pattern: /\b(?:open|submit|target)\s+(?:a\s+)?(?:PR|pull\s+request).*?(?:against|to|targeting)\s+(?:the\s+)?(\S+)\s+branch\b/i,
+        description: 'PR must target a specific branch',
+    },
+    {
+        category: 'scope',
+        pattern: /\b(?:one\s+(?:logical\s+)?change|focused\s+PR|atomic\s+commits?)\b/i,
+        description: 'Keep PRs focused / atomic',
+    },
+];
+/**
+ * Extract structured requirements from a CONTRIBUTING.md (or
+ * similar) text. Each rule fires at most once per document — a
+ * project that says "tests are required" twice still surfaces a
+ * single tests requirement.
+ */
+export function extractRequirements(content) {
+    if (!content || content.trim().length === 0)
+        return [];
+    const lines = content.split(/\r?\n/);
+    const out = [];
+    const seenCategoriesPerRule = new Set();
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        for (const rule of RULES) {
+            const ruleKey = `${rule.category}::${rule.pattern.source}`;
+            if (seenCategoriesPerRule.has(ruleKey))
+                continue;
+            if (rule.pattern.test(trimmed)) {
+                out.push({
+                    category: rule.category,
+                    description: rule.description,
+                    evidence: trimmed.length > 200 ? trimmed.slice(0, 200) + '…' : trimmed,
+                });
+                seenCategoriesPerRule.add(ruleKey);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Convenience: dedupe a requirement list down to one entry per
+ * category. Useful for top-line summaries where the agent doesn't
+ * need to render every matched rule.
+ */
+export function dedupeByCategory(requirements) {
+    const seen = new Set();
+    const out = [];
+    for (const r of requirements) {
+        if (seen.has(r.category))
+            continue;
+        seen.add(r.category);
+        out.push(r);
+    }
+    return out;
+}

package/dist/core/extraction-categories.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Per-repo extraction category configuration (#1284).
+ *
+ * The `extract-learnings` MCP prompt produces a structured markdown
+ * document organized into category sections. The default category
+ * set is sensible for typical web/library OSS work; specialized
+ * repos (security-focused, performance-critical, accessibility-
+ * forward) benefit from a tailored taxonomy.
+ *
+ * This module is the single source of truth for:
+ *   - The default category list.
+ *   - Validation of custom category lists (non-empty, no duplicates,
+ *     reasonable string lengths).
+ *   - Resolution: given a repo's optional override, produce the list
+ *     of categories the prompt and the storage layer should use.
+ *
+ * Pure typed helper — no I/O. Same architectural shape as the recent
+ * #1252 / #1264 / #1286 / #1279 / #1277 extractions.
+ *
+ * Out of scope (deferred per #1284):
+ *  - Wiring `categories` into the `guidelines store` / `guidelines view`
+ *    shape so the override persists alongside the markdown.
+ *  - Updating the `extract-learnings` MCP prompt to consume the
+ *    resolved category list at run time.
+ *  - Detecting repo type from signals (SECURITY.md presence, repo
+ *    topics, etc.) to suggest categories.
+ */
+/**
+ * The default category list used by `extract-learnings` when no
+ * per-repo override is configured. Order matters: the prompt
+ * renders sections in this order, so `Code Style` first /
+ * `Other` last is the established convention.
+ */
+export declare const DEFAULT_EXTRACTION_CATEGORIES: readonly string[];
+export interface CategoryValidationResult {
+    ok: boolean;
+    /** Non-empty when ok === false. One issue per detected problem. */
+    errors: string[];
+    /** The list as a caller should persist it, with `Other` appended
+     * if the user forgot it (the prompt always needs an "everything
+     * else" bucket). Only populated when ok === true. */
+    normalized?: readonly string[];
+}
+/**
+ * Validate a user-supplied category list. Returns a structured
+ * result rather than throwing — the CLI / slash-command callers
+ * surface error strings inline.
+ */
+export declare function validateCategories(input: readonly string[]): CategoryValidationResult;
+/**
+ * Resolve the categories the prompt + storage layer should use for a
+ * specific extraction. Falls back to the default list when no
+ * override is supplied or when the override fails validation.
+ */
+export declare function resolveCategories(override: readonly string[] | undefined | null): readonly string[];

package/dist/core/extraction-categories.js

@@ -0,0 +1,108 @@
+/**
+ * Per-repo extraction category configuration (#1284).
+ *
+ * The `extract-learnings` MCP prompt produces a structured markdown
+ * document organized into category sections. The default category
+ * set is sensible for typical web/library OSS work; specialized
+ * repos (security-focused, performance-critical, accessibility-
+ * forward) benefit from a tailored taxonomy.
+ *
+ * This module is the single source of truth for:
+ *   - The default category list.
+ *   - Validation of custom category lists (non-empty, no duplicates,
+ *     reasonable string lengths).
+ *   - Resolution: given a repo's optional override, produce the list
+ *     of categories the prompt and the storage layer should use.
+ *
+ * Pure typed helper — no I/O. Same architectural shape as the recent
+ * #1252 / #1264 / #1286 / #1279 / #1277 extractions.
+ *
+ * Out of scope (deferred per #1284):
+ *  - Wiring `categories` into the `guidelines store` / `guidelines view`
+ *    shape so the override persists alongside the markdown.
+ *  - Updating the `extract-learnings` MCP prompt to consume the
+ *    resolved category list at run time.
+ *  - Detecting repo type from signals (SECURITY.md presence, repo
+ *    topics, etc.) to suggest categories.
+ */
+/**
+ * The default category list used by `extract-learnings` when no
+ * per-repo override is configured. Order matters: the prompt
+ * renders sections in this order, so `Code Style` first /
+ * `Other` last is the established convention.
+ */
+export const DEFAULT_EXTRACTION_CATEGORIES = [
+    'Code Style',
+    'Process',
+    'Architecture',
+    'Testing',
+    'Other',
+];
+/**
+ * Reasonable bounds on an override list. The prompt produces output
+ * organized into one heading per category; very long lists become
+ * unreadable, very long category names blow out heading width.
+ */
+const CATEGORY_NAME_MAX_LENGTH = 40;
+const MAX_CATEGORIES = 12;
+/**
+ * Validate a user-supplied category list. Returns a structured
+ * result rather than throwing — the CLI / slash-command callers
+ * surface error strings inline.
+ */
+export function validateCategories(input) {
+    const errors = [];
+    if (input.length === 0) {
+        errors.push('At least one category is required.');
+        return { ok: false, errors };
+    }
+    if (input.length > MAX_CATEGORIES) {
+        errors.push(`At most ${MAX_CATEGORIES} categories are supported (received ${input.length}).`);
+    }
+    const seen = new Set();
+    const cleaned = [];
+    for (const raw of input) {
+        const trimmed = raw.trim();
+        if (trimmed.length === 0) {
+            errors.push('Category names cannot be empty or whitespace-only.');
+            continue;
+        }
+        if (trimmed.length > CATEGORY_NAME_MAX_LENGTH) {
+            errors.push(`Category "${trimmed.slice(0, 30)}…" is longer than ${CATEGORY_NAME_MAX_LENGTH} characters.`);
+            continue;
+        }
+        const lowerKey = trimmed.toLowerCase();
+        if (seen.has(lowerKey)) {
+            errors.push(`Duplicate category "${trimmed}" (case-insensitive).`);
+            continue;
+        }
+        seen.add(lowerKey);
+        cleaned.push(trimmed);
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    // Always ensure an "Other" bucket exists at the end so the prompt
+    // has a place to put feedback that doesn't fit the user's chosen
+    // categories. Append silently if missing rather than treating the
+    // omission as an error — most users won't think to add it.
+    if (!seen.has('other')) {
+        cleaned.push('Other');
+    }
+    return { ok: true, errors: [], normalized: cleaned };
+}
+/**
+ * Resolve the categories the prompt + storage layer should use for a
+ * specific extraction. Falls back to the default list when no
+ * override is supplied or when the override fails validation.
+ */
+export function resolveCategories(override) {
+    if (!override || override.length === 0) {
+        return DEFAULT_EXTRACTION_CATEGORIES;
+    }
+    const result = validateCategories(override);
+    if (!result.ok || !result.normalized) {
+        return DEFAULT_EXTRACTION_CATEGORIES;
+    }
+    return result.normalized;
+}