loadout-ai 0.4.0 → 0.4.1

package/docs/superpowers/plans/2026-07-20-project-activation-safety.md

@@ -0,0 +1,469 @@
+# Project Activation Safety Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make project activation respect every agent's real active-skill capacity, tolerate recursively empty rollback residue, and recommend a compact project-relevant set.
+
+**Architecture:** Extract the existing bounded target-occupancy rule into one shared filesystem module used by setup and activation. Build per-agent budgets from the read-only installed-skill inventory, then score and slice reviewed library candidates per agent. Extend deterministic local project signals and recommendation metadata without introducing network or model calls.
+
+**Tech Stack:** TypeScript 5.7, Node.js 20+, Commander 12, Vitest 4, existing Loadout transaction/state/inventory modules.
+
+## Global Constraints
+
+- No model or external API call is required for recommendation or activation.
+- No project source, filename, dependency, or outcome data leaves the machine.
+- Never execute package code while scanning, recommending, or activating.
+- Missing and recursively empty targets are unoccupied; files, symlinks, special entries, unreadable directories, and scans beyond 10,000 entries are occupied.
+- `--limit` is a per-agent ceiling over managed plus unmanaged skills containing `SKILL.md`.
+- Preview remains read-only; apply revalidates inside one rollback-safe transaction.
+- Existing CLI flags remain valid; the project-plan JSON schema may add per-agent budgets in 0.4.1.
+
+---
+
+### Task 1: Share the bounded target-occupancy rule
+
+**Files:**
+
+- Create: `src/core/target-occupancy.ts`
+- Create: `tests/target-occupancy.test.ts`
+- Modify: `src/core/install.ts`
+- Modify: `src/core/active-set.ts`
+- Modify: `tests/active-set.test.ts`
+
+**Interfaces:**
+
+- Produces: `inspectTargetOccupancy(path: string, maximumEntries?: number): Promise<TargetOccupancy>`.
+- Consumed by: setup collision checks and activation preview/apply checks.
+
+- [x] **Step 1: Write failing occupancy tests**
+
+```ts
+import { mkdir, mkdtemp, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { expect, it } from "vitest";
+import { inspectTargetOccupancy } from "../src/core/target-occupancy.js";
+
+it("treats missing and recursively empty targets as unoccupied", async () => {
+  const root = await mkdtemp(join(tmpdir(), "loadout-target-"));
+  const empty = join(root, "skill");
+  await mkdir(join(empty, "nested"), { recursive: true });
+  await expect(
+    inspectTargetOccupancy(join(root, "missing")),
+  ).resolves.toMatchObject({ occupied: false });
+  await expect(inspectTargetOccupancy(empty)).resolves.toMatchObject({
+    occupied: false,
+  });
+});
+
+it("treats content, symlinks, and the inspection bound as occupied", async () => {
+  const root = await mkdtemp(join(tmpdir(), "loadout-target-"));
+  const content = join(root, "content");
+  const linked = join(root, "linked");
+  await mkdir(content);
+  await writeFile(join(content, "SKILL.md"), "content");
+  await symlink(content, linked);
+  await expect(inspectTargetOccupancy(content)).resolves.toMatchObject({
+    occupied: true,
+    reason: "content",
+  });
+  await expect(inspectTargetOccupancy(linked)).resolves.toMatchObject({
+    occupied: true,
+    reason: "symlink",
+  });
+  await expect(inspectTargetOccupancy(join(root), 1)).resolves.toMatchObject({
+    occupied: true,
+    reason: "inspection-limit",
+  });
+});
+```
+
+- [x] **Step 2: Run the occupancy tests and verify RED**
+
+Run: `npx vitest run tests/target-occupancy.test.ts`  
+Expected: FAIL because `src/core/target-occupancy.ts` does not exist.
+
+- [x] **Step 3: Implement the shared predicate**
+
+```ts
+import { lstat, readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+export interface TargetOccupancy {
+  occupied: boolean;
+  reason?:
+    "content" | "symlink" | "unsupported" | "unreadable" | "inspection-limit";
+}
+
+export async function inspectTargetOccupancy(
+  path: string,
+  maximumEntries = 10_000,
+): Promise<TargetOccupancy> {
+  let root;
+  try {
+    root = await lstat(path);
+  } catch (error) {
+    if (
+      error &&
+      typeof error === "object" &&
+      "code" in error &&
+      (error as { code?: string }).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 };
+}
+```
+
+- [x] **Step 4: Replace duplicate setup logic and activation `pathExists` checks**
+
+In `src/core/install.ts`, import `inspectTargetOccupancy` and replace the recursive block in `assertActiveTargetsUnoccupied` with:
+
+```ts
+for (const target of targets) {
+  if ((await inspectTargetOccupancy(target)).occupied) occupied.push(target);
+}
+```
+
+In `src/core/active-set.ts`, use the same predicate when enabling and include the reason in the blocker. Re-run the check immediately before the transaction copies any target; remove only targets proven recursively empty.
+
+- [x] **Step 5: Add the activation regression**
+
+Extend `tests/active-set.test.ts` so a disabled library entry with `empty/nested` under its active target previews without blockers and applies, while a target containing `notes.txt` remains blocked and unchanged.
+
+- [x] **Step 6: Verify GREEN and commit**
+
+Run: `npx vitest run tests/target-occupancy.test.ts tests/install.test.ts tests/active-set.test.ts`  
+Expected: all tests pass.
+
+```bash
+git add src/core/target-occupancy.ts src/core/install.ts src/core/active-set.ts tests/target-occupancy.test.ts tests/active-set.test.ts
+git commit -m "fix: share safe target occupancy checks"
+```
+
+### Task 2: Enforce per-agent total active capacity
+
+**Files:**
+
+- Modify: `src/core/active-policy.ts`
+- Modify: `src/core/active-set.ts`
+- Modify: `tests/active-policy.test.ts`
+
+**Interfaces:**
+
+- Consumes: `detectAgents()`, `scanInstalledSkills()`, and reviewed activation records.
+- Produces: `AgentActiveSetPlan` records with total, managed, unmanaged, capacity, and selected candidates.
+
+- [x] **Step 1: Write failing mixed-agent capacity tests**
+
+Add a fixture with 12 unmanaged `SKILL.md` directories under Claude's skill root, zero under Codex, and 40 reviewed disabled candidates per agent. Assert:
+
+```ts
+const plan = await planProjectActivation(project, {
+  agents: ["claude-code", "codex"],
+  limit: 30,
+});
+expect(
+  plan.agentPlans.find((item) => item.agent === "claude-code"),
+).toMatchObject({
+  activeBefore: 12,
+  unmanagedBefore: 12,
+  capacity: 18,
+});
+expect(
+  plan.agentPlans.find((item) => item.agent === "claude-code")!.selected,
+).toHaveLength(18);
+expect(plan.agentPlans.find((item) => item.agent === "codex")).toMatchObject({
+  activeBefore: 0,
+  capacity: 30,
+});
+expect(
+  plan.agentPlans.find((item) => item.agent === "codex")!.selected,
+).toHaveLength(30);
+```
+
+Add a second test where Claude already has 30 unmanaged skills and Codex has none. Claude must receive zero additions and Codex must still receive candidates.
+
+- [x] **Step 2: Run the capacity tests and verify RED**
+
+Run: `npx vitest run tests/active-policy.test.ts`  
+Expected: FAIL because the plan has one managed-only global budget and no `agentPlans`.
+
+- [x] **Step 3: Add per-agent plan types and inventory-backed budgets**
+
+```ts
+export interface AgentActiveSetPlan {
+  agent: AgentId;
+  activeBefore: number;
+  managedBefore: number;
+  unmanagedBefore: number;
+  capacity: number;
+  selected: ActiveSetCandidate[];
+}
+
+export interface ProjectActiveSetPlan {
+  project: ProjectSignals;
+  limit: number;
+  agents?: AgentId[];
+  agentPlans: AgentActiveSetPlan[];
+  activation?: ActivationPlan;
+  warnings: string[];
+}
+```
+
+Resolve requested agents through `detectAgents`, call `scanInstalledSkills`, and create one budget from each inventory summary. Score only that agent's reviewed disabled records, diversify them, and slice to that agent's capacity.
+
+- [x] **Step 4: Merge exact per-agent activation plans**
+
+Call `planActivationChange("enable", selectors, { agents: [agent] })` once per non-empty agent selection and combine `changes`, `skipped`, `warnings`, `blocked`, and unique package IDs into one transaction plan. `applyProjectActivation` continues to call `applyActivationChange` exactly once.
+
+Before copying, re-scan inventory and abort if any agent's current total would make the planned additions exceed `limit`.
+
+- [x] **Step 5: Format truthful per-agent budgets**
+
+Replace the global budget line with:
+
+```text
+Claude Code: 12 active (0 managed, 12 unmanaged); 18/30 slots available
+Codex: 0 active (0 managed, 0 unmanaged); 30/30 slots available
+```
+
+Group additions beneath their target agent and do not duplicate one global list that implies identical capacities.
+
+- [x] **Step 6: Verify GREEN and commit**
+
+Run: `npx vitest run tests/active-policy.test.ts tests/active-set.test.ts tests/skill-inventory.test.ts`  
+Expected: all tests pass, including 18 Claude additions and 30 Codex additions.
+
+```bash
+git add src/core/active-policy.ts src/core/active-set.ts tests/active-policy.test.ts
+git commit -m "fix: enforce per-agent active skill limits"
+```
+
+### Task 3: Detect bounded Node CLI and package signals
+
+**Files:**
+
+- Modify: `src/shared/types.ts`
+- Modify: `src/core/recommend.ts`
+- Modify: `tests/recommend.test.ts`
+
+**Interfaces:**
+
+- Extends `ProjectSignals` with `roles: string[]` and `tools: string[]`.
+- Consumed by package recommendations and skill ranking.
+
+- [x] **Step 1: Write failing signal tests**
+
+Create a package fixture containing `bin`, `publishConfig`, `commander`, `zod`, `vitest`, `@playwright/test`, `prepack`, and an `mcp` keyword, plus `SECURITY.md`. Assert:
+
+```ts
+expect(signals.roles).toEqual(
+  expect.arrayContaining([
+    "node-cli",
+    "npm-package",
+    "release",
+    "mcp",
+    "security",
+  ]),
+);
+expect(signals.tools).toEqual(
+  expect.arrayContaining(["commander", "zod", "vitest", "playwright"]),
+);
+```
+
+- [x] **Step 2: Run the recommendation tests and verify RED**
+
+Run: `npx vitest run tests/recommend.test.ts`  
+Expected: FAIL because `roles` and `tools` are absent.
+
+- [x] **Step 3: Extend project signals and parse only known metadata**
+
+```ts
+export interface ProjectSignals {
+  root: string;
+  languages: string[];
+  frameworks: string[];
+  roles: string[];
+  tools: string[];
+  files: string[];
+}
+```
+
+In `scanProject`, derive roles and tools only from root entry names, known manifest fields, dependencies/devDependencies, scripts, publish metadata, and keywords. Do not recursively read arbitrary source content.
+
+- [x] **Step 4: Format readable detected roles**
+
+Add display labels so human output says `TypeScript, Node CLI, npm package, Vitest, Playwright, MCP tooling` while JSON retains stable lowercase identifiers.
+
+- [x] **Step 5: Verify GREEN and commit**
+
+Run: `npx vitest run tests/recommend.test.ts tests/outcomes.test.ts`  
+Expected: all tests pass.
+
+```bash
+git add src/shared/types.ts src/core/recommend.ts tests/recommend.test.ts
+git commit -m "feat: detect local cli and package signals"
+```
+
+### Task 4: Diversify project skill selection
+
+**Files:**
+
+- Modify: `src/core/active-policy.ts`
+- Modify: `tests/active-policy.test.ts`
+
+**Interfaces:**
+
+- Consumes: extended `ProjectSignals`.
+- Produces: evidence-threshold candidates grouped by capability family.
+
+- [x] **Step 1: Write failing relevance tests**
+
+Add reviewed candidates named `javascript-typescript-jest`, `vitest-testing`, five Playwright variants, `cli-design`, `npm-package`, and `mcp-security`. For a Vitest Node CLI fixture, assert Jest is absent, CLI/npm/MCP candidates are present, and no more than three browser-testing candidates are selected.
+
+- [x] **Step 2: Run the active-policy tests and verify RED**
+
+Run: `npx vitest run tests/active-policy.test.ts`  
+Expected: FAIL because current ranking selects Jest and redundant Playwright variants.
+
+- [x] **Step 3: Add exact signal rules and mismatch rejection**
+
+Add role/tool rules for Node CLI, npm package, Vitest, Commander, Zod, MCP, release, and security. Reject a candidate matching `jest` when `vitest` is present and `jest` is absent.
+
+- [x] **Step 4: Add deterministic family caps**
+
+Implement `candidateFamily(unitId)` and deterministic caps: browser testing 3; documentation 2; code review 2; architecture 2; planning 3; security 3; language/tooling 5; uncategorized 3. Explicit full-selector pins bypass family caps but still consume capacity. Stop after eligible candidates are exhausted; never fill unused slots with candidates below the existing evidence threshold.
+
+- [x] **Step 5: Verify GREEN and commit**
+
+Run: `npx vitest run tests/active-policy.test.ts`  
+Expected: all relevance, diversity, pin, outcome, and per-agent capacity tests pass.
+
+```bash
+git add src/core/active-policy.ts tests/active-policy.test.ts
+git commit -m "feat: diversify project skill selection"
+```
+
+### Task 5: Label recommendation component types
+
+**Files:**
+
+- Modify: `src/shared/types.ts`
+- Modify: `src/core/recommend.ts`
+- Modify: `tests/recommend.test.ts`
+
+**Interfaces:**
+
+- Extends `PackageRecommendation` with `kind: "skill-library" | "mcp-runtime" | "unavailable"`.
+- Uses catalog `components` to classify suggestions.
+
+- [x] **Step 1: Write failing type-label tests**
+
+Assert Superpowers formats as `skill library`, while Playwright MCP and GitHub MCP format as `MCP/runtime setup` and include a separate preview/setup hint rather than activation wording.
+
+- [x] **Step 2: Run the recommendation tests and verify RED**
+
+Run: `npx vitest run tests/recommend.test.ts`  
+Expected: FAIL because recommendations have no `kind`.
+
+- [x] **Step 3: Classify catalog-backed recommendations**
+
+```ts
+function recommendationKind(
+  pkg: CatalogPackage,
+): PackageRecommendation["kind"] {
+  if (pkg.components?.includes("skill")) return "skill-library";
+  if (pkg.components?.some((item) => item === "mcp" || item === "plugin"))
+    return "mcp-runtime";
+  return "unavailable";
+}
+```
+
+Attach the kind when adding each catalog recommendation and preserve it through local-outcome personalization.
+
+- [x] **Step 4: Format kinds and next actions**
+
+Human output must label every line and end MCP/runtime suggestions with the read-only recipe or explicit setup command supported by the package. It must not claim those integrations are automatically activatable skills.
+
+- [x] **Step 5: Verify GREEN and commit**
+
+Run: `npx vitest run tests/recommend.test.ts tests/outcomes.test.ts`  
+Expected: all tests pass.
+
+```bash
+git add src/shared/types.ts src/core/recommend.ts tests/recommend.test.ts
+git commit -m "feat: label recommendation component types"
+```
+
+### Task 6: Verify the product path and prepare the release candidate
+
+**Files:**
+
+- Modify: `CHANGELOG.md`
+- Modify: `master_plan.md`
+- Modify: `docs/USER_TEST_GUIDE.md`
+- Modify: `scripts/cli-product-flow.mjs`
+
+**Interfaces:**
+
+- Consumes: all corrected preview/apply behavior.
+- Produces: repeatable release and founder acceptance evidence.
+
+- [x] **Step 1: Extend the CLI product-flow regression**
+
+Add a journey that creates one agent with unmanaged skills and one empty agent, restores recursively empty snapshot residue, installs a disabled library, previews project activation, applies it, and rolls back the explicit activation snapshot. Assert unmanaged bytes are unchanged at every point.
+
+- [x] **Step 2: Run the focused product flow after the unit-level RED/GREEN cycles**
+
+Run: `npm run test:e2e:cli`  
+Expected: PASS for per-agent capacity, empty-target activation, atomic apply, and explicit rollback.
+
+- [x] **Step 3: Update user-facing documentation**
+
+Document that `--limit` includes unmanaged skills, Maximum remains disabled by default, recommendations distinguish skills from MCP/runtime setup, and project activation may choose different set sizes per agent.
+
+- [x] **Step 4: Run the full local release gate**
+
+Run: `npm run verify`  
+Expected: formatting, lint, typecheck, evidence checks, unit tests, CLI/readme/package flows, and performance checks all pass.
+
+- [x] **Step 5: Build and inspect the packed npm artifact without publishing**
+
+Run: `npm pack --dry-run`  
+Expected: the package contains the corrected compiled CLI and no untracked secret or local-state files.
+
+- [x] **Step 6: Record completion and commit**
+
+Mark only the implemented portions of `P18-27` complete, record exact test counts and remaining founder/npm steps, and keep real-profile activation blocked until the corrected package is published.
+
+```bash
+git add CHANGELOG.md MASTER_PLAN.md docs/USER_TEST_GUIDE.md scripts/cli-product-flow.mjs
+git commit -m "test: cover safe project activation journey"
+```

package/docs/superpowers/specs/2026-07-20-project-activation-safety-design.md

@@ -0,0 +1,228 @@
+# Project Activation Safety and Relevance Design
+
+**Status:** Approved direction; awaiting written-spec review  
+**Date:** 2026-07-20  
+**Release target:** Loadout 0.4.1
+
+## Problem
+
+The founder acceptance run of `loadout activate --project . --agents
+codex,claude-code --limit 30` exposed three connected defects:
+
+1. The preview reported `0/30 active` even though Claude Code already had 12
+   unmanaged skills. The planner counted only active Loadout records, so applying the
+   proposal could exceed the disclosed per-agent limit.
+2. An earlier rollback correctly restored recursively empty skill directories. The
+   activation planner treated the existence of those empty directories as occupied
+   content and blocked safe activation for both agents.
+3. Project detection recognized only JavaScript/TypeScript and Playwright. It missed
+   strong local evidence that this repository is a Node CLI, an npm package, a Vitest
+   project, an MCP-related tool, and a release/supply-chain project. Ranking then used
+   the entire 30-slot budget as a quota and proposed redundant or mismatched skills,
+   including several overlapping Playwright workflows and a Jest skill for a Vitest
+   repository.
+
+No activation was applied. The Maximum library remains disabled, and the founder's
+12 unmanaged Claude skills remain unchanged.
+
+## Goals
+
+- Make `--limit` a truthful ceiling over all active skills visible to each selected
+  agent, whether managed by Loadout or not.
+- Plan and explain capacity separately for every selected agent.
+- Treat recursively empty rollback residue as unoccupied while continuing to refuse
+  every non-empty, symlinked, unreadable, or unsupported target.
+- Improve local project recognition enough to distinguish this Node CLI/npm/Vitest
+  repository from a generic Playwright web application.
+- Select a compact, diverse working set instead of filling every available slot with
+  weak or redundant matches.
+- Preserve a preview-first, transactional, rollback-safe mutation path.
+
+## Non-goals
+
+- No model or external API call is required for recommendation or activation.
+- No project source, filename, dependency, or outcome data leaves the machine.
+- This work does not claim that a deterministic recommendation proves global package
+  quality.
+- This work does not install deferred MCP servers or collect credentials.
+- Dashboard removal remains a separate 0.4.1 task.
+
+## Design
+
+### 1. One shared definition of an occupied skill target
+
+Loadout will use one filesystem predicate for both initial installation and later
+library activation:
+
+- A missing path is unoccupied.
+- A real directory containing no entries at any depth is unoccupied.
+- A regular file, symlink, special entry, unreadable directory, or directory with any
+  non-directory descendant is occupied.
+- Recursive inspection is bounded to 10,000 entries. Reaching the bound is treated as
+  occupied, never as empty.
+
+Activation will re-check this predicate inside the transaction immediately before
+copying. This closes the preview/apply race without deleting or adopting user content.
+Empty target directories may be removed immediately before the copy because they
+contain no bytes to preserve; rollback still restores the pre-transaction topology.
+
+### 2. Per-agent total active capacity
+
+For each requested agent, the planner will scan the agent's real skill root and count
+every directory containing a valid `SKILL.md`. This inventory already distinguishes
+managed and unmanaged skills and will be the capacity source of truth.
+
+For agent `a`:
+
+```text
+available(a) = max(0, limit - inventory(a).total)
+```
+
+Candidate ranking is deterministic and shared, but selection is sliced independently
+to each agent's available capacity. In the founder fixture, Claude Code has 12 active
+unmanaged skills and may receive at most 18 additions; Codex has zero active skills and
+may receive at most 30. An agent at its limit receives no changes and a clear warning;
+it does not prevent another requested agent from using its own available capacity.
+
+The plan must never count an empty directory as an active skill. Existing managed
+skills already in the desired state count toward capacity but are not proposed again.
+
+### 3. Project signals
+
+Project scanning remains deterministic, bounded, and local-only. It will read known
+root manifests/configuration and a bounded set of repository filenames. For Node
+projects it will derive explicit signals from `package.json`:
+
+- `bin` -> Node CLI
+- package name plus `publishConfig` or non-private package -> npm package/release
+- `vitest` -> Vitest
+- `jest` -> Jest
+- `@playwright/test` or Playwright config -> Playwright
+- `commander` -> command-line application
+- `zod` -> schema validation
+- scripts containing `prepack`, package-smoke, or release checks -> package/release
+
+Repository filenames add delivery, security, MCP, and documentation signals only when
+matching explicit reviewed patterns such as `.github/workflows`, `SECURITY.md`, MCP-
+named modules, and package/release scripts. The scanner does not recursively read
+arbitrary project source or send any data elsewhere.
+
+Human output will name the important detected roles, for example:
+
+```text
+Detected: TypeScript, Node CLI, npm package, Vitest, Playwright, MCP tooling
+```
+
+### 4. Relevant and diverse selection
+
+The existing source-priority tie-break remains, but a capacity ceiling is not a quota.
+Selection stops when no candidate reaches the evidence threshold.
+
+Ranking will:
+
+- reward exact tool and role matches such as Vitest, CLI design, npm packaging,
+  TypeScript, MCP security, release verification, and documentation;
+- reject framework mismatches such as Jest-only guidance when Vitest is detected and
+  Jest is not;
+- group close alternatives into capability families such as browser testing, code
+  review, documentation, planning, security, and architecture;
+- select the highest-evidence representative before taking another member of the same
+  family;
+- cap weak generic foundation choices so they cannot crowd out project-specific
+  evidence;
+- continue to honor explicit `--pin` selectors, while disclosing when a pin consumes a
+  slot or conflicts with the limit.
+
+The same skill name from multiple repositories remains an alternative, not two active
+copies. Multiple distinct skills in one family are allowed only when each has separate
+strong project evidence.
+
+### 5. Recommendation type clarity
+
+Package-level `loadout recommend` output will label every suggestion as one of:
+
+- `skill library` — eligible for disabled-library activation;
+- `MCP/runtime setup` — requires a separate explicit preview and may require a
+  non-model credential;
+- `unavailable` — not prepared locally, with the reason.
+
+Playwright MCP and GitHub MCP must not look like ordinary automatically activatable
+skills. The command will show the next preview command for explicit integrations and
+will continue to state that recommendations are rule-selected, not proof of quality.
+
+### 6. Preview and apply output
+
+The default human preview will begin with one compact block per agent:
+
+```text
+Claude Code: 12 active (0 managed, 12 unmanaged), 18/30 slots available
+Codex: 0 active, 30/30 slots available
+```
+
+It will then show additions grouped by agent and capability, followed by blockers. A
+recursively empty target is not printed as a blocker. A real conflict prints the exact
+target and a non-destructive next action. JSON output retains full scores, reasons,
+alternatives, per-agent budgets, targets, and blocker details.
+
+`--yes` is rejected when any proposed target is blocked. A successful apply creates
+one transaction snapshot covering every selected agent and prints the exact rollback
+command.
+
+## Data flow
+
+1. Scan project metadata into local project signals.
+2. Scan each requested agent's active skill inventory.
+3. Read reviewed disabled-library records and local-only outcomes.
+4. Score and diversify eligible candidates.
+5. Slice the ordered candidates independently to each agent's available capacity.
+6. Build exact activation changes and inspect targets with the shared occupancy rule.
+7. Print the preview; stop unless `--yes` is present.
+8. Inside the transaction, re-read state, re-check capacity and target occupancy, copy
+   reviewed library bytes, fingerprint the result, persist activation state, and emit
+   the rollback snapshot.
+
+## Failure handling
+
+- If inventory scanning fails for an agent, activation for that agent is blocked; its
+  capacity is never guessed.
+- If the project manifest is malformed, show the exact manifest error and continue
+  only with signals that remain trustworthy.
+- If state or filesystem contents change between preview and apply, abort the entire
+  multi-agent transaction without partial activation.
+- If fewer candidates meet the evidence threshold than available slots, activate only
+  those candidates and explain that unused capacity is intentional.
+
+## Tests and acceptance criteria
+
+Automated tests must prove:
+
+1. A recursively empty target does not block preview or apply.
+2. A target containing a file, symlink, unreadable entry, or more than the inspection
+   bound remains blocked and unchanged.
+3. Empty-directory handling is identical in initial setup and project activation.
+4. Twelve unmanaged Claude skills plus an 18-skill proposal never exceeds a limit of 30.
+5. The same plan may select 18 additions for Claude and 30 for an empty Codex profile.
+6. An agent already at capacity receives no additions while another agent can proceed.
+7. Apply re-checks inventory and occupancy and aborts atomically when either changes.
+8. The Loadout repository fixture detects Node CLI, npm package, Vitest, Playwright,
+   Commander, Zod, release, security, and MCP signals.
+9. A Vitest-only fixture never recommends a Jest-only skill.
+10. Redundant Playwright/browser candidates do not consume most of the active set.
+11. Recommendation output distinguishes skill libraries from explicit MCP/runtime
+    setup.
+12. Human output shows per-agent managed/unmanaged counts and unused capacity; JSON
+    exposes the same facts structurally.
+13. Existing Stable, Power, Maximum, rollback, and non-overwrite tests remain green.
+
+Founder acceptance resumes only after the published release candidate previews a
+non-blocked plan, reports Claude's existing 12 skills, respects both per-agent limits,
+applies transactionally, and restores its explicit snapshot without changing unmanaged
+content.
+
+## Compatibility
+
+Existing `loadout activate` and `loadout optimize` flags remain valid. The meaning of
+`--limit` is corrected from an implicit managed-only count to the documented total
+active skill ceiling. JSON consumers must migrate from one global `activeBefore` and
+`capacity` pair to per-agent budget records; the 0.4.1 changelog will call out this
+schema correction.