loadout-ai 0.2.3 → 0.4.0

package/docs/superpowers/plans/2026-07-19-relatable-readme-hero.md

@@ -0,0 +1,283 @@
+# Relatable README and Hero 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:** Give Viraj's Loadout repository a relatable, evidence-bounded story and original GitHub-ready hero while correcting canonical repository metadata and preserving all existing truth gates.
+
+**Architecture:** Keep the README human-authored around the existing six machine-owned fact blocks. Add one dependency-free SVG hero under `docs/assets/`, strengthen only the README and metadata contracts that intentionally change, and leave the required CI workflow untouched because its failed job was blocked before execution by GitHub account billing.
+
+**Tech Stack:** Markdown, SVG/XML, TypeScript, Vitest, Node.js 20+, Prettier, Playwright, GitHub Actions.
+
+## Global Constraints
+
+- Base every change on `VirajMishra1/loadout` `main` at `194676910327176272ebe42982d13c6e8246f0aa`.
+- Canonical repository identity is `VirajMishra1/loadout`; preserve dated historical fork evidence where it is explicitly historical.
+- Keep exactly one ordered marker pair for `catalog-coverage`, `evidence-stages`, `daily-discovery`, `current-limits`, `support-summary`, and `verification-summary`.
+- Preserve the unpublished `0.3.2` warning, preview/apply recomputation boundary, catalog evidence limits, native-host boundary, security statements, installation requirements, and existing executable product-flow proof.
+- Do not claim the GitHub billing/spending-limit failure is reproducible locally; its job executed zero steps.
+- Do not modify `.github/workflows/ci.yml`, delete/skip/weaken tests, add dependencies, copy Ponytail artwork, or add decorative badges.
+- Deliver an unmerged ready pull request against Viraj's `main`.
+
+---
+
+### Task 1: Correct canonical repository identity
+
+**Files:**
+
+- Modify: `package.json`
+- Modify: `README.md`
+- Modify: `docs/evidence/live-checks.schema.json`
+- Modify: `tests/live-evidence.test.ts`
+- Modify: `tests/readme-product-flow.test.ts`
+
+**Interfaces:**
+
+- Consumes: canonical repository identity `VirajMishra1/loadout`.
+- Produces: package metadata, README visitor links, schema identity, and regression expectations that agree on the canonical upstream.
+
+- [ ] **Step 1: Add failing canonical-identity assertions**
+
+  In `tests/readme-product-flow.test.ts`, load `package.json` and `docs/evidence/live-checks.schema.json` alongside the README and assert:
+
+  ```ts
+  expect(readme).toContain(
+    "https://github.com/VirajMishra1/loadout/actions/workflows/ci.yml",
+  );
+  expect(readme).toContain(
+    "git clone https://github.com/VirajMishra1/loadout.git",
+  );
+  expect(readme).toContain("https://github.com/VirajMishra1/loadout/issues");
+  expect(readme).not.toContain("https://github.com/reddynitish/loadout");
+  expect(packageJson.repository.url).toBe(
+    "git+https://github.com/VirajMishra1/loadout.git",
+  );
+  expect(packageJson.homepage).toBe(
+    "https://github.com/VirajMishra1/loadout#readme",
+  );
+  expect(packageJson.bugs.url).toBe(
+    "https://github.com/VirajMishra1/loadout/issues",
+  );
+  expect(schema.$id).toBe(
+    "https://github.com/VirajMishra1/loadout/docs/evidence/live-checks.schema.json",
+  );
+  ```
+
+  Update the intentional `packageJson` fixture in `tests/live-evidence.test.ts` to Viraj only after observing the new repository-contract test fail; the fixture change follows production metadata and does not change live-check behavior.
+
+- [ ] **Step 2: Run the focused test and confirm RED**
+
+  Run:
+
+  ```bash
+  npm test -- --run tests/readme-product-flow.test.ts
+  ```
+
+  Expected: failure showing at least the current fork CI/clone/issue or package metadata URL.
+
+- [ ] **Step 3: Apply the smallest canonical URL changes**
+
+  Replace only current canonical fork destinations in the listed files. Do not change the historical fork observations or dated fork CI evidence in `docs/REPOSITORY_STABILIZATION.md`.
+
+- [ ] **Step 4: Verify focused behavior and formatting**
+
+  Run:
+
+  ```bash
+  npm test -- --run tests/readme-product-flow.test.ts tests/live-evidence.test.ts
+  npm run readme:check
+  npx prettier --check README.md package.json docs/evidence/live-checks.schema.json tests/live-evidence.test.ts tests/readme-product-flow.test.ts
+  git diff --check
+  ```
+
+  Expected: both focused files pass; generated README blocks remain current; formatting and diff checks pass.
+
+- [ ] **Step 5: Commit**
+
+  ```bash
+  git add README.md package.json docs/evidence/live-checks.schema.json tests/live-evidence.test.ts tests/readme-product-flow.test.ts
+  git commit -m "fix: restore Viraj repository identity"
+  ```
+
+### Task 2: Create and render the original hero
+
+**Files:**
+
+- Create: `docs/assets/loadout-hero.svg`
+
+**Interfaces:**
+
+- Produces: accessible, dependency-free, theme-aware hero consumed by the README in Task 3.
+
+- [ ] **Step 1: Draw the approved composition**
+
+  Create a wide SVG with a developer choosing one extension tile between an unmanaged cluster and five organized loadout slots. Use original basic geometry and path-drawn symbols; include:
+
+  ```xml
+  role="img"
+  aria-labelledby="loadout-hero-title loadout-hero-description"
+  <title id="loadout-hero-title">Choose an intentional agent loadout</title>
+  <desc id="loadout-hero-description">A developer moves an extension from scattered configuration tiles into organized managed equipment slots.</desc>
+  ```
+
+  Use `currentColor`, an internal dark-scheme color override, a wide `viewBox`, and no external content, fonts, scripts, raster images, gradients, or animation.
+
+- [ ] **Step 2: Validate source structure**
+
+  Run:
+
+  ```bash
+  xmllint --noout docs/assets/loadout-hero.svg
+  xmllint --xpath 'count(/*[local-name()="svg"]/*[local-name()="title"]) = 1 and count(/*[local-name()="svg"]/*[local-name()="desc"]) = 1' docs/assets/loadout-hero.svg
+  rg -n '<script|<image|<animate|<foreignObject|font-family|(?:href|src)="https?://' docs/assets/loadout-hero.svg
+  ```
+
+  Expected: XML and XPath checks succeed; the forbidden-content search has no matches.
+
+- [ ] **Step 3: Render four visual contexts**
+
+  Use the existing Playwright/Chromium dependency or an available SVG renderer to produce untracked PNG previews at approximately 720×225 and 360×113 on white and `#0d1117` backgrounds. Store previews under `/tmp/loadout-hero-preview/`, never in the repository.
+
+- [ ] **Step 4: Inspect and iterate**
+
+  Inspect all four images at original resolution. Confirm the unmanaged cluster, developer selection gesture, management boundary, five slots, and path-drawn symbols remain distinct; text/symbols are legible; no geometry clips; and contrast works in both themes. Iterate until every check passes.
+
+- [ ] **Step 5: Format and commit**
+
+  Run:
+
+  ```bash
+  npx prettier --parser html --check docs/assets/loadout-hero.svg
+  git diff --check
+  git add docs/assets/loadout-hero.svg
+  git commit -m "docs: add intentional loadout hero"
+  ```
+
+### Task 3: Add the relatable story and stronger hero contract
+
+**Files:**
+
+- Modify: `README.md`
+- Modify: `tests/readme-product-flow.test.ts`
+
+**Interfaces:**
+
+- Consumes: `docs/assets/loadout-hero.svg` from Task 2.
+- Produces: first-visitor README hierarchy with a genuine loadout metaphor and verified hero reference.
+
+- [ ] **Step 1: Add failing story/hero assertions**
+
+  Replace the old mark assertion with:
+
+  ```ts
+  expect(readme).toContain("./docs/assets/loadout-hero.svg");
+  expect(readme).toMatch(/skills, plugins, MCP servers, and agent settings/i);
+  expect(readme).toMatch(
+    /loadout is the deliberate set of tools chosen before a mission/i,
+  );
+  expect(readme).toMatch(
+    /what is installed, where it came from, or how to undo it/i,
+  );
+  expect(readme).not.toMatch(/founder|revolutionary|game-changing/i);
+  ```
+
+  Also require the README hero alt text to mention a developer and organized loadout slots.
+
+- [ ] **Step 2: Run the focused test and confirm RED**
+
+  Run:
+
+  ```bash
+  npm test -- --run tests/readme-product-flow.test.ts
+  ```
+
+  Expected: failure on the absent hero reference or metaphor paragraph.
+
+- [ ] **Step 3: Update only the intended README sections**
+
+  Replace the top image with `./docs/assets/loadout-hero.svg`, a width appropriate for the wide asset, and meaningful alt text. Add the approved concise paragraph under `## Why Loadout`, followed by the existing three bullets. Do not change the verified journey, transcript, warnings, generated blocks, trust boundaries, installation requirements, or unrelated hierarchy.
+
+- [ ] **Step 4: Refresh and verify README contracts**
+
+  Run:
+
+  ```bash
+  npm run readme:update
+  npm run readme:check
+  npm run check:evidence
+  npm test -- --run tests/readme-product-flow.test.ts tests/readme-facts-script.test.ts tests/readme-claims.test.ts
+  npx prettier --check README.md tests/readme-product-flow.test.ts
+  git diff --check
+  ```
+
+  Expected: generated blocks current, evidence gate reports zero contradictions, focused tests pass, and no unrelated README section moves.
+
+- [ ] **Step 5: Commit**
+
+  ```bash
+  git add README.md tests/readme-product-flow.test.ts
+  git commit -m "docs: explain the Loadout metaphor"
+  ```
+
+### Task 4: Verify failure boundary, render, links, and full repository
+
+**Files:**
+
+- Modify only files needed to resolve verified findings.
+
+**Interfaces:**
+
+- Produces: reviewed branch and unmerged upstream pull request.
+
+- [ ] **Step 1: Reconfirm the failed Actions evidence**
+
+  Use `gh` to confirm run `29708871932`, job `88250042904`, zero job steps, and the billing/spending-limit annotation. Record that no repository command ran and therefore the external failure cannot be reproduced locally.
+
+- [ ] **Step 2: Run every intended required-job command locally**
+
+  Run, separately and read each exit code:
+
+  ```bash
+  npm ci
+  npm run format:check
+  npm run lint
+  npm run typecheck
+  node scripts/check-catalog-attribution.mjs
+  node scripts/check-discovery-artifacts.mjs
+  npm test -- --run
+  npm run test:e2e:cli
+  npm run test:package
+  npm run test:performance
+  ```
+
+  Expected: every command exits zero. `npm test -- --run` is the exact test command the blocked workflow intended to execute.
+
+- [ ] **Step 3: Run repository verification entry points**
+
+  Run:
+
+  ```bash
+  npm run verify
+  npm run verify:full
+  ```
+
+  If the combined Playwright wrapper does not return a reliable completion code, run `npm run test:e2e:dashboard` separately and require its explicit success.
+
+- [ ] **Step 4: Validate links, XML, and final renders**
+
+  Check every README relative file target and heading fragment with a focused script, validate SVG XML/accessibility/forbidden content, re-render all four hero contexts, and inspect them. Confirm the README's canonical external links point to Viraj and all dated fork links outside canonical product metadata remain clearly historical.
+
+- [ ] **Step 5: Obtain independent final review**
+
+  Request independent factual/claim review, code/test review, and rendered first-visitor/accessibility review for the complete branch diff. Fix every Critical and Important finding test-first and re-review until clean.
+
+- [ ] **Step 6: Push and open an unmerged PR**
+
+  Push `codex/relatable-readme-hero` to `VirajMishra1/loadout` and open a ready PR against `main`. The PR body must report:
+
+  - billing/spending-limit root cause and zero executed steps;
+  - why no local reproduction of account billing is possible;
+  - exact local commands and test counts;
+  - hero render/accessibility evidence;
+  - files changed and preserved truth boundaries.
+
+  Do not merge the PR. Confirm its final state is `OPEN`, `isDraft: false`, and base branch `main`.

package/docs/superpowers/specs/2026-07-19-relatable-readme-hero-design.md

@@ -0,0 +1,80 @@
+# Relatable README and Hero Design
+
+## Objective
+
+Make Viraj's current Loadout README more memorable to a first-time visitor without weakening its evidence boundaries. Replace the small slot mark with a clearly stronger original hero, add a concise human explanation of the loadout metaphor, correct canonical repository links, and document the actual GitHub Actions failure without pretending it is a code defect.
+
+## Verified starting point
+
+- Source: `VirajMishra1/loadout` default branch `main` at merge commit `194676910327176272ebe42982d13c6e8246f0aa`.
+- The README already presents the verified `Choose -> Inspect -> Preview -> Apply -> Undo` flow and bounded warnings about unpublished `0.3.2`, preview/apply identity, catalog evidence, native-agent execution, security, and persistence.
+- The failed upstream Actions job `88250042904` in run `29708871932` executed zero steps. Its sole annotation says the job did not start because recent account payments failed or the spending limit must be increased.
+- Because no runner step started, there is no failing repository command to reproduce locally. Verification must instead run the workflow's intended commands locally and report that this validates the code but cannot reproduce GitHub account billing state.
+- Canonical README/package links still point to the temporary `reddynitish/loadout` fork and must point to `VirajMishra1/loadout`.
+
+## README story
+
+Keep `## Why Loadout` in its current location after the verified product journey. Add one short paragraph before the existing evidence-backed benefits:
+
+> Skills, plugins, MCP servers, and agent settings tend to accumulate one experiment at a time. Eventually it becomes hard to remember what is installed, where it came from, or how to undo it. In a game, a loadout is the deliberate set of tools chosen before a mission. Loadout brings that same discipline to AI coding agents: inspect the available equipment, choose intentionally, apply it through managed changes, and remove or roll it back later.
+
+The final copy may be tightened for rhythm but must preserve these facts and must not introduce a founder narrative, generic marketing superlatives, universal safety, native-host execution, or stronger rollback guarantees than the implementation proves. Retain the three existing bullets for managed inventory, preview-first operations, and recoverable managed changes.
+
+## Hero composition
+
+Create `docs/assets/loadout-hero.svg` as a wide, dependency-free, theme-aware SVG and replace the README's small `loadout-mark.svg` reference only after rendered comparison shows the hero is materially stronger.
+
+The composition reads left to right:
+
+1. **Unmanaged edge:** a restrained cluster of loose extension/config tiles, crossing paths, and small labels sits outside a dashed management boundary. It is visibly disorganized but not cartoonishly chaotic.
+2. **Developer choice:** a simple, original geometric developer figure at a compact workbench reaches toward one extension tile. The figure is symbolic rather than a detailed character, avoiding any resemblance to Ponytail's artwork or composition.
+3. **Managed loadout:** five aligned equipment slots sit inside a clear rail. Selected slots use recognizable code-native symbols such as `>_`, a plug, linked nodes, or braces; the remaining slot can be empty. A small directional cue connects the chosen tile to the rail.
+4. **Outcome:** the organized rail is visually calmer and more regular than the unmanaged edge. The image communicates selection and control, not an unsupported claim that every external tool is safe.
+
+Use a wide `viewBox` suitable for a GitHub README hero, approximately 960 by 300. Use SVG paths and basic shapes only, with no raster content, scripts, animation, gradients, external fonts, remote references, or copied assets. Every visible symbol should remain legible when the hero is rendered near 720 pixels wide and at a smaller mobile width.
+
+Use `currentColor` plus an internal `prefers-color-scheme` fallback so strokes and restrained fills have adequate contrast on GitHub light and dark themes. Include one meaningful `<title>` and `<desc>`, `role="img"`, and matching `aria-labelledby`. The README `<img>` needs concise alt text describing the developer moving extension tiles from a messy group into organized loadout slots.
+
+The existing `docs/assets/loadout-mark.svg` remains available as a compact mark unless repository cleanup later proves it unused and removal is explicitly covered by tests and links. The task does not need to delete it.
+
+## Canonical repository corrections
+
+Update current canonical product metadata and visitor destinations from `reddynitish/loadout` to `VirajMishra1/loadout`:
+
+- README CI workflow badge and image URL.
+- README clone command.
+- README issue-tracker link.
+- `package.json` repository, homepage, and bugs URLs.
+- `docs/evidence/live-checks.schema.json` `$id`.
+- Tests/fixtures that intentionally assert canonical package metadata.
+
+Do not rewrite historical evidence that accurately identifies the fork or dated fork CI runs. Historical links in `docs/REPOSITORY_STABILIZATION.md` remain historical evidence, not canonical product metadata.
+
+## Check failure handling
+
+No workflow bypass is allowed. Do not delete, skip, weaken, or condition the required verification job. The smallest correct repository action is to leave CI logic intact and accurately report the external billing/spending-limit root cause.
+
+Before PR creation:
+
+- Reconfirm the failed check annotation and absence of job steps.
+- Run each intended required job command locally, including the exact `npm test -- --run` invocation.
+- Run `npm run verify`.
+- Run `npm run verify:full` because Playwright dependencies are available locally.
+- Treat any local failure as a real defect and fix it test-first; do not call the external billing annotation a locally reproduced failure.
+
+## Regression and rendering coverage
+
+Update README-focused tests only for intended structure/content changes:
+
+- require the new hero reference and genuine metaphor language;
+- require canonical Viraj badge/clone/issue destinations;
+- reject canonical README/package links to the temporary fork;
+- preserve all six generated marker pairs, current hierarchy, executable offline product flow, warnings, and truth-boundary assertions.
+
+Update package metadata tests for Viraj's canonical repository. Do not add a test that pretends GitHub billing can be reproduced locally.
+
+Validate all README relative targets and heading fragments, SVG XML/accessibility structure, forbidden external SVG content, and light/dark renders at desktop and mobile sizes. Review the complete README as a first-time visitor for hierarchy, clarity, and unsupported implications.
+
+## Delivery
+
+Commit implementation on `codex/relatable-readme-hero`, push it to Viraj's repository, and open a ready pull request against `main`. Include the Actions billing root cause, local command evidence, rendered hero evidence, and truth boundaries in the PR body. Do not merge the pull request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loadout-ai",
-  "version": "0.2.3",
+  "version": "0.4.0",
   "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.