loadout-ai 0.3.1 → 0.4.1

package/dist/src/core/recommend.js

@@ -15,8 +15,53 @@ const SIGNAL_FILES = new Set([
     "next.config.mjs",
     "vite.config.ts",
     "playwright.config.ts",
+    "SECURITY.md",
     ".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",
+});
+const SIGNAL_LABELS = {
+    "javascript/typescript": "TypeScript",
+    playwright: "Playwright",
+    "node-cli": "Node CLI",
+    "npm-package": "npm package",
+    release: "release automation",
+    mcp: "MCP tooling",
+    security: "security policy",
+    commander: "Commander",
+    zod: "Zod",
+    vitest: "Vitest",
+    jest: "Jest",
+};
+const SIGNAL_DISPLAY_ORDER = [
+    "javascript/typescript",
+    "playwright",
+    "node-cli",
+    "npm-package",
+    "release",
+    "mcp",
+    "security",
+    "commander",
+    "zod",
+    "vitest",
+    "jest",
+];
+export function formatDetectedSignals(signals) {
+    const values = new Set([
+        ...signals.languages,
+        ...signals.frameworks,
+        ...signals.roles,
+        ...signals.tools,
+    ]);
+    const ordered = [
+        ...SIGNAL_DISPLAY_ORDER.filter((value) => values.delete(value)),
+        ...values,
+    ];
+    return ordered.map((value) => SIGNAL_LABELS[value] ?? value).join(", ");
+}
 export async function scanProject(root = process.cwd()) {
     const absolute = resolve(root);
     const entries = await readdir(absolute, { withFileTypes: true });
@@ -26,6 +71,8 @@ export async function scanProject(root = process.cwd()) {
         .sort();
     const languages = new Set();
     const frameworks = new Set();
+    const roles = new Set();
+    const tools = new Set();
     if (files.includes("package.json")) {
         languages.add("javascript/typescript");
         try {
@@ -39,8 +86,28 @@ export async function scanProject(root = process.cwd()) {
                 frameworks.add("vue");
             if (deps.svelte)
                 frameworks.add("svelte");
-            if (deps.playwright || deps["@playwright/test"])
+            if (deps.playwright || deps["@playwright/test"]) {
                 frameworks.add("playwright");
+                tools.add("playwright");
+            }
+            if (deps.vitest)
+                tools.add("vitest");
+            if (deps.jest)
+                tools.add("jest");
+            if (deps.commander)
+                tools.add("commander");
+            if (deps.zod)
+                tools.add("zod");
+            if (pkg.bin)
+                roles.add("node-cli");
+            if (pkg.publishConfig || pkg.private === false)
+                roles.add("npm-package");
+            const scripts = pkg.scripts ?? {};
+            if (scripts.prepack ||
+                Object.keys(scripts).some((name) => /(?:package|release)/.test(name)))
+                roles.add("release");
+            if ((pkg.keywords ?? []).some((keyword) => /(?:^|-)mcp(?:-|$)/i.test(keyword)))
+                roles.add("mcp");
         }
         catch {
             /* malformed project metadata is reported through an empty framework set */
@@ -60,22 +127,37 @@ export async function scanProject(root = process.cwd()) {
         languages.add(".net");
     if (files.some((file) => file.startsWith("next.config")))
         frameworks.add("next.js");
-    if (files.includes("playwright.config.ts"))
+    if (files.includes("playwright.config.ts")) {
         frameworks.add("playwright");
+        tools.add("playwright");
+    }
+    if (files.includes("SECURITY.md"))
+        roles.add("security");
     return {
         root: absolute,
         languages: [...languages],
         frameworks: [...frameworks],
+        roles: [...roles],
+        tools: [...tools],
         files,
     };
 }
 export function recommendPackages(signals, catalog) {
-    const ids = new Set(catalog.map((pkg) => pkg.id));
+    const packages = new Map(catalog.map((pkg) => [pkg.id, pkg]));
     const result = [];
     const add = (packageId, reason, confidence) => {
-        if (ids.has(packageId) &&
-            !result.some((item) => item.packageId === packageId))
-            result.push({ packageId, reason, confidence });
+        const pkg = packages.get(packageId);
+        if (pkg && !result.some((item) => item.packageId === packageId))
+            result.push({
+                packageId,
+                reason,
+                confidence,
+                kind: pkg.components?.includes("skill")
+                    ? "skill-library"
+                    : pkg.components?.some((component) => component === "mcp" || component === "plugin")
+                        ? "mcp-runtime"
+                        : "unavailable",
+            });
     };
     add("superpowers", "Useful engineering planning, testing, and review workflows for most repositories.", "high");
     add("context7", "Current library documentation helps agents avoid outdated APIs.", signals.languages.length ? "high" : "medium");
@@ -124,6 +206,7 @@ export function personalizeRecommendations(recommendations, signals, outcomes, a
         packageId: item.packageId,
         reason: item.reason,
         confidence: item.confidence,
+        kind: item.kind,
         ...(item.localOutcomeAdjustment !== undefined
             ? { localOutcomeAdjustment: item.localOutcomeAdjustment }
             : {}),
@@ -132,7 +215,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 +227,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",
@@ -169,13 +252,22 @@ export function profileManifestPackages(profile, catalog) {
 export function formatRecommendations(signals, recommendations) {
     const lines = [
         `Project: ${basename(signals.root)}`,
-        `Detected: ${[...signals.languages, ...signals.frameworks].join(", ") || "no known project signals"}`,
+        `Detected: ${formatDetectedSignals(signals) || "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.");
-    for (const item of recommendations)
-        lines.push(`  ${item.packageId} [${item.confidence}] — ${item.reason}`);
+    const kindLabels = {
+        "skill-library": "skill library",
+        "mcp-runtime": "MCP/runtime setup",
+        unavailable: "unavailable",
+    };
+    for (const item of recommendations) {
+        lines.push(`  ${item.packageId} [${item.confidence}, ${kindLabels[item.kind]}] — ${item.reason}`);
+        if (item.kind === "mcp-runtime")
+            lines.push("    Explicit setup only; preview credentials and permissions before enabling it.");
+    }
     return lines.join("\n");
 }

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/target-occupancy.js

@@ -0,0 +1,50 @@
+import { lstat, readdir } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Inspect a prospective skill target without following symlinks or executing
+ * any content. Missing paths and recursively empty directories are safe to
+ * replace; every uncertain state fails closed.
+ */
+export async function inspectTargetOccupancy(path, maximumEntries = 10_000) {
+    let root;
+    try {
+        root = await lstat(path);
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT")
+            return { occupied: false };
+        return { occupied: true, reason: "unreadable" };
+    }
+    if (root.isSymbolicLink())
+        return { occupied: true, reason: "symlink" };
+    if (!root.isDirectory())
+        return { occupied: true, reason: "unsupported" };
+    const queue = [path];
+    let inspected = 0;
+    while (queue.length) {
+        const directory = queue.pop();
+        let entries;
+        try {
+            entries = await readdir(directory, { withFileTypes: true });
+        }
+        catch {
+            return { occupied: true, reason: "unreadable" };
+        }
+        for (const entry of entries) {
+            inspected += 1;
+            if (inspected > maximumEntries)
+                return { occupied: true, reason: "inspection-limit" };
+            if (entry.isDirectory() && !entry.isSymbolicLink())
+                queue.push(join(directory, entry.name));
+            else
+                return {
+                    occupied: true,
+                    reason: entry.isSymbolicLink() ? "symlink" : "content",
+                };
+        }
+    }
+    return { occupied: false };
+}

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