loadout-ai 0.3.1 → 0.4.1

package/dist/src/core/adopt.js

@@ -1,10 +1,125 @@
 import { createHash } from "node:crypto";
-import { readFile } from "node:fs/promises";
-import { basename, join } from "node:path";
+import { lstat, readFile, readdir } from "node:fs/promises";
+import { basename, isAbsolute, join, posix, relative, sep } from "node:path";
 import { enrichInventoryWithProvenance } from "./provenance.js";
 import { scanInstalledSkills } from "./skill-inventory.js";
 import { installStatePath, recordInstall } from "./state.js";
 import { runMutationTransaction } from "./transaction.js";
+const issuedAdoptionPlans = new WeakMap();
+function safeRelativePath(root, path) {
+    const value = relative(root, path).split(sep).join("/");
+    if (!value || isAbsolute(value) || value === ".." || value.startsWith("../"))
+        throw new Error(`Unsafe path while inspecting adoption tree: ${path}`);
+    return value;
+}
+async function captureAdoptionTree(root) {
+    const rootInfo = await lstat(root);
+    if (rootInfo.isSymbolicLink() || !rootInfo.isDirectory())
+        throw new Error(`Refusing unsafe adoption root: ${root}`);
+    const entries = [];
+    async function visit(directory) {
+        const children = (await readdir(directory, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name));
+        for (const child of children) {
+            const path = join(directory, child.name);
+            const relativePath = safeRelativePath(root, path);
+            const info = await lstat(path);
+            if (info.isSymbolicLink())
+                throw new Error(`Refusing symlink while inspecting adoption tree: ${path}`);
+            if (info.isDirectory()) {
+                entries.push({ path: relativePath, type: "directory" });
+                await visit(path);
+            }
+            else if (info.isFile()) {
+                entries.push({
+                    path: relativePath,
+                    type: "file",
+                    sha256: createHash("sha256")
+                        .update(await readFile(path))
+                        .digest("hex"),
+                });
+            }
+            else {
+                throw new Error(`Refusing special file while inspecting adoption tree: ${path}`);
+            }
+        }
+    }
+    await visit(root);
+    return entries;
+}
+function validateTreeEvidence(entries) {
+    const seen = new Set();
+    for (const entry of entries) {
+        if (!entry.path ||
+            isAbsolute(entry.path) ||
+            entry.path === ".." ||
+            entry.path.startsWith("../") ||
+            entry.path.includes("\\") ||
+            entry.path.split("/").includes("..") ||
+            posix.normalize(entry.path) !== entry.path ||
+            (entry.type === "file" && !/^[a-f0-9]{64}$/.test(entry.sha256 ?? "")) ||
+            (entry.type === "directory" && entry.sha256 !== undefined) ||
+            (entry.type !== "file" && entry.type !== "directory") ||
+            seen.has(entry.path))
+            throw new Error("The adoption preview contains unsafe tree evidence; preview again.");
+        seen.add(entry.path);
+    }
+}
+function adoptionWarnings(exact, reviewed) {
+    if (reviewed)
+        return [];
+    if (exact)
+        return [
+            "SKILL.md matches the reviewed catalog, but auxiliary local entries are not covered by catalog evidence; adoption remains unreviewed.",
+        ];
+    return [
+        "The installed bytes do not exactly match the reviewed catalog; adoption records ownership but does not mark them reviewed.",
+    ];
+}
+function derivedReviewState(plan) {
+    const exact = plan.provenance.kind === "catalog-exact";
+    const tree = plan.treeEvidence ?? [];
+    return {
+        exact,
+        reviewed: exact &&
+            tree.length === 1 &&
+            tree[0].type === "file" &&
+            tree[0].path === "SKILL.md",
+    };
+}
+function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            deepFreeze(child);
+        Object.freeze(value);
+    }
+    return value;
+}
+function canonicalInstallPlan(packageId, agent, name, path, warnings) {
+    return {
+        packageId,
+        targetAgents: [agent.id],
+        warnings,
+        files: [
+            {
+                source: path,
+                target: path,
+                targetAgent: agent.id,
+                componentType: "skill",
+                compatibility: "native",
+                skillName: name,
+            },
+        ],
+    };
+}
+function expectedRecordedFiles(plan) {
+    return plan.treeEvidence
+        .filter((entry) => entry.type === "file" && Boolean(entry.sha256))
+        .map((entry) => ({
+        path: join(plan.path, entry.path),
+        sha256: entry.sha256,
+    }))
+        .sort((left, right) => left.path.localeCompare(right.path));
+}
 function slug(value) {
     return (value
         .toLowerCase()
@@ -29,64 +144,82 @@ export async function planSkillAdoption(skill, agent, index) {
         ? match.provenance.candidates[0]
         : undefined;
     const packageId = `adopted-${agent.id}-${slug(match.name)}`;
-    return {
+    const treeEvidence = await captureAdoptionTree(match.path);
+    const reviewed = Boolean(exact) &&
+        treeEvidence.length === 1 &&
+        treeEvidence[0].type === "file" &&
+        treeEvidence[0].path === "SKILL.md";
+    const warnings = adoptionWarnings(Boolean(exact), reviewed);
+    const plan = {
         packageId,
-        agent,
+        agent: { ...agent },
         name: match.name,
         path: match.path,
         fingerprint: match.fingerprint,
-        provenance: match.provenance,
-        reviewed: Boolean(exact),
+        treeEvidence,
+        provenance: {
+            ...match.provenance,
+            evidence: [...match.provenance.evidence],
+            candidates: match.provenance.candidates.map((candidate) => ({
+                ...candidate,
+            })),
+        },
+        reviewed,
         ...(exact
             ? { repository: exact.repository, resolvedCommit: exact.commit }
             : {}),
-        installPlan: {
-            packageId,
-            targetAgents: [agent.id],
-            warnings: exact
-                ? []
-                : [
-                    "The installed bytes do not exactly match the reviewed catalog; adoption records ownership but does not mark them reviewed.",
-                ],
-            files: [
-                {
-                    source: match.path,
-                    target: match.path,
-                    targetAgent: agent.id,
-                    componentType: "skill",
-                    compatibility: "native",
-                    skillName: match.name,
-                },
-            ],
-        },
+        installPlan: canonicalInstallPlan(packageId, agent, match.name, match.path, warnings),
     };
+    deepFreeze(plan);
+    issuedAdoptionPlans.set(plan, deepFreeze({
+        packageId: plan.packageId,
+        path: plan.path,
+        treeEvidence: plan.treeEvidence,
+        installPlan: plan.installPlan,
+        ...(plan.repository ? { repository: plan.repository } : {}),
+        ...(plan.resolvedCommit ? { resolvedCommit: plan.resolvedCommit } : {}),
+        reviewed: derivedReviewState(plan).reviewed,
+    }));
+    return plan;
 }
-export async function applySkillAdoption(plan) {
+export async function applySkillAdoption(plan, options = {}) {
+    const issued = issuedAdoptionPlans.get(plan);
+    if (!issued)
+        throw new Error("The adoption plan was not issued by this planner process; preview again.");
     const applied = await runMutationTransaction(async () => {
-        const current = createHash("sha256")
-            .update(await readFile(join(plan.path, "SKILL.md")))
-            .digest("hex");
-        if (current !== plan.fingerprint)
+        validateTreeEvidence(issued.treeEvidence);
+        const current = await captureAdoptionTree(issued.path);
+        if (JSON.stringify(current) !== JSON.stringify(issued.treeEvidence))
             throw new Error("The skill changed after preview; scan again before adopting it.");
-        return { targets: [installStatePath()], value: plan };
+        return { targets: [installStatePath()], value: issued };
     }, async (freshPlan, snapshot) => {
+        await options.beforeRecord?.();
         await recordInstall(freshPlan.installPlan, snapshot.id, {
             ...(freshPlan.repository ? { repository: freshPlan.repository } : {}),
             ...(freshPlan.resolvedCommit
                 ? { resolvedCommit: freshPlan.resolvedCommit }
                 : {}),
             reviewed: freshPlan.reviewed,
+        }, {
+            expectedFiles: expectedRecordedFiles(freshPlan),
+            verifyBeforeWrite: async () => {
+                const current = await captureAdoptionTree(freshPlan.path);
+                if (JSON.stringify(current) !== JSON.stringify(freshPlan.treeEvidence))
+                    throw new Error("The skill changed after preview; scan again before adopting it.");
+            },
         });
     });
     return applied.snapshotId;
 }
 export function formatAdoptionPlan(plan) {
+    const review = derivedReviewState(plan);
     return [
         `Adopt: ${plan.name} for ${plan.agent.displayName}`,
         `Path: ${plan.path}`,
         `Managed id: ${plan.packageId}`,
         `Provenance: ${plan.provenance.kind} (${plan.provenance.confidence})`,
-        `Review state: ${plan.reviewed ? "reviewed exact catalog match" : "unreviewed"}`,
+        `Review state: ${review.reviewed ? "reviewed exact catalog match" : "unreviewed"}`,
+        `Bound tree entries: ${plan.treeEvidence?.length ?? 0}`,
         ...plan.installPlan.warnings.map((warning) => `Warning: ${warning}`),
     ].join("\n");
 }

package/dist/src/core/agent-health-score.js

@@ -248,7 +248,7 @@ function activeSetCapacity(evidence) {
             `Disable or consolidate at least ${active - capacity} active skill(s), prioritizing duplicates and weak evidence.`,
         ]
         : [
-            "Keep nonessential packages in the reviewed library and re-check capacity after activation changes.",
+            "Keep nonessential packages in the inspected library and re-check capacity after activation changes.",
         ]);
 }
 function compatibility(evidence) {
@@ -464,7 +464,7 @@ export function buildAgentHealthScore(evidence) {
 }
 export function formatAgentHealthScore(score) {
     const lines = [
-        `Agent Health Score: ${score.score}/${score.maximumScore} (${score.rating}; evidence coverage ${score.evidenceCoverage}%)`,
+        `Evidence coverage and managed-state hygiene: ${score.score}/${score.maximumScore} (${score.rating}; evidence coverage ${score.evidenceCoverage}%)`,
         `Agent: ${score.agent}${score.asOf ? ` · observed ${score.asOf}` : ""}`,
     ];
     for (const item of score.dimensions) {

package/dist/src/core/catalog-coverage.js

@@ -42,6 +42,7 @@ export function buildCatalogCoverage(catalog, targetRecords = 50) {
     const platforms = tally(catalog.flatMap((pkg) => pkg.operatingSystems ?? []), operatingSystems);
     return {
         records: catalog.length,
+        categoryCount: Object.keys(categories).length,
         targetRecords,
         technicallyScreenedRecords: catalog.filter(technicallyScreened).length,
         recommendedRecords: catalog.filter((pkg) => catalogTrustStage(pkg) === "recommended").length,
@@ -76,7 +77,7 @@ export function formatCatalogCoverage(report) {
         .join(", ");
     return [
         `Screened catalog: ${report.technicallyScreenedRecords}/${report.records} technically complete records (target ${report.targetRecords})`,
-        `Recommendation trust: ${report.recommendedRecords} Stable sources · human license approval still required before release`,
+        `Policy selection: ${report.recommendedRecords} Stable sources · ${report.trustStages["human-reviewed"]} human-reviewed · ${report.trustStages.benchmarked} benchmarked`,
         `Evidence: ${report.immutablePins} immutable pins · ${report.assertedLicenses} asserted licenses · ${report.noAssertionLicenses} NOASSERTION`,
         `Coverage: ${Object.values(report.categories).length} categories · ${report.evaluationReady} evaluation-ready · ${report.activityObserved} with refreshed activity`,
         `Install shape: ${report.installShapes.skills} skill · ${report.installShapes.mcpOnly} MCP-only · ${report.installShapes.mixed} mixed`,

package/dist/src/core/catalog-install.js

@@ -5,6 +5,7 @@ import { applySkillLibraryBatch, applySkillInstallBatch, buildSkillPlan, install
 import { fetchRepositorySnapshot, } from "./source.js";
 import { analyzeInstallPlanSafety, } from "./safety.js";
 import { formatModelApiAccess } from "./access.js";
+import { recordInstalledProfile } from "./profile-state.js";
 export const RECOMMENDED_ACTIVE_SKILL_LIMIT = 30;
 async function parallelMap(values, concurrency, worker) {
     const results = new Array(values.length);
@@ -244,12 +245,18 @@ export async function applyPreparedCatalogInstall(prepared, options = {}) {
     if (risky.length && !options.approveRisk)
         throw new Error(`Additional risk approval is required for: ${risky.map((entry) => entry.package.id).join(", ")}. Review the plan, then use --approve-risk.`);
     return prepared.selection.mode === "maximum"
-        ? applySkillLibraryBatch(prepared.entries)
+        ? applySkillLibraryBatch(prepared.entries, {
+            afterRecord: () => recordInstalledProfile(prepared).then(() => undefined),
+        })
         : applySkillInstallBatch(prepared.entries, [], {
             replaceManagedTargets: true,
             reconcileManagedTargets: true,
             ...(prepared.reconciliation
                 ? { expectedReconciliation: prepared.reconciliation }
                 : {}),
+            afterRecord: () => recordInstalledProfile(prepared).then(() => undefined),
         });
 }
+export function formatCatalogApplyGuidance(riskApprovalRequired) {
+    return `Preview complete; nothing was changed. Re-run with --yes${riskApprovalRequired ? " --approve-risk" : ""} to install this exact screened plan.`;
+}

package/dist/src/core/catalog-release.js

@@ -7,7 +7,7 @@ import { catalogTrustPath, loadEffectiveCatalog, readCatalogTrustState, readTrus
 import { ensureDirectory } from "./paths.js";
 import { loadoutHome } from "./paths.js";
 import { withFileLock } from "./file-lock.js";
-import { createSnapshot } from "./snapshot.js";
+import { createSnapshot, recordSnapshotPostMutationState } from "./snapshot.js";
 import { verifyEnvelope } from "./signing.js";
 import { beginTransaction, completeTransaction, markTransactionCommitting, rollbackTransaction, recoverPendingTransactions, } from "./transaction.js";
 const MAX_RELEASE_BYTES = 5 * 1024 * 1024;
@@ -248,6 +248,7 @@ export async function applyCatalogRelease(preview, options = {}) {
             }, null, 2)}\n`);
             await markTransactionCommitting(transaction);
             await writeFileAtomically(target, `${JSON.stringify(state, null, 2)}\n`);
+            await recordSnapshotPostMutationState(snapshot);
             await completeTransaction(transaction, { releaseLock: false });
             await writeFileAtomically(catalogTrustPath(), `${JSON.stringify({
                 ...pinned,

package/dist/src/core/conformance.js

@@ -0,0 +1,74 @@
+import { ADAPTER_CAPABILITIES, agentComponentDirectory } from "./adapters.js";
+import { AGENT_DEFINITIONS, agentSkillsDirectory } from "./paths.js";
+const PLATFORM_BY_RUNNER = {
+    "ubuntu-latest": "linux",
+    "macos-latest": "macos",
+    "windows-latest": "windows",
+};
+/** Derive bounded platform evidence from the manually triggered CI job. */
+export function platformEvidenceFromCiWorkflow(workflow) {
+    const jobStart = workflow.search(/^ {2}cross-platform:\s*$/m);
+    const dispatchConfigured = /^ {2}workflow_dispatch:\s*$/m.test(workflow);
+    if (jobStart < 0 || !dispatchConfigured)
+        throw new Error("The cross-platform CI job and workflow_dispatch trigger are required before platform evidence can be claimed.");
+    const afterStart = workflow.slice(jobStart + 1);
+    const nextJob = afterStart.search(/^ {2}[a-zA-Z0-9_-]+:\s*$/m);
+    const job = nextJob < 0 ? afterStart : afterStart.slice(0, nextJob);
+    if (!/if:\s*github\.event_name\s*==\s*['"]workflow_dispatch['"]/.test(job))
+        throw new Error("The cross-platform CI job must remain explicitly bounded to workflow_dispatch.");
+    const match = job.match(/^\s+os:\s*\[([^\]]+)\]\s*$/m);
+    if (!match)
+        throw new Error("The cross-platform CI job has no explicit OS matrix.");
+    const runners = match[1].split(",").map((value) => value.trim());
+    return runners.map((runner) => {
+        const platform = PLATFORM_BY_RUNNER[runner];
+        if (!platform)
+            throw new Error(`The cross-platform CI job uses an unrecognized runner '${runner}'.`);
+        return {
+            platform,
+            kind: "ci-configured",
+            source: ".github/workflows/ci.yml (cross-platform job)",
+        };
+    });
+}
+function declaredAgents() {
+    return AGENT_DEFINITIONS.map((definition) => ({
+        id: definition.id,
+        displayName: definition.displayName,
+        installed: false,
+        skillsDirectory: agentSkillsDirectory(definition.id),
+    }));
+}
+/**
+ * Build conservative adapter evidence. Merely constructing this matrix does
+ * not prove a filesystem run or execution inside an agent application.
+ */
+export function buildAdapterConformanceMatrix(agents = declaredAgents(), platformEvidence = []) {
+    const detected = new Map(agents.map((agent) => [agent.id, agent]));
+    return ADAPTER_CAPABILITIES.map((adapter) => {
+        const agent = detected.get(adapter.agent);
+        return {
+            agent: adapter.agent,
+            displayName: adapter.displayName,
+            pathKnown: Boolean(agent) &&
+                Boolean(agentComponentDirectory(agent, "skill")) &&
+                adapter.components.skill === "native",
+            filesystemVerified: false,
+            nativeApplicationVerified: false,
+            platformEvidence: platformEvidence.map((item) => ({
+                ...item,
+            })),
+        };
+    });
+}
+/**
+ * Promote only the filesystem evidence after the caller has completed the
+ * disposable plan/apply/inspect/disable/enable/rollback lifecycle.
+ */
+export function markFilesystemConformanceVerified(matrix, agent) {
+    if (!matrix.some((entry) => entry.agent === agent && entry.pathKnown))
+        throw new Error(`Cannot verify filesystem conformance for '${agent}' without a known native skill path.`);
+    return matrix.map((entry) => entry.agent === agent
+        ? { ...entry, filesystemVerified: true }
+        : { ...entry });
+}

package/dist/src/core/install.js

@@ -6,6 +6,7 @@ import { planAdapterSkillInstall } from "./adapters.js";
 import { applySkillPlan, detectInstallConflicts } from "./skills.js";
 import { activationLibraryPath, installStatePath, recordInstall, recordInstallBatch, recordLibraryInstallBatch, readInstallState, hashDirectory, writeInstallState, } from "./state.js";
 import { runMutationTransaction } from "./transaction.js";
+import { inspectTargetOccupancy } from "./target-occupancy.js";
 export function installedAgents(agents, requested) {
     const available = agents.filter((agent) => agent.installed);
     if (!requested || requested.length === 0)
@@ -116,17 +117,8 @@ async function assertActiveTargetsUnoccupied(plans, options = {}) {
     for (const target of [
         ...new Set(plans.flatMap((plan) => plan.files.map((file) => file.target))),
     ])
-        try {
-            await lstat(target);
+        if ((await inspectTargetOccupancy(target)).occupied)
             occupied.push(target);
-        }
-        catch (error) {
-            if (!error ||
-                typeof error !== "object" ||
-                !("code" in error) ||
-                error.code !== "ENOENT")
-                throw error;
-        }
     if (occupied.length && options.allowManagedReplacement) {
         const state = await readInstallState();
         const allowed = new Map();
@@ -202,6 +194,9 @@ export async function applySkillInstall(plan, metadata, options = {}) {
             value: plan,
         };
     }, async (freshPlan, snapshot) => {
+        // Close the preview/apply race: an empty target may have become occupied
+        // after the first check but before the transaction snapshot completed.
+        await assertActiveTargetsUnoccupied([freshPlan], options);
         if (options.replaceManagedTargets)
             for (const target of [
                 ...new Set(freshPlan.files.map((file) => file.target)),
@@ -264,6 +259,9 @@ export async function applySkillInstallBatch(entries, extraSnapshotPaths = [], o
             value: { entries, reconciliation },
         };
     }, async ({ entries: freshEntries, reconciliation }, snapshot) => {
+        // Re-check immediately before any removal or copy for the same reason as
+        // the single-package path above.
+        await assertActiveTargetsUnoccupied(freshEntries.map((entry) => entry.plan), { allowManagedReplacement: options.replaceManagedTargets });
         for (const target of reconciliation.obsoleteTargets)
             await rm(target, { recursive: true, force: true });
         if (options.replaceManagedTargets)
@@ -279,6 +277,7 @@ export async function applySkillInstallBatch(entries, extraSnapshotPaths = [], o
                     await assertExactDirectoryCopy(file.source, file.target, "Exact setup copy verification failed");
         await recordInstallBatch(freshEntries, snapshot.id);
         await recordManagedProfileReconciliation(reconciliation);
+        await options.afterRecord?.();
     });
     return applied.snapshotId;
 }
@@ -286,7 +285,7 @@ export async function applySkillInstallBatch(entries, extraSnapshotPaths = [], o
  * Download a batch into the reviewed library without exposing any skill to an
  * agent yet. This is the safe destination for Maximum Library.
  */
-export async function applySkillLibraryBatch(entries) {
+export async function applySkillLibraryBatch(entries, options = {}) {
     if (!entries.length)
         throw new Error("Library batch is empty");
     const conflicts = detectInstallConflicts(entries.map((entry) => entry.plan));
@@ -343,6 +342,7 @@ export async function applySkillLibraryBatch(entries) {
             }
         }
         await recordLibraryInstallBatch(freshEntries, snapshot.id);
+        await options.afterRecord?.();
     });
     return applied.snapshotId;
 }

package/dist/src/core/profiles.js

@@ -1,6 +1,6 @@
 import { compareCatalogPackages } from "./ranking.js";
 /**
- * Stable is Loadout's recommended daily driver: broad enough to improve normal
+ * Stable is Loadout's bounded policy-selected daily driver: broad enough to improve normal
  * engineering work immediately, but bounded at skill granularity and restricted
  * to catalog sources with an identified SPDX license. Maximum remains the
  * explicit broad-library mode.
@@ -45,7 +45,8 @@ export const STABLE_BOOST_PACKAGE_IDS = Object.freeze(Object.keys(STABLE_SKILL_A
 /**
  * Trust is deliberately separate from popularity and publisher tier. No
  * bundled record is labelled human-reviewed or benchmarked until that evidence
- * is actually stored; Stable is the policy-recommended subset.
+ * is actually stored; Stable is the policy-selected subset. The stored
+ * `recommended` value remains for schema compatibility.
  */
 export function catalogTrustStage(pkg) {
     if (STABLE_BOOST_PACKAGE_IDS.includes(pkg.id) &&
@@ -58,6 +59,10 @@ export function catalogTrustStage(pkg) {
         return "inspected";
     return "discovered";
 }
+/** Keep stored `recommended` values compatible while naming their evidence honestly. */
+export function formatCatalogTrustStage(stage) {
+    return stage === "recommended" ? "policy-selected" : stage;
+}
 export function isStableSkillSelected(packageId, skillName, targetName) {
     const selected = STABLE_SKILL_ALLOWLIST[packageId];
     if (!selected)
@@ -233,7 +238,7 @@ export function resolveCatalogProfile(packages, selection, families = CATALOG_CO
                 selected.delete(secondary.id);
                 deferred.push(secondary);
             }
-            warnings.push(`Stable Boost selected ${primary.displayName}; deferred ${members
+            warnings.push(`Loadout policy selection for Stable chose ${primary.displayName}; deferred ${members
                 .slice(1)
                 .map((pkg) => pkg.displayName)
                 .join(", ")} because they overlap in ${family.label}.`);
@@ -242,7 +247,7 @@ export function resolveCatalogProfile(packages, selection, families = CATALOG_CO
             warnings.push(`Custom selection retains the soft overlap in ${family.label}. Review ${names} before installation.`);
         }
         else {
-            warnings.push(`${selection.mode === "power" ? "Power Boost" : "Maximum Library"} retains the soft overlap in ${family.label}. ${primary.displayName} is the recommended default; review each package before installation.`);
+            warnings.push(`${selection.mode === "power" ? "Power Boost" : "Maximum Library"} retains the soft overlap in ${family.label}. Loadout policy orders ${primary.displayName} first; review each package before installation.`);
         }
     }
     return {

package/dist/src/core/ranking.js

@@ -96,7 +96,7 @@ export function explainCatalogScore(pkg, now = new Date()) {
         ],
     };
 }
-/** A deterministic ordering: review tier first, then explainable evidence, then id. */
+/** A deterministic policy ordering: declared tier, bounded evidence score, then id. */
 export function compareCatalogPackages(a, b) {
     return (TIER_ORDER[b.tier] - TIER_ORDER[a.tier] ||
         explainCatalogScore(b).score - explainCatalogScore(a).score ||

package/dist/src/core/readme-claims.js

@@ -0,0 +1,10 @@
+import { formatSchemaError, readmeClaimManifestSchema, } from "../shared/schemas.js";
+export { readmeClaimManifestSchema };
+/** Parse the versioned index of evidence for material README statements. */
+export function parseReadmeClaimManifest(value) {
+    const result = readmeClaimManifestSchema.safeParse(value);
+    if (!result.success) {
+        throw new Error(`README claim manifest is invalid: ${formatSchemaError(result.error)}`);
+    }
+    return result.data;
+}

package/dist/src/core/readme-facts.js

@@ -0,0 +1,40 @@
+import { supportedAdapterNames } from "./adapters.js";
+import { buildCatalogCoverage } from "./catalog-coverage.js";
+function profileFacts(allowlist) {
+    return {
+        sources: Object.keys(allowlist).length,
+        skillDirectories: Object.values(allowlist).reduce((count, skills) => count + skills.length, 0),
+    };
+}
+/**
+ * Derive all changeable README facts from passed authoritative source data.
+ * This module intentionally neither reads nor parses README text.
+ */
+export function deriveReadmeFacts({ catalog, packageJson, agents, profiles, }) {
+    const coverage = buildCatalogCoverage(catalog);
+    return {
+        catalog: {
+            records: coverage.records,
+            categories: coverage.categoryCount,
+            components: coverage.components,
+            installShapes: coverage.installShapes,
+            assertedLicenses: coverage.assertedLicenses,
+            noAssertionLicenses: coverage.noAssertionLicenses,
+        },
+        profiles: {
+            stable: profileFacts(profiles.stable),
+            power: profileFacts(profiles.power),
+        },
+        agents: {
+            supportedNames: supportedAdapterNames(agents),
+        },
+        package: {
+            name: packageJson.name,
+            version: packageJson.version,
+            bin: { ...packageJson.bin },
+        },
+        runtime: {
+            node: packageJson.engines.node,
+        },
+    };
+}