loadout-ai 0.3.1 → 0.4.0

package/dist/src/cli.js

@@ -20,8 +20,8 @@ import { buildHealthReport, formatHealthReport } from "./core/health.js";
 import { readInstallState, recordInstallTransaction } from "./core/state.js";
 import { applyRemove, planRemove } from "./core/remove.js";
 import { applyUninstall, buildUninstallPlan, formatUninstallPlan, uninstallGlobalCli, } from "./core/uninstall.js";
-import { evaluateInstalledProfile, formatInstalledProfileStatus, recordInstalledProfile, } from "./core/profile-state.js";
-import { formatRecommendations, personalizeRecommendations, profileManifestPackages, recommendPackages, scanProject, TESTED_PROFILES, } from "./core/recommend.js";
+import { evaluateInstalledProfile, formatInstalledProfileStatus, } from "./core/profile-state.js";
+import { formatRecommendations, personalizeRecommendations, profileManifestPackages, recommendPackages, RECOMMENDATION_BOUNDARY, scanProject, TESTED_PROFILES, } from "./core/recommend.js";
 import { buildImprovementCycle, formatImprovementCycle, recordImprovementOutcome, writeImprovementCycle, } from "./core/improve.js";
 import { applySyncPlan, buildSyncPlan } from "./core/sync.js";
 import { createPackage, packPackage, publishLocalPackage, publishRemotePackage, searchLocalRegistry, } from "./core/registry.js";
@@ -33,7 +33,7 @@ import { generateSigningKeys, signJsonFile, verifyJsonFile, } from "./core/signi
 import { applyPortableImport, exportPortableLoadout, planPortableImport, } from "./core/portable.js";
 import { applyCodexMcpConfigPlan, defaultCodexMcpConfigPath, planCodexMcpConfig, } from "./core/codex-mcp.js";
 import { formatDemoResult, runIsolatedDemo } from "./core/demo.js";
-import { catalogTrustStage, resolveCatalogProfile } from "./core/profiles.js";
+import { catalogTrustStage, formatCatalogTrustStage, resolveCatalogProfile, } from "./core/profiles.js";
 import { discoverHackerNewsRepositories } from "./core/community.js";
 import { discoverPrivateRepositories } from "./core/private-discovery.js";
 import { defaultGitHubDiscoveryQueries, discoverGitHubRepositories, } from "./core/github-discovery.js";
@@ -45,7 +45,7 @@ import { compileConversion, } from "./core/conversion.js";
 import { writeFileAtomically } from "./core/atomic-file.js";
 import { formatCanaryResult, runCanary } from "./core/canary.js";
 import { startDashboardServer } from "./dashboard.js";
-import { applyPreparedCatalogInstall, formatPreparedCatalogInstall, prepareCatalogInstall, } from "./core/catalog-install.js";
+import { applyPreparedCatalogInstall, formatCatalogApplyGuidance, formatPreparedCatalogInstall, prepareCatalogInstall, } from "./core/catalog-install.js";
 import { formatInstalledSkillInventory, scanInstalledSkills, } from "./core/skill-inventory.js";
 import { enrichInventoryWithProvenance, formatProvenanceSummary, resolveCatalogSkillIndex, } from "./core/provenance.js";
 import { compareSkill, formatSkillComparison } from "./core/skill-compare.js";
@@ -183,14 +183,14 @@ async function runSetup(options) {
     try {
         if (!mode) {
             if (!interactive) {
-                console.log("Loadout is CLI-first. Run `loadout setup --mode stable` for the recommended daily driver, `--mode power` for broader opt-in skills, or `--mode maximum` to download the screened library without activating it.");
+                console.log("Loadout is CLI-first. Run `loadout setup --mode stable` for Loadout's bounded policy selection, `--mode power` for broader opt-in skills, or `--mode maximum` to download the screened library without activating it.");
                 return;
             }
             reader = createInterface({
                 input: process.stdin,
                 output: process.stdout,
             });
-            const answer = (await reader.question("Choose a loadout: [1] Stable Daily Driver (recommended), [2] Power Boost, [3] Maximum Library, [4] Custom: ")).trim();
+            const answer = (await reader.question("Choose a loadout: [1] Stable Daily Driver (Loadout policy selection), [2] Power Boost, [3] Maximum Library, [4] Custom: ")).trim();
             mode =
                 answer === "2"
                     ? "power"
@@ -228,7 +228,7 @@ async function runSetup(options) {
         let riskApproved = Boolean(options.approveRisk);
         if (!approved) {
             if (!interactive) {
-                console.log("Preview complete; nothing was changed. Re-run with --yes to install this exact screened plan.");
+                console.log(formatCatalogApplyGuidance(Boolean(risky)));
                 return;
             }
             reader ??= createInterface({
@@ -258,7 +258,6 @@ async function runSetup(options) {
         const snapshotId = await applyPreparedCatalogInstall(prepared, {
             approveRisk: riskApproved,
         });
-        await recordInstalledProfile(prepared);
         console.log(`\nLoadout installed ${prepared.entries.length} repositories for ${prepared.agents.length} agent(s). Snapshot: ${snapshotId}`);
         console.log("Next: `loadout status`, `loadout optimize --project .`, or `loadout autopilot --yes` for opt-in daily read-only discovery and update checks.");
     }
@@ -266,7 +265,7 @@ async function runSetup(options) {
         reader?.close();
     }
 }
-const LOADOUT_VERSION = "0.3.1";
+const LOADOUT_VERSION = "0.4.0";
 function durableSchedulerLauncher() {
     return [
         join(dirname(process.execPath), process.platform === "win32" ? "npx.cmd" : "npx"),
@@ -730,8 +729,8 @@ for (const workflow of ["activate", "optimize"]) {
     program
         .command(workflow)
         .description(workflow === "activate"
-        ? "Select and activate reviewed library skills for a project"
-        : "Scan a project and propose the best reviewed active-set additions")
+        ? "Select and activate inspected library skills for a project"
+        : "Scan a project and propose rule-selected inspected active-set additions")
         .option("--project <path>", "project directory to scan", ".")
         .option("--agents <ids>", "comma-separated agent ids")
         .option("--limit <count>", "maximum active skills per agent", "40")
@@ -1055,6 +1054,7 @@ program
         ? JSON.stringify({
             signals,
             recommendations,
+            recommendationBoundary: RECOMMENDATION_BOUNDARY,
             personalization: options.agent
                 ? {
                     agent: options.agent,
@@ -1066,7 +1066,7 @@ program
 });
 program
     .command("profiles")
-    .description("List tested Loadout profiles or inspect one profile")
+    .description("List Loadout policy profiles or inspect one profile")
     .argument("[name]", "profile name")
     .option("--json", "emit machine-readable JSON")
     .option("--apply-to <path>", "add the selected profile packages to a manifest")
@@ -1183,7 +1183,7 @@ program
     .description("Take ownership of one explicitly selected installed skill without changing its bytes")
     .argument("<skill>", "installed skill name, directory name, or exact path")
     .requiredOption("--agent <id>", "agent that owns the installed skill")
-    .option("--refresh-provenance", "rebuild the reviewed catalog skill index")
+    .option("--refresh-provenance", "rebuild the inspected catalog skill index")
     .option("--yes", "record ownership; otherwise show a dry-run plan")
     .option("--json", "emit machine-readable JSON")
     .action(async (skill, options) => {
@@ -1218,7 +1218,7 @@ program
     .description("Compare an installed or reviewed skill with evidence-related catalog alternatives without changing anything")
     .argument("<skill>", "installed skill name, directory name, or catalog package id")
     .option("--agent <id>", "select one installed agent when names are ambiguous")
-    .option("--refresh", "rebuild the reviewed catalog skill index")
+    .option("--refresh", "rebuild the inspected catalog skill index")
     .option("--offline", "never fetch; use the existing local index only")
     .option("--limit <count>", "maximum alternatives to show", "10")
     .option("--json", "emit the complete machine-readable comparison")
@@ -1559,6 +1559,7 @@ program
                 category: pkg.category,
                 tier: pkg.tier,
                 trustStage: catalogTrustStage(pkg),
+                evidenceLabel: formatCatalogTrustStage(catalogTrustStage(pkg)),
             },
             ranking: explainCatalogScore(pkg),
         }, null, 2));
@@ -1580,7 +1581,7 @@ program
         const updated = pkg.lastUpdatedAt
             ? ` — updated ${pkg.lastUpdatedAt.slice(0, 10)}`
             : "";
-        console.log(`${pkg.displayName} [${pkg.tier}; ${catalogTrustStage(pkg)}] ★${pkg.stars ?? "?"} — ${pkg.repository}${topics}${updated}`);
+        console.log(`${pkg.displayName} [${pkg.tier}; ${formatCatalogTrustStage(catalogTrustStage(pkg))}] ★${pkg.stars ?? "?"} — ${pkg.repository}${topics}${updated}`);
     }
     for (const failure of result.failures)
         console.error(`Warning: could not refresh ${failure.repository}: ${failure.error}`);
@@ -1648,7 +1649,7 @@ candidate
     .description("Convert a reviewed dossier into a catalog-record proposal; never edits the catalog")
     .argument("<dossier>", "persisted candidate dossier JSON")
     .requiredOption("--id <id>", "lowercase kebab-case catalog id")
-    .requiredOption("--category <category>", "reviewed catalog category")
+    .requiredOption("--category <category>", "inspected catalog category")
     .requiredOption("--platforms <ids>", "explicitly reviewed comma-separated platforms: windows,macos,linux")
     .option("--display-name <name>", "reviewed display name")
     .option("--description <text>", "reviewed description")
@@ -2590,13 +2591,12 @@ program
         });
         console.log(formatPreparedCatalogInstall(prepared));
         if (!options.yes) {
-            console.log("Preview complete; nothing was changed. Use --yes after reviewing to install this exact plan.");
+            console.log(formatCatalogApplyGuidance(prepared.entries.some((entry) => entry.safety.approvalRequired)));
             return;
         }
         const snapshotId = await applyPreparedCatalogInstall(prepared, {
             approveRisk: options.approveRisk,
         });
-        await recordInstalledProfile(prepared);
         console.log(`Installed ${prepared.entries.length} repositories as one transaction. Snapshot: ${snapshotId}`);
         return;
     }
@@ -2671,7 +2671,9 @@ program
         const chosen = options.snapshot ?? snapshotIds.at(-1);
         if (!chosen)
             throw new Error("No Loadout snapshots found");
-        await restoreSnapshot(await readSnapshot(chosen));
+        await restoreSnapshot(await readSnapshot(chosen), {
+            requireUnchangedPostMutationState: true,
+        });
         return chosen;
     });
     console.log(`Restored snapshot ${selected}`);
@@ -2716,7 +2718,6 @@ program
         profileSnapshotId = await applyPreparedCatalogInstall(prepared, {
             approveRisk: options.approveRisk,
         });
-        await recordInstalledProfile(prepared);
         if (!options.json)
             console.log(`Applied reviewed ${saved.mode} profile changes. Snapshot: ${profileSnapshotId}`);
         profile = await evaluateInstalledProfile(catalog);
@@ -2883,7 +2884,12 @@ for (const command of program.commands)
     if (HIDDEN_FROM_FIRST_SCREEN.has(command.name()))
         command._hidden = true;
 program.addHelpText("after", "\nStart here: `loadout guide` shows the safe everyday path. `loadout advanced` lists the retained maintainer and integration commands.\n");
-program.action(printBeginnerGuide);
+program.argument("[unknown-command]");
+program.action((unknownCommand) => {
+    if (unknownCommand)
+        throw new Error(`Unknown command '${unknownCommand}'. Run 'loadout --help' to list available commands.`);
+    printBeginnerGuide();
+});
 try {
     await recoverPendingTransactions();
     await program.parseAsync();

package/dist/src/core/adapters.js

@@ -140,6 +140,16 @@ export function adapterCapabilities(agent) {
         throw new Error(`No adapter capability declaration for '${agent}'`);
     return found;
 }
+/**
+ * Return the display names of agents with an explicitly declared native skill
+ * directory. This is a filesystem-support boundary, not a claim about native
+ * application runtime behavior.
+ */
+export function supportedAdapterNames(adapters = ADAPTER_CAPABILITIES) {
+    return adapters
+        .filter((adapter) => adapter.components.skill === "native")
+        .map((adapter) => adapter.displayName);
+}
 /**
  * Produce a read-only native-skill plan for one agent.  This is deliberately
  * narrower than package normalization: adapters may only target a directory

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 });
+}