loadout-ai 0.3.1 → 0.4.1

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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loadout-ai",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "private": false,
   "license": "MIT",
   "description": "Universal upgrade manager for AI coding agents",
@@ -16,7 +16,6 @@
     "README.md",
     "CHANGELOG.md",
     "MASTER_PLAN.md",
-    "SIMPLE_PLAN.md",
     "SECURITY.md",
     "LICENSE"
   ],
@@ -55,13 +54,18 @@
     "test:e2e:dashboard": "playwright test",
     "pretest:e2e:cli": "npm run build",
     "test:e2e:cli": "node scripts/cli-product-flow.mjs",
+    "test:e2e:readme": "node scripts/readme-product-flow.mjs",
     "test:package": "node scripts/package-smoke.mjs",
     "pretest:performance": "npm run build",
     "test:performance": "node scripts/scan-benchmark.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "check:evidence": "node scripts/check-catalog-attribution.mjs && node scripts/check-discovery-artifacts.mjs && node --import tsx scripts/check-release-claims.ts",
+    "readme:update": "node scripts/update-readme-facts.mjs",
+    "readme:check": "node scripts/update-readme-facts.mjs --check",
+    "check:readme-claims": "npm run build && node scripts/check-readme-claims.mjs",
+    "check:live": "node scripts/check-live-evidence.mjs",
+    "check:evidence": "node scripts/check-catalog-attribution.mjs && node scripts/check-discovery-artifacts.mjs && npm run check:readme-claims && node --import tsx scripts/check-release-claims.ts",
     "feed:build": "node --import tsx scripts/build-intelligence-feed.ts",
-    "verify": "npm run format:check && npm run lint && npm run typecheck && npm run check:evidence && npm test -- --run && npm run test:e2e:cli && npm run test:package && npm run test:performance",
+    "verify": "npm run format:check && npm run lint && npm run typecheck && npm run check:evidence && npm test -- --run && npm run test:e2e:cli && npm run test:e2e:readme && npm run test:package && npm run test:performance",
     "verify:full": "npm run verify && npm run test:e2e:dashboard"
   },
   "dependencies": {

package/SIMPLE_PLAN.md

@@ -1,44 +0,0 @@
-# Loadout plan — simple version
-
-Loadout's primary experience is CLI-first:
-
-```bash
-npx loadout-ai
-```
-
-It detects installed agents, scans the actual skills already present, and recommends a
-small Stable foundation. Maximum Library and Custom are explicit alternatives. It
-previews reviewed pinned sources, exact overlaps, capacity, and safety findings before
-one rollback-safe transaction. The dashboard is optional diagnostics.
-
-Loadout also provides the package-manager operations:
-
-- Find, install, update, remove, create, share, and synchronize AI-agent add-ons.
-- Work with skills, commands, rules, agents, plugins, and MCP tools.
-- Support Codex, Claude Code, Cursor, and more from one setup file.
-
-Loadout's four major advantages are:
-
-1. **Safety:** scan first, explain every change, block dangerous behavior, and never
-   touch unrelated files.
-2. **Recovery:** back up before changes and provide one-command undo.
-3. **Guidance:** check setup health and recommend tested add-on collections for the
-   user's project.
-4. **Optimization:** keep a broad reviewed library but expose only the best supported,
-   non-overlapping active set for the current agent and project.
-
-The original build order was:
-
-1. Finish the reliable package-manager foundation.
-2. Match OpenPackage's package types, sources, synchronization, and publishing.
-3. Add health checks, security scanning, safe updates, recommendations, and profiles.
-4. Keep the dashboard optional and prove every supported platform with tests.
-
-That foundation is now integrated on `main`. [MASTER_PLAN.md](./MASTER_PLAN.md) is the
-only canonical checklist; contributor branches and notes are historical inputs, not
-separate sources of project status. Phase 12 now tracks provenance for unmanaged
-skills, evidence-backed comparison, library-versus-active-set state, safe adoption and
-enable/disable, project activation, guided optimization, category evaluations, daily
-review queues, provider/MCP workflows, CLI polish, npm publication, and public-beta
-testing. Catalog expansion, legal review, keychains, additional adapters, and submission
-work remain explicit rather than hidden behind earlier checked implementation proofs.

package/docs/plans/2026-07-18-release-0.3.md

@@ -1,42 +0,0 @@
-# Loadout 0.3 Product-Hardening Plan
-
-## Goal
-
-Ship a user-testable CLI release with one-command cleanup, honest whole-profile update
-checks, explicit no-key MCP discovery, and a verified local dashboard.
-
-## Public contracts
-
-1. `loadout uninstall` is a preview. `loadout uninstall --yes` removes scheduled
-   Loadout jobs, runtime tools, managed agent files, disabled library copies, cache,
-   snapshots, and state while preserving unmanaged or modified files. `--remove-cli`
-   additionally runs the global npm uninstall.
-2. `loadout update` checks every tracked package and compares the last installed
-   Stable/Power/Maximum profile with the current trusted catalog. It never mutates by
-   default.
-3. `loadout update --yes` reapplies trusted profile changes and applies all
-   statically-safe active package updates; blocked, disabled, or failed updates are
-   reported and skipped. `--package <id> --yes` remains the precise path.
-4. Stable, Power, and Maximum are re-evaluated against the trusted catalog whenever
-   `update` runs. Discovery can nominate new candidates daily, but candidates cannot
-   enter a profile until immutable source, license, compatibility, and safety review
-   are recorded.
-5. `loadout mcp-recipe --no-key` lists reviewed recipes requiring no separately
-   billed AI/model API key. It includes GitHub read-only while separately disclosing
-   the GitHub token. `--credential-free` is the stricter zero-credential filter.
-6. `loadout dashboard` remains loopback-only and is verified by the browser E2E test.
-
-## Implementation sequence
-
-- [x] Add failing tests for uninstall preview/application and CLI help.
-- [x] Implement uninstall orchestration with dependency injection and path guards.
-- [x] Add failing tests for persisted profile state and profile drift reporting.
-- [x] Record setup mode in snapshot-restorable install state and include it in update.
-- [x] Add failing tests for bulk safe update selection and clear skipped results.
-- [x] Implement `update --yes`, retaining `--apply` as a compatible alias.
-- [x] Add and test Chrome DevTools as a pinned no-key MCP recipe.
-- [x] Add `mcp-recipe --no-key` and beginner-readable recipe output.
-- [x] Update README, test guide, master plan, changelog, completion, and version.
-- [ ] Run unit, lint, type, evidence, package, CLI E2E, performance, dashboard E2E,
-      and npm dry-run gates.
-- [ ] Review, commit, merge to main, push, tag, and publish to npm.

package/docs/superpowers/plans/2026-07-18-cli-ux-polish.md

@@ -1,86 +0,0 @@
-# CLI UX Polish Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use `executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make Loadout's everyday CLI path understandable for a first-time user while preserving its existing safe, advanced capabilities.
-
-**Architecture:** Keep the CLI as the primary interface. Add one concise, read-only `guide` command and a focused help footer; retain advanced commands but remove them from the first-screen help. Fix JSON output and package-scoped update previews as explicit public CLI contracts. Document a safe test journey and keep the dashboard as an optional local companion.
-
-**Tech Stack:** Node.js 20+, TypeScript, Commander, Vitest, framework-free local dashboard.
-
-## Global Constraints
-
-- Never mutate a user's agent configuration from a default or preview command.
-- Existing command names remain valid even if hidden from first-screen help.
-- Machine-readable commands must emit valid JSON when `--json` is accepted.
-- Do not require an API key or GitHub account for the core test journey.
-- Every behavior change gets a test before its production code.
-
----
-
-### Task 1: Define the beginner CLI contract
-
-**Files:**
-
-- Modify: `tests/cli-help.test.ts`
-- Modify: `src/cli.ts`
-
-**Interfaces:**
-
-- Produces: `loadout guide`, a read-only command that explains setup, discovery, project recommendations, recovery, dashboard, and help.
-
-- [x] **Step 1: Write failing CLI contract tests** for `loadout guide`, a focused top-level help footer, and retained access to an advanced command.
-- [x] **Step 2: Run** `npm test -- tests/cli-help.test.ts` **and confirm the new assertions fail.**
-- [x] **Step 3: Implement** `guide`, hide maintainer-only commands from first-screen help, and add a short help footer that points to the guide.
-- [x] **Step 4: Run** `npm test -- tests/cli-help.test.ts` **and confirm it passes.**
-- [ ] **Step 5: Commit** the focused CLI discoverability change.
-
-### Task 2: Repair machine-readable and scoped preview contracts
-
-**Files:**
-
-- Modify: `tests/cli-help.test.ts`
-- Modify: `tests/update.test.ts`
-- Modify: `src/cli.ts`
-- Modify: `src/core/update.ts`
-
-**Interfaces:**
-
-- `loadout catalog --json` returns a JSON array.
-- `loadout update --package <id>` plans only that managed package and rejects an unknown installed package clearly.
-
-- [x] **Step 1: Write failing tests** for catalog JSON and package-scoped update planning.
-- [x] **Step 2: Run the focused test files** and confirm the assertions fail for the existing implementation.
-- [x] **Step 3: Implement the smallest compatible fixes.**
-- [x] **Step 4: Run the focused tests** and confirm they pass.
-- [ ] **Step 5: Commit** the contract fixes separately.
-
-### Task 3: Record user testing and current product scope
-
-**Files:**
-
-- Create: `docs/USER_TEST_GUIDE.md`
-- Modify: `MASTER_PLAN.md`
-
-**Interfaces:**
-
-- The guide gives a real-profile-safe order of commands, says which commands change state, and gives rollback instructions.
-- `MASTER_PLAN.md` begins with the one authoritative unfinished-work section and moves stale immediate tasks out of the active path.
-
-- [x] **Step 1: Add a concise user testing guide** for daily use, discovery, optional dashboard, safe mutation, rollback, and advanced validation.
-- [x] **Step 2: Add the current remaining work section** and mark historic, non-essential ideas as deferred rather than pretending they are active product requirements.
-- [x] **Step 3: Run markdown and CLI smoke checks** to make sure command names match the real surface.
-- [ ] **Step 4: Commit** documentation separately.
-
-### Task 4: Validate the actual user journey
-
-**Files:**
-
-- Test: `tests/cli-help.test.ts`
-- Test: `tests/update.test.ts`
-- Test: `tests/dashboard.test.ts`
-
-- [x] **Step 1: Build and run** the CLI guide, catalog JSON, health, library, project recommendation preview, and dashboard endpoint checks without changing agent files.
-- [ ] **Step 2: Run** `npm run verify:full` **and inspect every failure if any.**
-- [ ] **Step 3: Review the diff for accidental profile/cache/secrets changes.**
-- [ ] **Step 4: Commit, then present the exact install/test/recovery commands to the user.**