loadout-ai 0.3.1 → 0.4.0

package/dist/src/core/install.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { cp, lstat, rm } from "node:fs/promises";
+import { cp, lstat, readdir, rm } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, posix, relative, win32, } from "node:path";
 import { ensureDirectory, loadoutHome } from "./paths.js";
 import { planAdapterSkillInstall } from "./adapters.js";
@@ -117,7 +117,32 @@ async function assertActiveTargetsUnoccupied(plans, options = {}) {
         ...new Set(plans.flatMap((plan) => plan.files.map((file) => file.target))),
     ])
         try {
-            await lstat(target);
+            const info = await lstat(target);
+            if (info.isDirectory() && !info.isSymbolicLink()) {
+                const queue = [target];
+                let entriesChecked = 0;
+                let empty = true;
+                while (queue.length && empty) {
+                    const directory = queue.pop();
+                    for (const entry of await readdir(directory, {
+                        withFileTypes: true,
+                    })) {
+                        entriesChecked += 1;
+                        if (entriesChecked > 10_000) {
+                            empty = false;
+                            break;
+                        }
+                        if (entry.isDirectory() && !entry.isSymbolicLink())
+                            queue.push(join(directory, entry.name));
+                        else {
+                            empty = false;
+                            break;
+                        }
+                    }
+                }
+                if (empty)
+                    continue;
+            }
             occupied.push(target);
         }
         catch (error) {
@@ -202,6 +227,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 +292,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 +310,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 +318,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 +375,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,
+        },
+    };
+}

package/dist/src/core/recommend.js

@@ -17,6 +17,11 @@ const SIGNAL_FILES = new Set([
     "playwright.config.ts",
     ".git",
 ]);
+/** Additive machine-readable boundary for every rule-selected recommendation list. */
+export const RECOMMENDATION_BOUNDARY = Object.freeze({
+    selectionMethod: "deterministic-project-signal-rules",
+    qualityEvidence: "not-established",
+});
 export async function scanProject(root = process.cwd()) {
     const absolute = resolve(root);
     const entries = await readdir(absolute, { withFileTypes: true });
@@ -132,7 +137,7 @@ export function personalizeRecommendations(recommendations, signals, outcomes, a
 }
 export const TESTED_PROFILES = {
     stable: {
-        description: "Recommended 30-skill daily driver from four pinned, SPDX-identified sources with no extra static-risk approvals.",
+        description: "Loadout policy selection: 30 skills from four pinned, SPDX-identified sources with no extra static-risk approvals.",
         packages: [...STABLE_BOOST_PACKAGE_IDS],
     },
     web: {
@@ -144,7 +149,7 @@ export const TESTED_PROFILES = {
         packages: ["superpowers", "context7", "github-mcp-server"],
     },
     maximum: {
-        description: "Broad reviewed toolkit; always review MCP permissions before applying.",
+        description: "Broad inspected toolkit; always review MCP permissions before applying.",
         packages: [
             "superpowers",
             "context7",
@@ -171,7 +176,8 @@ export function formatRecommendations(signals, recommendations) {
         `Project: ${basename(signals.root)}`,
         `Detected: ${[...signals.languages, ...signals.frameworks].join(", ") || "no known project signals"}`,
         "",
-        "Recommendations:",
+        "Rule-based project suggestions:",
+        "Rules use detected project signals and catalog membership; they do not prove package quality.",
     ];
     if (!recommendations.length)
         lines.push("  No matching catalog packages found.");

package/dist/src/core/runtime-tools.js

@@ -5,7 +5,7 @@ import { promisify } from "node:util";
 import { writeFileAtomically } from "./atomic-file.js";
 import { detectAgents, loadoutHome, userHome } from "./paths.js";
 import { parseRuntimeToolRecipe, renderRuntimeRecipeValue, resolveRuntimeRecipePath, } from "./runtime-tool-recipe.js";
-import { createSnapshot, readSnapshot, restoreSnapshot } from "./snapshot.js";
+import { createSnapshot, readSnapshot, recordSnapshotPostMutationState, restoreSnapshot, } from "./snapshot.js";
 const execFileAsync = promisify(execFile);
 function deepFreeze(value) {
     if (value && typeof value === "object" && !Object.isFrozen(value)) {
@@ -399,7 +399,9 @@ export async function applyRuntimeToolPlan(plan, options) {
         if (!installed)
             throw new Error(`${plan.recipe.displayName} is not managed by Loadout`);
         const snapshot = await readSnapshot(installed.snapshotId);
-        await restoreSnapshot(snapshot);
+        await restoreSnapshot(snapshot, {
+            requireUnchangedPostMutationState: true,
+        });
         delete state.tools[plan.recipe.id];
         await writeState(state, plan.stateHome);
         return { action: "remove", snapshotId: snapshot.id };
@@ -444,6 +446,7 @@ export async function applyRuntimeToolPlan(plan, options) {
             agents: plan.agents.map((agent) => agent.id),
             runtimeRoot: plan.runtimeRoot,
         };
+        await recordSnapshotPostMutationState(snapshot);
         await writeState(state, plan.stateHome);
         return { action: "install", snapshotId: snapshot.id };
     }

package/dist/src/core/scheduler.js

@@ -4,7 +4,7 @@ import { dirname, win32, join } from "node:path";
 import { promisify } from "node:util";
 import { writeFileAtomically } from "./atomic-file.js";
 import { ensureDirectory, loadoutHome, userHome } from "./paths.js";
-import { createSnapshot } from "./snapshot.js";
+import { createSnapshot, recordSnapshotPostMutationState } from "./snapshot.js";
 import { beginTransaction, completeTransaction, markTransactionCommitting, recoverPendingTransactions, rollbackTransaction, } from "./transaction.js";
 const execFileAsync = promisify(execFile);
 function parseTime(value) {
@@ -238,6 +238,7 @@ export async function applyNativeSchedulerBundle(plans, runner = defaultRunner)
         if (plans[0].action === "unschedule")
             for (const file of plans.flatMap((plan) => plan.files))
                 await rm(file.path, { force: true });
+        await recordSnapshotPostMutationState(snapshot);
         await completeTransaction(transaction);
     }
     catch (error) {

package/dist/src/core/snapshot.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { readFile, writeFile, mkdir, readdir, rm, lstat, } from "node:fs/promises";
+import { readFile, writeFile, mkdir, readdir, rename, rm, lstat, } from "node:fs/promises";
 import { dirname, join, resolve, sep } from "node:path";
 import { loadoutHome, ensureDirectory, userHome } from "./paths.js";
 export async function createSnapshot(paths, options = {}) {
@@ -41,7 +41,7 @@ export async function createSnapshot(paths, options = {}) {
         if (!info.isDirectory())
             throw new Error(`Refusing unsupported snapshot target: ${path}`);
         snapshot.files.push({ path, existed: true, directory: true });
-        const entries = await readdir(path, { withFileTypes: true });
+        const entries = (await readdir(path, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name));
         for (const entry of entries) {
             const child = join(path, entry.name);
             if (entry.isSymbolicLink())
@@ -55,6 +55,8 @@ export async function createSnapshot(paths, options = {}) {
                     content: (await readFile(child)).toString("base64"),
                     encoding: "base64",
                 });
+            else
+                throw new Error(`Refusing unsupported snapshot target: ${child}`);
         }
     }
     for (const path of snapshot.roots)
@@ -67,8 +69,10 @@ export async function createSnapshot(paths, options = {}) {
     }
     return snapshot;
 }
-export async function restoreSnapshot(snapshot) {
+export async function restoreSnapshot(snapshot, options = {}) {
     validateSnapshot(snapshot);
+    if (options.requireUnchangedPostMutationState)
+        await assertUnchangedPostMutationState(snapshot);
     for (const root of snapshot.roots)
         await rm(root, { recursive: true, force: true });
     for (const directory of snapshot.files
@@ -84,6 +88,39 @@ export async function restoreSnapshot(snapshot) {
             : (file.content ?? ""));
     }
 }
+/** Attach the committed state used to make later user-requested rollback safe. */
+export async function recordSnapshotPostMutationState(snapshot) {
+    const postMutation = await createSnapshot(snapshot.roots, { persist: false });
+    snapshot.postMutationFiles = postMutation.files;
+    validateSnapshot(snapshot);
+    const directory = join(loadoutHome(), "snapshots");
+    await ensureDirectory(directory);
+    const target = join(directory, `${snapshot.id}.json`);
+    const temporary = `${target}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(temporary, JSON.stringify(snapshot, null, 2), {
+        mode: 0o600,
+        flag: "wx",
+    });
+    await rename(temporary, target);
+}
+async function assertUnchangedPostMutationState(snapshot) {
+    if (!snapshot.postMutationFiles)
+        throw new Error("Explicit rollback refused: this legacy snapshot has no post-mutation evidence. Preserve current files and use a newer snapshot.");
+    let current;
+    try {
+        current = (await createSnapshot(snapshot.roots, { persist: false })).files;
+    }
+    catch (error) {
+        throw new Error(`Explicit rollback refused because the current filesystem cannot be verified: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const expected = new Map(snapshot.postMutationFiles.map((file) => [file.path, file]));
+    const actual = new Map(current.map((file) => [file.path, file]));
+    const changed = [...new Set([...expected.keys(), ...actual.keys()])]
+        .filter((path) => JSON.stringify(expected.get(path)) !== JSON.stringify(actual.get(path)))
+        .sort();
+    if (changed.length)
+        throw new Error(`Explicit rollback refused because files changed after the snapshot: ${changed.slice(0, 10).join(", ")}. Preserve or review these changes before rollback.`);
+}
 export async function readSnapshot(id) {
     if (!isSnapshotId(id))
         throw new Error(`Invalid snapshot id: ${id}`);
@@ -167,42 +204,50 @@ export function validateSnapshot(value) {
         if (roots.some((candidate, candidateIndex) => candidateIndex !== index && isInside(candidate, root)))
             throw new Error("Snapshot roots must be unique and non-overlapping");
     }
+    validateSnapshotFiles(value.files, roots, "Snapshot");
+    if (value.postMutationFiles !== undefined) {
+        if (!Array.isArray(value.postMutationFiles))
+            throw new Error("Snapshot post-mutation files are invalid");
+        validateSnapshotFiles(value.postMutationFiles, roots, "Snapshot post-mutation");
+    }
+    return value;
+}
+function validateSnapshotFiles(files, roots, label) {
     const paths = new Set();
-    for (const [index, file] of value.files.entries()) {
+    for (const [index, file] of files.entries()) {
         if (!isRecord(file) ||
             typeof file.path !== "string" ||
             typeof file.existed !== "boolean" ||
             (file.directory !== undefined && typeof file.directory !== "boolean") ||
             (file.content !== undefined && typeof file.content !== "string") ||
             (file.encoding !== undefined && file.encoding !== "base64"))
-            throw new Error(`Snapshot file ${index} is invalid`);
+            throw new Error(`${label} file ${index} is invalid`);
         const filePath = file.path;
         if (resolve(filePath) !== filePath)
-            throw new Error(`Snapshot file ${index} path must be absolute and normalized`);
+            throw new Error(`${label} file ${index} path must be absolute and normalized`);
         if (paths.has(filePath))
-            throw new Error(`Snapshot file ${index} duplicates another path`);
+            throw new Error(`${label} file ${index} duplicates another path`);
         paths.add(filePath);
         if (!roots.some((root) => isInside(root, filePath)))
-            throw new Error(`Snapshot file ${index} escapes its declared roots`);
+            throw new Error(`${label} file ${index} escapes its declared roots`);
         if (!file.existed) {
             if (file.directory !== undefined ||
                 file.content !== undefined ||
                 file.encoding !== undefined)
-                throw new Error(`Missing snapshot file ${index} must not contain data`);
+                throw new Error(`Missing ${label.toLowerCase()} file ${index} must not contain data`);
         }
         else if (file.directory) {
             if (file.content !== undefined || file.encoding !== undefined)
-                throw new Error(`Snapshot directory ${index} must not contain bytes`);
+                throw new Error(`${label} directory ${index} must not contain bytes`);
         }
         else if (typeof file.content !== "string" ||
             file.encoding !== "base64" ||
             !isCanonicalBase64(file.content))
-            throw new Error(`Snapshot file ${index} bytes are invalid`);
+            throw new Error(`${label} file ${index} bytes are invalid`);
     }
     for (const [index, root] of roots.entries())
         if (!paths.has(root))
-            throw new Error(`Snapshot root ${index} has no matching file record`);
-    return value;
+            throw new Error(`${label} root ${index} has no matching file record`);
 }
 function isCanonicalBase64(value) {
     if (value.length % 4 !== 0)

package/dist/src/core/state.js

@@ -123,7 +123,7 @@ export async function hashDirectory(root) {
     await visit(root);
     return files;
 }
-export async function recordInstall(plan, snapshotId, metadata = {}) {
+export async function recordInstall(plan, snapshotId, metadata = {}, options = {}) {
     const record = await createInstallRecord(plan, snapshotId, metadata);
     const state = await readInstallState();
     state.installs = [
@@ -131,6 +131,13 @@ export async function recordInstall(plan, snapshotId, metadata = {}) {
         record,
     ];
     state.activations = mergeActivationRecords(state.activations, activationRecordsForPlan(plan, metadata));
+    await options.verifyBeforeWrite?.();
+    if (options.expectedFiles) {
+        const actual = [...record.files].sort((left, right) => left.path.localeCompare(right.path));
+        const expected = [...options.expectedFiles].sort((left, right) => left.path.localeCompare(right.path));
+        if (JSON.stringify(actual) !== JSON.stringify(expected))
+            throw new Error("Installed files changed before ownership could be recorded.");
+    }
     await writeInstallState(state);
     return record;
 }

package/dist/src/core/transaction.js

@@ -2,7 +2,7 @@ import { lstat, mkdir, readdir, readFile, rename, rm, writeFile, } from "node:fs
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { ensureDirectory, loadoutHome } from "./paths.js";
-import { createSnapshot, readSnapshot, restoreSnapshot } from "./snapshot.js";
+import { createSnapshot, readSnapshot, recordSnapshotPostMutationState, restoreSnapshot, } from "./snapshot.js";
 import { acquireFileLock, withFileLock, } from "./file-lock.js";
 export const transactionRoot = () => join(loadoutHome(), "staging");
 const transactionPreparingRoot = () => join(loadoutHome(), "staging-preparing");
@@ -136,6 +136,7 @@ export async function runMutationTransaction(prepare, mutate) {
         });
         await markTransactionCommitting(transaction);
         const result = await mutate(prepared.value, snapshot);
+        await recordSnapshotPostMutationState(snapshot);
         await completeTransaction(transaction);
         return { snapshotId: snapshot.id, result };
     }

package/dist/src/core/uninstall.js

@@ -40,8 +40,32 @@ async function removeEmptyManagedDirectories(plans) {
     ].sort((left, right) => right.length - left.length);
     for (const directory of candidates) {
         try {
-            if ((await readdir(directory)).length === 0)
-                await rmdir(directory);
+            const queue = [directory];
+            const visited = [directory];
+            let entriesChecked = 0;
+            let empty = true;
+            while (queue.length && empty) {
+                const current = queue.pop();
+                for (const entry of await readdir(current, { withFileTypes: true })) {
+                    entriesChecked += 1;
+                    if (entriesChecked > 10_000) {
+                        empty = false;
+                        break;
+                    }
+                    if (entry.isDirectory() && !entry.isSymbolicLink()) {
+                        const child = resolve(current, entry.name);
+                        queue.push(child);
+                        visited.push(child);
+                    }
+                    else {
+                        empty = false;
+                        break;
+                    }
+                }
+            }
+            if (empty)
+                for (const current of visited.sort((left, right) => right.length - left.length))
+                    await rmdir(current);
         }
         catch {
             // Missing and non-empty directories are both safe to leave alone.

package/dist/src/dashboard.js

@@ -8,7 +8,7 @@ import { inspectAgents } from "./core/agent-inspection.js";
 import { loadEffectiveCatalog, rankCatalog } from "./core/catalog.js";
 import { buildUpdatePlan } from "./core/update.js";
 import { buildHealthReport } from "./core/health.js";
-import { recommendPackages, scanProject, TESTED_PROFILES, } from "./core/recommend.js";
+import { recommendPackages, RECOMMENDATION_BOUNDARY, scanProject, TESTED_PROFILES, } from "./core/recommend.js";
 import { searchLocalRegistry } from "./core/registry.js";
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { applySyncPlan, buildSyncPlan } from "./core/sync.js";
@@ -318,6 +318,7 @@ async function route(request, response, context) {
             const signals = await scanProject(process.cwd());
             await sendJson(response, 200, {
                 signals,
+                recommendationBoundary: RECOMMENDATION_BOUNDARY,
                 recommendations: recommendPackages(signals, await loadEffectiveCatalog()),
             });
             return;
@@ -368,7 +369,9 @@ export function createDashboardServer(options = {}) {
         buildSync: options.buildSync ?? buildSyncPlan,
         applySync: options.applySync ?? applySyncPlan,
         rollback: options.rollback ??
-            (async (snapshotId) => withMutationLock(async () => restoreSnapshot(await readSnapshot(snapshotId)))),
+            (async (snapshotId) => withMutationLock(async () => restoreSnapshot(await readSnapshot(snapshotId), {
+                requireUnchangedPostMutationState: true,
+            }))),
         token: randomBytes(32).toString("hex"),
     };
     return createServer((request, response) => {

package/dist/src/shared/schemas.js

@@ -41,8 +41,26 @@ export const componentCompatibilitySchema = z.enum([
     "unsupported",
 ]);
 export const safetyRiskLevelSchema = z.enum(["safe", "review", "blocked"]);
+export const readmeClaimEvidenceClassSchema = z.enum([
+    "structural",
+    "unit-verified",
+    "integration-verified",
+    "live-verified",
+    "platform-verified",
+    "human-reviewed",
+    "benchmarked",
+    "policy-selected",
+]);
+export const readmeClaimStatusSchema = z.enum([
+    "proven",
+    "bounded",
+    "unfulfilled",
+]);
 const text = z.string().trim().min(1, "must not be empty");
 const optionalText = text.optional();
+const readmeClaimIdSchema = z
+    .string()
+    .regex(/^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)*$/, "must be a safe dotted identifier");
 const sha256 = z.string().regex(/^[a-f0-9]{64}$/i, "must be a SHA-256 hash");
 const gitSha = z.string().regex(/^[a-f0-9]{40}$/i, "must be a full Git SHA");
 const repository = z
@@ -348,6 +366,45 @@ export const loadoutLockfileSchema = z
         .optional(),
 })
     .passthrough();
+export const readmeClaimSchema = z
+    .object({
+    id: readmeClaimIdSchema,
+    section: text,
+    summary: text,
+    evidenceClass: readmeClaimEvidenceClassSchema,
+    status: readmeClaimStatusSchema,
+    evidence: z.array(text),
+    externalPrerequisites: z.array(text).optional(),
+})
+    .strict()
+    .superRefine((claim, context) => {
+    if (claim.status === "proven" && claim.evidence.length === 0) {
+        context.addIssue({
+            code: "custom",
+            path: ["evidence"],
+            message: "proven claims require at least one authoritative evidence reference",
+        });
+    }
+});
+export const readmeClaimManifestSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    claims: z.array(readmeClaimSchema).min(1),
+})
+    .strict()
+    .superRefine((manifest, context) => {
+    const seen = new Set();
+    for (const [index, claim] of manifest.claims.entries()) {
+        if (seen.has(claim.id)) {
+            context.addIssue({
+                code: "custom",
+                path: ["claims", index, "id"],
+                message: "must be unique",
+            });
+        }
+        seen.add(claim.id);
+    }
+});
 /** Compact, path-aware errors suitable for CLI and persisted-data diagnostics. */
 export function formatSchemaError(error) {
     return error.issues

package/docs/FEATURE_TEST_MATRIX.md

@@ -121,8 +121,10 @@ reruns and diagnosis.
 | `npm run format:check`       | Repository formatting                                                   | Exit 0; no files changed.                          |
 | `npm run lint`               | TypeScript lint rules                                                   | Exit 0.                                            |
 | `npm run typecheck`          | TypeScript contract                                                     | Exit 0.                                            |
+| `npm run check:evidence`     | Catalog/discovery attribution, README claims, and release boundaries    | Exit 0; no claim is silently promoted.             |
 | `npm test`                   | Unit, integration, native filesystem, safety, and regression suites     | All tests pass.                                    |
 | `npm run test:e2e:cli`       | Disposable scan → compare → optimize → apply → rollback journey         | Prints a successful CLI product flow.              |
+| `npm run test:e2e:readme`    | Isolated library/activation/manifest/card/rollback journey              | Prints README product flow success.                |
 | `npm run test:package`       | `npm pack`, install outside the checkout, packaged CLI install/rollback | Prints package smoke success.                      |
 | `npm run test:performance`   | Seven scans of 1,000 real on-disk skill directories                     | p95 remains below the enforced five-second budget. |
 | `npm run test:e2e:dashboard` | Loopback dashboard first-run browser test                               | Playwright passes; no real profile is used.        |
@@ -131,6 +133,20 @@ The dashboard test needs a Playwright browser. If the browser executable is abse
 run `npx playwright install chromium` once; that download is not a Loadout product
 side effect.
 
+The focused regression contract for the v0.3.x profile lifecycle is:
+
+```bash
+npx vitest run tests/upgrade.test.ts tests/profile-state.test.ts \
+  tests/update.test.ts tests/uninstall.test.ts tests/install.test.ts \
+  tests/mcp-recipes.test.ts tests/cli-help.test.ts
+```
+
+It verifies preview/apply upgrade behavior, saved-profile refresh detection, safe
+profile reconciliation, complete-uninstall drift protection, recursively empty target
+recovery, and the separation between model-provider access declarations and service
+credentials. These are disposable automated filesystem tests; they do not prove that
+a native agent consumes the resulting files or that a host scheduler/keychain works.
+
 ## 2. Read-only inventory, ranking, and recommendation track (R; some N)
 
 ```bash