co-maintainer 0.4.0-beta.1

package/dist/src/knowledge/probe.js

@@ -0,0 +1,144 @@
+function year(value) {
+    return new Date(String(value)).getFullYear();
+}
+function percentile(values, percentage) {
+    if (!values.length)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * percentage) - 1)];
+}
+function isMerge(commit) {
+    const message = String(commit.commit?.message ?? "");
+    return (message.startsWith("Merge ") ||
+        (Array.isArray(commit.parents) && commit.parents.length > 1));
+}
+function isConventional(commit) {
+    return /^(feat|fix|docs|refactor|test|build|ci|chore|perf|style)(\(.+\))?!?:\s/i.test(String(commit.commit?.message ?? ""));
+}
+function commitStats(commits) {
+    if (!commits.length)
+        return { mergeRatio: 0, conventionalRatio: 0 };
+    return {
+        mergeRatio: commits.filter(isMerge).length / commits.length,
+        conventionalRatio: commits.filter(isConventional).length / commits.length,
+    };
+}
+function recommendCommitWindow(commits) {
+    if (commits.length <= 300)
+        return undefined;
+    const useful = commits.filter((commit) => !isMerge(commit));
+    if (useful.length < 100)
+        return undefined;
+    const recent = commitStats(commits.slice(0, 100));
+    let stableThrough = 100;
+    for (let start = 100; start < commits.length; start += 100) {
+        const window = commits.slice(start, start + 100);
+        const stats = commitStats(window);
+        const stable = Math.abs(stats.mergeRatio - recent.mergeRatio) <= 0.15 &&
+            Math.abs(stats.conventionalRatio - recent.conventionalRatio) <= 0.15;
+        if (!stable)
+            break;
+        stableThrough = start + window.length;
+    }
+    return stableThrough < commits.length ? stableThrough : undefined;
+}
+function recommendPrWindow(pulls, latestReleaseAt) {
+    if (!pulls.length)
+        return undefined;
+    const years = new Map();
+    for (const pull of pulls) {
+        const itemYear = year(pull.updated_at);
+        years.set(itemYear, (years.get(itemYear) ?? 0) + 1);
+    }
+    const oldest = Math.min(...years.keys());
+    const current = new Date().getFullYear();
+    const span = current - oldest + 1;
+    if (pulls.length <= 150 || span <= 3)
+        return undefined;
+    const recentTwoYears = pulls.filter((pull) => year(pull.updated_at) >= current - 1).length;
+    const releaseAgeMonths = latestReleaseAt
+        ? (Date.now() - new Date(latestReleaseAt).getTime()) /
+            (30.44 * 24 * 60 * 60 * 1_000)
+        : Infinity;
+    if (recentTwoYears >= 100 &&
+        (releaseAgeMonths <= 18 || recentTwoYears / pulls.length >= 0.35)) {
+        return 24;
+    }
+    const target = pulls.length * 0.85;
+    let covered = 0;
+    let windowYears = 0;
+    while (windowYears < span && (covered < target || windowYears < 2)) {
+        windowYears++;
+        covered += years.get(current - windowYears + 1) ?? 0;
+    }
+    return windowYears < span ? windowYears * 12 : undefined;
+}
+export function analyzeProbe(meta, pulls, detailSamples, commits) {
+    const years = new Map();
+    for (const pull of pulls) {
+        const itemYear = year(pull.updated_at);
+        years.set(itemYear, (years.get(itemYear) ?? 0) + 1);
+    }
+    const diffs = detailSamples
+        .map((detail) => Number(detail.additions ?? 0) + Number(detail.deletions ?? 0))
+        .filter((value) => value >= 0);
+    const medianDiff = percentile(diffs, 0.5);
+    const p90Diff = percentile(diffs, 0.9);
+    const maxDiff = Math.max(...diffs, 0);
+    const latestReleaseAt = String(meta.latest_release_at ?? "");
+    const maxPrMonths = recommendPrWindow(pulls, latestReleaseAt);
+    const maxCommits = recommendCommitWindow(commits);
+    const commitSignal = commitStats(commits);
+    const usefulCommits = commits.filter((commit) => !isMerge(commit)).length;
+    const includeCommitHistory = usefulCommits >= 20 && commitSignal.mergeRatio < 0.75;
+    const includeChanges = pulls.length > 0 && diffs.length > 0;
+    const maxChangeLines = includeChanges && diffs.length >= 10 && p90Diff < maxDiff
+        ? Math.max(100, Math.ceil(p90Diff / 100) * 100)
+        : undefined;
+    const reasons = [];
+    if (maxPrMonths) {
+        const releaseAgeMonths = latestReleaseAt
+            ? (Date.now() - new Date(latestReleaseAt).getTime()) /
+                (30.44 * 24 * 60 * 60 * 1_000)
+            : Infinity;
+        reasons.push(releaseAgeMonths <= 18
+            ? `A release from ${latestReleaseAt.slice(0, 10)} is recent; use the last ${maxPrMonths} months to prioritize the current contribution and release process.`
+            : `The last ${maxPrMonths} months cover at least 85% of pull requests; older history is a minority.`);
+    }
+    else if (pulls.length) {
+        reasons.push("Pull request volume or history span is small enough to keep all PR months.");
+    }
+    if (includeCommitHistory) {
+        reasons.push(`${usefulCommits} non-merge commits contain enough signal to analyze commit conventions.`);
+    }
+    else if (commits.length) {
+        reasons.push("Commit history is mostly merge/noise commits, so it is not recommended as a source.");
+    }
+    if (maxChangeLines) {
+        reasons.push(`The sampled diff p90 is ${p90Diff} lines; the cap keeps the largest outliers out while retaining about 90% of sampled diffs.`);
+    }
+    return {
+        includePullRequests: pulls.length > 0,
+        includePullRequestChanges: includeChanges,
+        includeCommitHistory,
+        maxPrMonths,
+        maxCommits: includeCommitHistory ? maxCommits : undefined,
+        maxPullRequestChangeLines: maxChangeLines,
+        reasons,
+        report: {
+            pullRequests: pulls.length,
+            pullRequestYears: Object.fromEntries([...years.entries()].sort()),
+            sampledPullRequests: detailSamples.length,
+            diffLines: {
+                median: medianDiff,
+                p90: p90Diff,
+                maximum: maxDiff,
+            },
+            commits: commits.length,
+            usefulCommits,
+            commitSignal,
+            defaultBranch: String(meta.default_branch ?? "main"),
+            latestReleaseAt: latestReleaseAt || undefined,
+        },
+    };
+}

package/dist/src/knowledge/sections.d.ts

@@ -0,0 +1,2 @@
+export declare const sectionTitles: Record<string, string>;
+export declare const sectionKeys: string[];

package/dist/src/knowledge/sections.js

@@ -0,0 +1,13 @@
+export const sectionTitles = {
+    identity: "Repository",
+    devloop: "Development and debugging",
+    ship: "Shipping",
+    layout: "Code layout",
+    style: "Code style",
+    tests: "Tests",
+    "title-body": "Pull request title and body",
+    labels: "Labels",
+    "review-bar": "Review bar",
+    process: "Pull request process",
+};
+export const sectionKeys = Object.keys(sectionTitles);

package/dist/src/knowledge/skill.d.ts

@@ -0,0 +1,10 @@
+import type { Fact } from "./types.ts";
+/** Slices an assembled skill's `## Heading` sections back out by section key,
+ * from `<!-- section:key -->` markers or (fallback) canonical heading text. */
+export declare function extractSections(markdown: string): Record<string, string>;
+export declare function factSectionHashes(facts: Fact[]): Promise<Record<string, string>>;
+export declare function assembleSkill(repo: string, facts: Fact[], previousMarkdown: string | undefined, previousHashes: Record<string, string>, overrides?: Record<string, string>): Promise<{
+    markdown: string;
+    hashes: Record<string, string>;
+    changed: string[];
+}>;

package/dist/src/knowledge/skill.js

@@ -0,0 +1,106 @@
+import { sectionKeys, sectionTitles } from "./sections.js";
+function sectionFacts(facts, key) {
+    return facts
+        .filter((item) => item.sectionKey === key)
+        .sort((a, b) => b.weight - a.weight);
+}
+function render(key, facts) {
+    const items = sectionFacts(facts, key).slice(0, 6);
+    if (!items.length)
+        return "";
+    return `## ${sectionTitles[key] ?? key}\n\n${items.map((item) => `- ${item.claim}`).join("\n")}`;
+}
+function cleanSection(value) {
+    return value.replace(/^\s*```[a-zA-Z0-9_-]*\s*$/gm, "").trim();
+}
+function hasBullets(value) {
+    return /^-\s+/m.test(value);
+}
+/** Slices an assembled skill's `## Heading` sections back out by section key,
+ * from `<!-- section:key -->` markers or (fallback) canonical heading text. */
+export function extractSections(markdown) {
+    const result = {};
+    const markerPattern = /<!-- section:([a-z-]+) -->\n([\s\S]*?)\n<!-- \/section:\1 -->/g;
+    for (const match of markdown.matchAll(markerPattern)) {
+        result[match[1]] = match[2];
+    }
+    const keysByTitle = Object.fromEntries(Object.entries(sectionTitles).map(([key, title]) => [title, key]));
+    const headings = [...markdown.matchAll(/^##\s+(.+)$/gm)];
+    for (let index = 0; index < headings.length; index++) {
+        const key = keysByTitle[headings[index][1].trim()];
+        if (!key || result[key])
+            continue;
+        const start = headings[index].index ?? 0;
+        const end = headings[index + 1]?.index ?? markdown.length;
+        result[key] = markdown.slice(start, end).trim();
+    }
+    return result;
+}
+async function hash(value) {
+    const bytes = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(value));
+    return [...new Uint8Array(bytes)]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
+export async function factSectionHashes(facts) {
+    const hashes = {};
+    for (const key of new Set(facts.map((item) => item.sectionKey))) {
+        const relevant = sectionFacts(facts, key);
+        hashes[key] = await hash(JSON.stringify(relevant.map((item) => [
+            item.id,
+            item.claim,
+            item.weight,
+            item.scope,
+            item.confidence,
+            item.status,
+        ])));
+    }
+    return hashes;
+}
+export async function assembleSkill(repo, facts, previousMarkdown, previousHashes, overrides = {}) {
+    const previous = previousMarkdown ? extractSections(previousMarkdown) : {};
+    const sections = {};
+    const hashes = {};
+    const changed = [];
+    const keys = sectionKeys.filter((key) => facts.some((item) => item.sectionKey === key));
+    for (const key of keys) {
+        const content = render(key, facts);
+        if (!content)
+            continue;
+        const relevant = sectionFacts(facts, key);
+        const sectionHash = await hash(JSON.stringify(relevant.map((item) => [
+            item.id,
+            item.claim,
+            item.weight,
+            item.scope,
+            item.confidence,
+            item.status,
+        ])));
+        hashes[key] = sectionHash;
+        const canonicalHeading = `## ${sectionTitles[key] ?? key}`;
+        const hasOverride = Object.hasOwn(overrides, key);
+        if (!hasOverride &&
+            previousMarkdown &&
+            previousHashes[key] === sectionHash &&
+            previous[key]?.startsWith(canonicalHeading)) {
+            sections[key] = cleanSection(previous[key]);
+            continue;
+        }
+        const section = hasOverride ? overrides[key] : content;
+        if (!hasBullets(section))
+            continue;
+        sections[key] = section;
+        changed.push(key);
+    }
+    const header = `---
+name: ${repo.replace("/", "-")}-maintainer
+description: Repository-specific guidance for contributing to ${repo}. Use when writing code, opening or reviewing pull requests, debugging, or releasing this repository.
+---
+
+# ${repo}
+
+Generated from repository metadata and selected project history. Prefer current repository files and workflows when this guidance conflicts with a stale example.
+`;
+    const body = Object.values(sections).join("\n\n");
+    return { markdown: header + body + "\n", hashes, changed };
+}

package/dist/src/knowledge/synthesis.d.ts

@@ -0,0 +1,7 @@
+import type { AiProvider, AiResponse, Options } from "../types.ts";
+import type { Fact, Source } from "./types.ts";
+type UsageSink = (job: string, response: AiResponse) => Promise<void>;
+export declare function extractAiFacts(provider: AiProvider, repo: string, source: Source, options: Options, usage?: UsageSink): Promise<Fact[]>;
+export declare function enrichFacts(provider: AiProvider, repo: string, base: Fact[], source: Source, options: Options, usage?: UsageSink): Promise<Fact[]>;
+export declare function synthesizeSections(provider: AiProvider, repo: string, facts: Fact[], _previousMarkdown: string | undefined, ai: Options["ai"], model: string, concurrency: number, usage?: UsageSink, onlySections?: Set<string>): Promise<Record<string, string>>;
+export {};

package/dist/src/knowledge/synthesis.js

@@ -0,0 +1,315 @@
+import { AiBatch } from "../ai/batch.js";
+import { sectionTitles } from "./sections.js";
+const allowedSections = new Set([
+    "identity",
+    "devloop",
+    "ship",
+    "layout",
+    "style",
+    "tests",
+    "title-body",
+    "labels",
+    "review-bar",
+    "process",
+]);
+function slug(value) {
+    return value.toLowerCase().replaceAll(/\W+/g, "-").replace(/^-|-$/g, "");
+}
+function promptText(value, limit = 6_000) {
+    return value.length > limit ? `${value.slice(0, limit)}\n[truncated]` : value;
+}
+function parseJson(text) {
+    const cleaned = text
+        .trim()
+        .replace(/^```(?:json)?\s*/i, "")
+        .replace(/\s*```$/, "");
+    try {
+        return JSON.parse(cleaned);
+    }
+    catch {
+        const start = cleaned.indexOf("[");
+        const end = cleaned.lastIndexOf("]");
+        if (start < 0)
+            throw new Error("AI fact output is not JSON");
+        if (end > start)
+            return JSON.parse(cleaned.slice(start, end + 1));
+        const lastCompleteObject = cleaned.lastIndexOf("}");
+        if (lastCompleteObject <= start) {
+            throw new Error("AI fact output is truncated");
+        }
+        return JSON.parse(`${cleaned.slice(start, lastCompleteObject + 1)}]`);
+    }
+}
+function factsFromResponse(text, evidence, defaultScope) {
+    const parsed = parseJson(text);
+    if (!Array.isArray(parsed)) {
+        throw new Error("AI fact output must be an array");
+    }
+    return parsed.flatMap((item) => {
+        if (!item || typeof item !== "object")
+            return [];
+        const value = item;
+        const claim = String(value.claim ?? "").trim();
+        const sectionKey = String(value.sectionKey ?? "").trim();
+        if (!claim || !allowedSections.has(sectionKey))
+            return [];
+        const scope = value.scope === "current" ||
+            value.scope === "repeated-history" ||
+            value.scope === "historical-example"
+            ? value.scope
+            : defaultScope;
+        const confidence = value.confidence === "high" ||
+            value.confidence === "medium" ||
+            value.confidence === "low"
+            ? value.confidence
+            : "medium";
+        return [
+            {
+                id: `${sectionKey}:${slug(claim)}`,
+                sectionKey,
+                claim,
+                evidence: [evidence],
+                weight: 1,
+                scope,
+                confidence,
+                status: "active",
+            },
+        ];
+    });
+}
+function hasUnsupportedIdentifier(claim, source) {
+    const evidence = [
+        ...source.tree,
+        ...Object.keys(source.files),
+        ...Object.values(source.files),
+    ].join("\n");
+    return [...claim.matchAll(/`([A-Za-z_]\w*)`/g)].some(([_, identifier]) => !evidence.includes(identifier));
+}
+function allowsContributionSections(source) {
+    return Object.keys(source.files).some((path) => /CONTRIBUTING|PULL_REQUEST_TEMPLATE/i.test(path));
+}
+function hasUnsupportedPath(claim, source) {
+    const paths = new Set([...source.tree, ...Object.keys(source.files)]);
+    const repositoryName = String(source.repo.full_name ?? "");
+    const references = [
+        ...[...claim.matchAll(/`([^`\n]+\/[^`\n]+)`/g)].map(([, value]) => value),
+        ...[...claim.matchAll(/`([^`\n]+\/)`/g)].map(([, value]) => value),
+        ...[
+            ...claim.matchAll(/(?:^|[\s("'`])((?!@)[A-Za-z0-9_.-]+\/[A-Za-z0-9_.*?{}<>:+-]+(?:\/[A-Za-z0-9_.*?{}<>:+-]+)*)/g),
+        ].map(([, value]) => value),
+    ];
+    return references.some((reference) => {
+        if (reference.startsWith("@") || reference === repositoryName)
+            return false;
+        const normalized = reference.replace(/^\.\/+/, "").replace(/\/+$/, "");
+        const wildcard = normalized.includes("*")
+            ? new RegExp(`^${normalized
+                .split("*")
+                .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+                .join(".*")}$`)
+            : undefined;
+        return (!paths.has(normalized) &&
+            ![...paths].some((path) => wildcard ? wildcard.test(path) : path.startsWith(`${normalized}/`)));
+    });
+}
+function pullRequestUnit(pr) {
+    return JSON.stringify({
+        number: pr.number,
+        title: pr.title,
+        body: promptText(pr.body),
+        labels: pr.labels,
+        comments: pr.comments.map((comment) => promptText(comment, 2_000)),
+        reviews: pr.reviews.map((review) => promptText(review, 2_000)),
+        changedFiles: pr.changedFiles,
+        diff: promptText(pr.diff, 8_000),
+    });
+}
+function queueFor(provider, repo, ai, model, concurrency) {
+    return new AiBatch(provider, repo, Math.max(1, concurrency), `${ai}:v2:${model}`);
+}
+function extractRequest(prompt, maxTokens) {
+    return {
+        job: "extract_unit",
+        prompt,
+        maxTokens,
+        system: "Extract only repository-specific facts. Never invent files, commands, or process.",
+    };
+}
+function cleanSection(text, key) {
+    const clean = text.replace(/^\s*```[a-zA-Z0-9_-]*\s*$/gm, "").trim();
+    const heading = sectionTitles[key] ?? key;
+    return clean.replace(/^##\s+.+$/m, `## ${heading}`);
+}
+function validSection(text, key) {
+    const heading = `## ${sectionTitles[key] ?? key}`;
+    const bullets = text.match(/^-\s+/gm) ?? [];
+    return (text.startsWith(heading) &&
+        bullets.length > 0 &&
+        bullets.length <= 6 &&
+        !text.includes("```") &&
+        !/\b(?:TODO|TBD)\b/i.test(text));
+}
+function sectionGoal(key) {
+    const goals = {
+        layout: "Describe module responsibilities and important dependency or change-impact paths; do not list routine public symbols.",
+        tests: "State which verification is required after a behavior change and the dependency/setup that makes it meaningful.",
+        devloop: "Give local build, debugging, or change-impact guidance that is not already stated in Shipping.",
+        ship: "Give one concise release/CI checklist; merge overlapping workflow, artifact, and release-gate facts.",
+        style: "Keep only repository-specific, evidenced conventions. Return only the heading when none are actionable.",
+    };
+    return goals[key] ?? "Keep only actionable repository-specific guidance.";
+}
+function synthesisFacts(facts, key) {
+    return facts
+        .filter((item) => item.sectionKey === key)
+        .sort((a, b) => (b.status === "active" ? 1 : 0) - (a.status === "active" ? 1 : 0) ||
+        ({
+            current: 3,
+            "repeated-history": 2,
+            "historical-example": 1,
+        }[b.scope] ?? 0) -
+            ({
+                current: 3,
+                "repeated-history": 2,
+                "historical-example": 1,
+            }[a.scope] ?? 0) ||
+        b.weight - a.weight ||
+        b.evidence.length - a.evidence.length ||
+        a.claim.localeCompare(b.claim))
+        .slice(0, 20);
+}
+export async function extractAiFacts(provider, repo, source, options, usage) {
+    const requests = [];
+    const evidence = [];
+    const scopes = [];
+    const prs = options.includePullRequests ? source.pullRequests : [];
+    for (const pr of prs) {
+        requests.push(extractRequest(`Analyze this pull request and return only a JSON array of atomic observations. Each item must have exactly:
+{"sectionKey":"one allowed section","claim":"one directly evidenced observation","scope":"historical-example","confidence":"medium"}
+Allowed sections: ${[...allowedSections].join(", ")}
+Use evidence from this PR only. Do not generalize this PR into a repository-wide policy.
+Return at most 6 items. Keep each claim under 180 characters. Do not explain the answer.
+
+PULL REQUEST:
+${pullRequestUnit(pr)}`, 1_200));
+        evidence.push(`PR #${pr.number}`);
+        scopes.push("historical-example");
+    }
+    if (options.includeCodebase || options.includeHowRepoWorks) {
+        const files = Object.entries(source.files)
+            .map(([path, content]) => `${path}\n${promptText(content, 4_000)}`)
+            .join("\n\n");
+        if (files) {
+            requests.push(extractRequest(`Analyze these canonical repository files and return only a JSON array of atomic observations.
+Each item must have exactly:
+{"sectionKey":"one allowed section","claim":"one directly evidenced observation","scope":"current","confidence":"high"}
+Allowed sections: ${[...allowedSections].join(", ")}
+Focus on module responsibilities, test-to-code relationships, build/debug constraints,
+release gates, and conventions that affect a code change. Ignore end-user feature lists,
+installation walkthroughs, and generic programming advice. For source files, identify
+what important modules own and how tests exercise them when the files provide evidence.
+Do not infer PR titles, labels, review rules, or contributor policy unless the input
+contains PR or pull-request-template evidence; every claim must be directly supported
+by a provided file. Do not report a current version value; preserve the version
+change or release rule instead.
+Return at most 10 items. Keep each claim under 180 characters. Do not explain the answer.
+
+FILES:
+${files}`, 2_200));
+            evidence.push("repository files");
+            scopes.push("current");
+        }
+    }
+    const queue = queueFor(provider, repo, options.ai, options.lowModel ?? "", options.aiConcurrent);
+    const responses = await queue.run(requests, usage);
+    const facts = [];
+    for (let index = 0; index < responses.length; index++) {
+        const response = responses[index];
+        if (!response)
+            continue;
+        try {
+            facts.push(...factsFromResponse(response.text, evidence[index], scopes[index] ?? "historical-example").filter((item) => !hasUnsupportedIdentifier(item.claim, source) &&
+                !hasUnsupportedPath(item.claim, source) &&
+                (evidence[index] !== "repository files" ||
+                    allowsContributionSections(source) ||
+                    !["title-body", "labels", "review-bar", "process"].includes(item.sectionKey))));
+        }
+        catch (error) {
+            console.log(`[ai] invalid ${evidence[index]} output skipped: ${String(error)}`);
+        }
+        if (index % 10 === 0 || index === responses.length - 1) {
+            console.log(`[ai] extract units ${index + 1}/${responses.length}`);
+        }
+    }
+    return facts;
+}
+function mergeFacts(base, extra) {
+    const merged = new Map(base.map((item) => [item.id, { ...item, evidence: [...item.evidence] }]));
+    for (const item of extra) {
+        const existing = merged.get(item.id);
+        if (!existing)
+            merged.set(item.id, item);
+        else {
+            existing.weight += item.weight;
+            existing.evidence = [
+                ...new Set([...existing.evidence, ...item.evidence]),
+            ];
+        }
+    }
+    return [...merged.values()];
+}
+export async function enrichFacts(provider, repo, base, source, options, usage) {
+    return mergeFacts(base, await extractAiFacts(provider, repo, source, options, usage));
+}
+export async function synthesizeSections(provider, repo, facts, _previousMarkdown, ai, model, concurrency, usage, onlySections) {
+    const requests = [];
+    const keys = [];
+    for (const key of [...new Set(facts.map((item) => item.sectionKey))]) {
+        if (onlySections && !onlySections.has(key))
+            continue;
+        const relevant = synthesisFacts(facts, key);
+        keys.push(key);
+        requests.push({
+            job: "synth_section",
+            maxTokens: 1_800,
+            reasoningEffort: "high",
+            system: `You synthesize contribution guidance for an unfamiliar open-source repository.
+Help developers make correct implementation, testing, review, debugging, and release
+decisions. Current repository evidence outranks history. A single historical
+observation is not a repository-wide rule. If sources conflict and current evidence
+does not resolve the conflict, omit the claim. Never invent paths, commands,
+conventions, or policies. Do not summarize README prose or list incidental details.`,
+            prompt: `Write only the Markdown for the "${key}" section of a repository Agent Skill.
+Use only the facts below. Keep rules that change implementation, testing, review,
+debugging, or release decisions. Drop end-user README instructions, feature lists,
+file inventories, duplicate commands, and generic programming advice. Preserve useful
+existing guidance, remove contradictions, deduplicate overlapping facts, and do not
+invent anything. Include the correct human-readable section heading. Use inline
+backticks instead of fenced code blocks. Do not create examples, placeholder
+identifiers, or policies that are not present in the facts. Prefer at most
+6 high-value bullets; keep a concrete example only when it changes an agent decision.
+Do not preserve a current version value that can become stale. In Shipping,
+consolidate CI and release facts instead of repeating the same workflow rule.
+Facts are raw candidates, not all mandatory output. A fact supported by only one PR
+is an example, not a repository-wide rule; omit it unless canonical files or repeated
+evidence support it. Omit conflicting claims rather than guessing. Return only the
+heading when this section has no durable guidance. Do not preserve bot-specific
+automation commands, reviewer identities, or one-off historical requests as
+repository-wide process guidance.
+
+SECTION GOAL:
+${sectionGoal(key)}
+
+FACTS:
+${JSON.stringify(relevant)}`,
+        });
+    }
+    const queue = queueFor(provider, repo, ai, model, ai === "hetzner" ? 1 : concurrency);
+    const responses = await queue.run(requests, usage);
+    const overrides = {};
+    responses.forEach((response, index) => {
+        const section = response ? cleanSection(response.text, keys[index]) : "";
+        overrides[keys[index]] = validSection(section, keys[index]) ? section : "";
+    });
+    return overrides;
+}

package/dist/src/knowledge/types.d.ts

@@ -0,0 +1,49 @@
+import type { Json, Options } from "../types.ts";
+export type PullRequest = {
+    number: number;
+    title: string;
+    body: string;
+    state: string;
+    merged: boolean;
+    updatedAt: string;
+    headSha: string;
+    labels: string[];
+    additions: number;
+    deletions: number;
+    comments: string[];
+    reviews: string[];
+    changedFiles: string[];
+    diff: string;
+};
+export type Source = {
+    repo: Json;
+    tree: string[];
+    treeSha: Record<string, string>;
+    files: Record<string, string>;
+    pullRequests: PullRequest[];
+    commits: Json[];
+};
+export type Fact = {
+    id: string;
+    sectionKey: string;
+    claim: string;
+    evidence: string[];
+    weight: number;
+    scope: "current" | "repeated-history" | "historical-example";
+    confidence: "high" | "medium" | "low";
+    status: "active" | "contradicted" | "stale";
+};
+export type State = {
+    version: 1;
+    repo: string;
+    options: Omit<Options, "command" | "aiToken" | "githubPat">;
+    source: Source;
+    facts: Fact[];
+    sectionHashes: Record<string, string>;
+    scanDone: {
+        pullRequests: number;
+        commits: number;
+        updatedAt: string;
+    };
+    updatedAt: string;
+};

package/dist/src/knowledge/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/knowledge/validate.d.ts

@@ -0,0 +1,6 @@
+import type { Source } from "./types.ts";
+export type ValidationResult = {
+    valid: boolean;
+    errors: string[];
+};
+export declare function validateSkill(markdown: string, outputDirectory: string, source?: Source): Promise<ValidationResult>;