loadout-ai 0.7.0 → 0.9.0

package/docs/specs/BOUNDED_AGENT_DISCUSSIONS.md

@@ -0,0 +1,169 @@
+# Spec: Bounded agent discussions
+
+## Objective
+
+Add an opt-in design room in which Claude Code and Codex can discuss one
+technical question, challenge each other's proposals, and record a final
+decision. The user chooses the topic, participants, round count, and provider
+turn budget. Success means the exchange is genuinely bidirectional, bounded,
+auditable, resumable from the coordination log, and unable to edit files merely
+because a discussion was started.
+
+The initial release targets two participants. One is the proposer and one is
+the reviewer. A round gives each participant one turn; after the configured
+rounds, the proposer receives one synthesis turn and Loadout records the final
+decision and considered alternative.
+
+## Assumptions approved by the user
+
+1. `loadout coord discuss start` is explicitly opt-in and may spend paid
+   provider turns.
+2. A discussion shares only responses produced for the public design room. It
+   does not expose hidden reasoning, unrelated chat history, or provider state.
+3. Discussion prompts forbid code edits and command execution. Implementation
+   begins only after the discussion completes and the user acts on the result.
+4. Exactly Claude Code and Codex are supported in the first release, using
+   either fresh sessions (`--agents`) or explicit existing sessions
+   (`--sessions`).
+5. A discussion has 1-8 rounds and a hard turn budget. The expected budget is
+   `rounds * 2 + 1`; invalid or insufficient budgets fail before any paid turn.
+6. Provider output is untrusted, redacted at the existing persistence boundary,
+   length-bounded, and stored only as explicit discussion events.
+
+## Tech stack
+
+- TypeScript 5.7, ESM, Node.js 20+
+- Commander 12 for the public CLI
+- Zod 4 for boundary validation
+- Vitest 4 for unit, integration, and CLI tests
+- Existing Claude Code CLI and official Codex SDK adapters
+- Existing project-local `.handoff/coordination.jsonl` protocol
+
+## Commands
+
+```bash
+# Build and static checks
+npm run build
+npm run typecheck
+npm run lint
+npm run format:check
+
+# Focused tests
+npx vitest run tests/coordination-discussion.test.ts
+npx vitest run tests/coordination-session-commands.test.ts
+
+# Full release gate
+npm run verify:full
+
+# Start fresh provider sessions
+loadout coord discuss start "REST or GraphQL for checkout?" \
+  --agents claude-code,codex --rounds 4 --max-turns 9
+
+# Reuse existing provider sessions
+loadout coord discuss start "REST or GraphQL for checkout?" \
+  --sessions claude-code:<session-id> codex:<thread-id> \
+  --rounds 4 --max-turns 9
+
+# Inspect a discussion without spending provider turns
+loadout coord discuss show <thread-id>
+loadout coord discuss list
+```
+
+## Project structure
+
+- `src/core/coordination/discussion.ts`: pure discussion state, prompts,
+  orchestration, result formatting, and bounded public transcript.
+- `src/core/coordination/events.ts`: additive discussion payload schema.
+- `src/commands/coordination-discussions.ts`: CLI registration and provider
+  session composition.
+- `src/commands/coordinate.ts`: registers the discussion command group.
+- `tests/coordination-discussion.test.ts`: protocol and orchestrator behavior.
+- `tests/coordination-session-commands.test.ts`: public argument parsing.
+- `docs/decisions/003-bounded-agent-discussions.md`: architecture rationale.
+- `docs/LIVE_COLLABORATION.md`, `docs/USER_TEST_GUIDE.md`, `README.md`: user
+  workflow and safety language.
+
+## Public contract and code style
+
+Discussion events extend the existing protocol without changing old events:
+
+```ts
+type DiscussionPayload = {
+  threadId: string;
+  kind: "started" | "proposal" | "critique" | "revision" | "summary" | "closed";
+  round: number;
+  role: "system" | "proposer" | "reviewer";
+  content: string;
+  participants?: [string, string];
+  replyTo?: string;
+  alternatives?: string[];
+  unresolved?: string[];
+  outcome?: "decided" | "failed";
+};
+```
+
+Names use current camelCase TypeScript conventions. Inputs and outputs are
+separate interfaces. Boundary schemas are strict and descriptive. Existing
+event error semantics and redaction are reused.
+
+## Testing strategy
+
+- Unit-test schemas, state reconstruction, prompt safety text, reply chains,
+  round limits, turn-budget validation, provider failure, and kill-switch
+  behavior with real coordination storage and fake participants.
+- Integration-test a complete alternating discussion and assert the persisted
+  event order and final decision.
+- CLI-test parsing for `--agents`, `--sessions`, rounds, and mutually exclusive
+  modes without invoking a paid provider.
+- Extend replay/adapter formatting tests so discussion events are legible.
+- Run all coordination suites, then `npm run verify:full`.
+- Manually run one real Claude Code/Codex discussion before publishing 0.9.0.
+
+## Boundaries
+
+### Always
+
+- Validate all CLI and persisted discussion input.
+- Check the kill switch before every provider turn and persisted event.
+- Emit a stable thread ID and reply ID for every public statement.
+- Keep turns sequential so each agent sees the previous public response.
+- Redact and bound shared responses through the canonical event store.
+- Print the exact paid-turn count before starting fresh or resumed sessions.
+
+### Ask first
+
+- Adding a third provider or more than two participants.
+- Allowing discussion prompts to edit files or execute commands.
+- Adding remote/networked coordination or a hosted message broker.
+- Persisting private provider transcripts or hidden reasoning.
+
+### Never
+
+- Start paid turns when validation or budget checks fail.
+- Route a discussion output as an instruction outside its thread.
+- Run an unbounded loop or retry provider turns silently.
+- Continue after the kill switch, missing response, or provider rejection.
+- Claim consensus when the synthesis records unresolved disagreement.
+
+## Success criteria
+
+- `coord discuss start` alternates Claude Code and Codex for exactly the
+  requested number of rounds and runs at most the declared turn budget.
+- Every response is a validated `discussion` event with `threadId`, `kind`,
+  `round`, `role`, and an explicit reply chain.
+- A successful discussion ends in `summary`, `decision`, and `closed` events;
+  a failed discussion ends in a bounded error/closed state without extra turns.
+- `list` and `show` reconstruct bounded discussion state from the JSONL log.
+- Both fresh sessions and explicit existing sessions are supported, but cannot
+  be selected together.
+- The kill switch halts the exchange before the next provider turn.
+- Each provider turn defaults to a 120-second timeout and accepts a validated
+  10-600 second override.
+- Existing coordination consumers continue to parse and operate unchanged.
+- Focused tests, all coordination tests, build, lint, formatting, package smoke,
+  and the complete release gate pass.
+
+## Open questions
+
+- None for the two-agent MVP. Multi-agent voting, remote machines, and automatic
+  implementation are intentionally deferred.

package/docs/superpowers/plans/2026-09-03-coordination-hardening.md

@@ -0,0 +1,231 @@
+# Coordination Hardening 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 Loadout coordination safe under concurrent processes, secure on localhost, correctly packaged over MCP, truthful about provider capabilities, and releasable behind an explicit beta contract.
+
+**Architecture:** Keep the human-readable JSONL audit log, but serialize every state-changing operation through one project-local lock and one canonical validated/redacted write path. Treat the HTTP daemon and stdio MCP server as authenticated/validated adapters over that core. Provider adapters may submit a new turn to a resumable session; they must never claim to inject into an active turn unless the host exposes that capability.
+
+**Tech Stack:** Node.js 20+, TypeScript, Zod, Vitest, `@modelcontextprotocol/sdk` v1, `@openai/codex-sdk`.
+
+## Global Constraints
+
+- Preserve existing `loadout handoff` behavior and `.handoff/messages.jsonl` compatibility.
+- Persist coordination events before notifying watchers or SSE subscribers.
+- Every persisted event has a unique, strictly increasing sequence number across concurrent processes.
+- Bind HTTP only to loopback and require a project-scoped bearer token for every API/SSE request.
+- Never persist raw secrets through any CLI, HTTP, or MCP write path.
+- Keep destructive actions, publishing, deployment, and permission expansion under user control.
+- Mark provider-driven live turns beta until both installed-host integration tests pass.
+
+---
+
+### Task 1: Restore the quality gate
+
+**Files:**
+
+- Modify: `src/core/coordination/adapters/codex.ts`
+- Modify: `src/core/coordination/daemon.ts`
+- Modify: `src/core/coordination/retention.ts`
+- Modify: `tests/coordination-concurrency.test.ts`
+- Modify: `tests/coordination-crash-recovery.test.ts`
+- Modify: `tests/coordination-interrupt-policy.test.ts`
+
+**Interfaces:**
+
+- Produces: a zero-error `npm run lint` baseline without weakening ESLint rules.
+
+- [ ] Remove imports that have no runtime or type use.
+- [ ] Rename or omit unused parameters rather than disabling lint rules.
+- [ ] Run `npm run lint`; expect exit 0.
+- [ ] Run `npm run typecheck`; expect exit 0.
+- [ ] Commit as `chore: restore coordination quality gate`.
+
+### Task 2: Serialize the coordination log and enforce invariants
+
+**Files:**
+
+- Create: `src/core/coordination/lock.ts`
+- Modify: `src/core/coordination/coordinator.ts`
+- Modify: `src/core/coordination/events.ts`
+- Modify: `src/commands/coordinate.ts`
+- Modify: `tests/coordination-concurrency.test.ts`
+- Create: `tests/fixtures/coordination-writer.mjs`
+
+**Interfaces:**
+
+- Produces: `withCoordinationLock<T>(projectRoot, operation): Promise<T>`.
+- Produces: `claimOwnership(projectRoot, input): Promise<CoordinationEvent>`.
+- Produces: atomic `publishContract` revision allocation and validated `ack` watermarks.
+
+- [ ] Add a failing multi-process test that starts independent Node writers and asserts 100 unique sequence numbers equal `0..99`.
+- [ ] Add failing tests for overlapping ownership (`src/api` vs `src/api/user.ts`), future acknowledgements, concurrent contract revisions, stale-lock recovery, and permission errors from an existing unreadable log.
+- [ ] Run `npx vitest run tests/coordination-concurrency.test.ts`; confirm failures describe duplicate sequences and missing validation.
+- [ ] Implement an exclusive lock file using `open(path, "wx", 0o600)`, bounded jittered retries, owner metadata, stale-owner recovery, and `finally` cleanup.
+- [ ] Move append, sequence allocation, contract revision allocation, ownership check/claim, and acknowledgement validation inside the lock.
+- [ ] Normalize project-relative paths and detect equal, parent, and child overlap.
+- [ ] Catch only `ENOENT` as an empty coordination log; propagate other I/O errors.
+- [ ] Cap IDs/agent names at 128 characters, descriptions at 8 KiB, context at 64 KiB, path counts at 256, and paths at 1 KiB.
+- [ ] Run the focused test until green, then run all coordination tests.
+- [ ] Commit as `fix: make coordination state atomic across processes`.
+
+### Task 3: Make redaction canonical
+
+**Files:**
+
+- Modify: `src/core/coordination/redaction.ts`
+- Modify: `src/core/coordination/coordinator.ts`
+- Modify: `src/core/coordination/daemon.ts`
+- Modify: `tests/coordination-redaction.test.ts`
+- Modify: `tests/coordination.test.ts`
+
+**Interfaces:**
+
+- Produces: `sanitizeEmitOptions(options): EmitOptions` used by the sole append path.
+
+- [ ] Add failing tests that emit secrets through direct core calls, CLI-equivalent calls, nested payloads, and daemon calls.
+- [ ] Confirm direct writes currently persist the sample secret.
+- [ ] Apply redaction inside the canonical locked writer before schema validation and persistence.
+- [ ] Remove adapter-specific duplicate redaction.
+- [ ] Verify all paths persist `[REDACTED]` and preserve non-sensitive fields.
+- [ ] Commit as `fix: redact every coordination write path`.
+
+### Task 4: Secure the localhost daemon and stabilize its API
+
+**Files:**
+
+- Create: `src/core/coordination/auth.ts`
+- Create: `src/core/coordination/http-api.ts`
+- Modify: `src/core/coordination/daemon.ts`
+- Modify: `src/commands/coordinate.ts`
+- Modify: `tests/coordination-daemon.test.ts`
+- Create: `tests/coordination-daemon-security.test.ts`
+
+**Interfaces:**
+
+- Produces: `ensureDaemonToken(projectRoot): Promise<string>` with a mode-0600 token file.
+- Produces: one structured error shape `{ error: { code, message } }`.
+- Consumes: atomic coordinator operations from Task 2.
+
+- [ ] Add failing tests for missing/wrong bearer token, malicious `Origin`, forged `Host`, unauthenticated SSE, oversized bodies, malformed JSON, and project-root leakage.
+- [ ] Confirm authenticated loopback requests remain possible.
+- [ ] Generate a 32-byte random token, store it under `.handoff` with mode `0600`, and compare tokens using `timingSafeEqual`.
+- [ ] Require `Authorization: Bearer <token>` for API requests; allow a query token only for the initial dashboard document and immediately move it to session storage/history-free state.
+- [ ] Replace wildcard CORS with same-origin behavior and reject non-loopback Host headers.
+- [ ] Return 400 for malformed JSON, 401 for missing authentication, 403 for origin/host rejection, 409 for ownership/revision conflict, and 413 for oversized bodies.
+- [ ] Stop returning absolute project paths from browser-visible status payloads.
+- [ ] Split the 700-line daemon into HTTP policy/route and lifecycle modules.
+- [ ] Run daemon security, daemon behavior, and full coordination tests.
+- [ ] Commit as `fix: authenticate and isolate the coordination daemon`.
+
+### Task 5: Ship a real MCP server
+
+**Files:**
+
+- Modify: `package.json`
+- Modify: `package-lock.json`
+- Modify: `tsconfig.json`
+- Modify: `src/core/coordination/mcp-server.ts`
+- Create: `tests/coordination-mcp.test.ts`
+- Modify: `scripts/package-smoke.mjs`
+
+**Interfaces:**
+
+- Produces: packaged `dist/src/core/coordination/mcp-server.js`.
+- Produces: stdio tools backed only by validated coordinator operations.
+
+- [ ] Add `@modelcontextprotocol/sdk` v1 as a runtime dependency and remove the TypeScript exclusion.
+- [ ] Add a failing package test asserting that `mcp-server.js` exists in the tarball.
+- [ ] Add an MCP client smoke test that initializes the server, lists tools, emits an event, and reads a snapshot in a temporary project.
+- [ ] Update handlers to use the SDK v1 API and convert validation/conflict failures into MCP tool errors.
+- [ ] Verify stdout contains only protocol messages and diagnostics go to stderr.
+- [ ] Run MCP tests and `npm pack --dry-run --json`.
+- [ ] Commit as `fix: compile and package the coordination MCP server`.
+
+### Task 6: Replace fictional provider commands with supported adapters
+
+**Files:**
+
+- Modify: `package.json`
+- Modify: `package-lock.json`
+- Modify: `src/core/coordination/adapters/types.ts`
+- Modify: `src/core/coordination/adapters/codex.ts`
+- Modify: `src/core/coordination/adapters/claude-code.ts`
+- Modify: `src/core/coordination/session-manager.ts`
+- Create: `tests/coordination-adapter-codex.test.ts`
+- Create: `tests/coordination-adapter-claude.test.ts`
+- Create: `tests/coordination-session-manager.test.ts`
+
+**Interfaces:**
+
+- Produces: capability `canSubmitTurn`, distinct from unsupported mid-turn injection.
+- Produces: Codex `start`, `resume`, and `submitTurn` through `@openai/codex-sdk`.
+- Produces: Claude `start`, `resume`, and `submitTurn` through documented positional CLI prompts.
+
+- [ ] Write adapter contract tests around injected process/SDK drivers so exact command arguments and session IDs are observable.
+- [ ] Assert Codex never uses `--quiet` and Claude never uses `--message` or `sessions list`.
+- [ ] Add `@openai/codex-sdk` as a runtime dependency and implement start/resume/turn using `startThread()`, `resumeThread(id)`, and `run()`.
+- [ ] Implement Claude print-mode turns as `claude -p --output-format json [--resume id] <prompt>` and parse `session_id` from validated output.
+- [ ] Track sessions Loadout itself creates instead of claiming to enumerate every host session.
+- [ ] Queue relevant events until an adapter is idle; do not interrupt active work unless a future host capability explicitly supports steering.
+- [ ] Run adapter and session-manager tests with fake drivers, followed by opt-in smoke checks against the locally installed CLIs.
+- [ ] Commit as `fix: use supported Codex and Claude session APIs`.
+
+### Task 7: Reconcile retention, recovery, and observability
+
+**Files:**
+
+- Modify: `src/core/coordination/retention.ts`
+- Modify: `src/core/coordination/crash-recovery.ts`
+- Modify: `src/core/coordination/replay.ts`
+- Modify: `src/core/coordination/watcher.ts`
+- Modify: `tests/coordination-retention.test.ts`
+- Modify: `tests/coordination-crash-recovery.test.ts`
+- Modify: `tests/coordination-replay.test.ts`
+
+**Interfaces:**
+
+- Consumes: the same lock from Task 2 for compaction and recovery.
+- Produces: explicit health data without filesystem secrets.
+
+- [ ] Add failing tests for append-during-compaction, truncated final lines, duplicate legacy sequences, reconnect after compaction, and backup restoration.
+- [ ] Make compaction and recovery use the same exclusive lock as append.
+- [ ] Preserve corrupt-line evidence rather than silently discarding it.
+- [ ] Bound replay and snapshot queries by event count and serialized byte size.
+- [ ] Add counters for connected clients, high watermark, corrupt records, rejected writes, and last compaction time.
+- [ ] Run focused recovery/retention/replay tests.
+- [ ] Commit as `fix: harden coordination recovery and retention`.
+
+### Task 8: Make the product contract truthful and test the release artifact
+
+**Files:**
+
+- Create: `docs/decisions/001-coordination-jsonl-locking.md`
+- Create: `docs/decisions/002-local-daemon-authentication.md`
+- Modify: `README.md`
+- Modify: `MASTERPLAN.md`
+- Modify: `docs/LIVE_COLLABORATION.md`
+- Modify: `docs/USER_TEST_GUIDE.md`
+- Modify: `CHANGELOG.md`
+- Modify: `scripts/readme-product-flow.mjs`
+- Modify: `scripts/cli-product-flow.mjs`
+
+**Interfaces:**
+
+- Produces: one user-facing distinction between durable handoff, live coordination, and provider-driven beta turns.
+
+- [ ] Document the locking and authentication decisions, rejected alternatives, limitations, and recovery behavior.
+- [ ] Remove contradictory phase/status claims and document exact supported commands.
+- [ ] Add a two-agent walkthrough: backend contract publish, frontend acknowledgement, revision diff, ownership conflict, reconnect, and kill switch.
+- [ ] Add CLI/product-flow coverage for the walkthrough without invoking paid model turns.
+- [ ] Run `npm run verify:full` from the clean branch.
+- [ ] Run `npm pack --dry-run --json`, install the tarball in a temporary directory, and execute `loadout --version`, `loadout coordinate --help`, daemon authentication, and MCP initialization.
+- [ ] Run opt-in real-host smoke tests with installed Codex and Claude CLIs; do not make destructive project changes.
+- [ ] Review `git diff` for secrets and unrelated changes.
+- [ ] Commit as `docs: define the live coordination beta contract`.
+
+## Self-review
+
+- Spec coverage: concurrency, authentication, MCP packaging, real provider APIs, validation, redaction, ownership overlap, acknowledgements, retention, recovery, documentation, clean-room packaging, and launch gates are each assigned to a task.
+- Placeholder scan: no deferred implementation placeholders are used; provider mid-turn interruption is explicitly excluded until supported by a host API.
+- Type consistency: all external adapters converge on `canSubmitTurn` and canonical coordinator operations; HTTP and MCP do not own state logic.

package/docs/superpowers/plans/2026-09-03-release-readiness.md

@@ -0,0 +1,232 @@
+# Loadout Release Readiness 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:** Resolve every actionable weakness from the 2026-09-03 audit and leave a locally testable, release-ready Loadout tree without publishing it.
+
+**Architecture:** Centralize bounded JSON HTTP handling, validate handoff data at its boundary, and derive CLI metadata from the Commander tree instead of parallel lists. Keep landing-page material concise while moving detailed reference content into focused documents. Reduce the two largest implementation files by extracting cohesive command and discovery responsibilities without changing their public behavior.
+
+**Tech Stack:** TypeScript, Node.js 20+, Commander, Zod, Vitest, GitHub Actions, npm.
+
+## Global Constraints
+
+- Do not push, publish, tag, or create a GitHub Release; the user will test first.
+- Preserve current user changes, including the pre-existing deletion of `loadout-ai-0.8.0.tgz`.
+- Add no runtime dependency; use Node web streams and the existing Zod dependency.
+- Every behavior change follows red-green TDD.
+- Preserve Node 20, macOS, Linux, and Windows compatibility.
+- Keep mutating CLI behavior preview-first and reversible.
+
+---
+
+### Task 1: Bound JSON network responses
+
+**Files:**
+
+- Create: `src/core/runtime/bounded-json.ts`
+- Create: `tests/bounded-json.test.ts`
+- Modify: `src/core/catalog/registry.ts`
+- Modify: `src/core/agents/model-config.ts`
+- Modify: `src/core/discovery/community.ts`
+- Modify: `src/core/discovery/github-discovery.ts`
+- Modify: `src/core/discovery/private-discovery.ts`
+- Modify: `src/core/runtime/github.ts`
+- Test: the existing tests for each consumer above
+
+**Interfaces:**
+
+- Produces: `boundedJson(fetcher, input, init, limits): Promise<{ response: Response; value: unknown }>` with required timeout and byte limits.
+- Consumes: standard `fetch`, `AbortSignal.timeout`, and `ReadableStreamDefaultReader`.
+
+- [ ] Add tests proving declared oversize, streamed oversize, malformed JSON, timeout signal composition, and exact-limit success.
+- [ ] Run `npx vitest run tests/bounded-json.test.ts tests/security-regressions.test.ts` and confirm the new cases fail for the missing helper/old full-buffer behavior.
+- [ ] Implement incremental stream reads that cancel above the cap and parse only after the bounded byte array is complete.
+- [ ] Route every listed JSON request through the helper with endpoint-appropriate caps and 30-second defaults.
+- [ ] Run all affected unit tests and confirm they pass.
+
+### Task 2: Validate every handoff log entry
+
+**Files:**
+
+- Modify: `src/core/delegation/handoff.ts`
+- Modify: `tests/handoff.test.ts`
+
+**Interfaces:**
+
+- Produces: a strict internal Zod schema matching `HandoffMessage`, including the terminal type enum and ISO timestamp.
+- Consumes: existing `readMessagesDetailed` corrupt-line reporting.
+
+- [ ] Add tests for missing timestamp/from/to/description, unsupported type, malformed resolves, and valid legacy terminal context.
+- [ ] Run `npx vitest run tests/handoff.test.ts` and confirm malformed-but-valid JSON reaches the old unsafe path.
+- [ ] Parse with the complete schema and report schema failures as corrupt lines without hiding valid neighbors.
+- [ ] Run the handoff suite and a CLI inbox formatting test.
+
+### Task 3: Generate complete shell command metadata
+
+**Files:**
+
+- Modify: `src/core/reporting/completion.ts`
+- Modify: `src/cli.ts`
+- Modify: `tests/completion.test.ts`
+- Modify: `scripts/check-documented-commands.mjs`
+- Create: `tests/documented-commands-script.test.ts`
+
+**Interfaces:**
+
+- Produces: recursive `CommandTree` nodes and shell completion output for every registered parent/child pair.
+- Produces: a machine-readable CLI command-path mode consumed by the documentation gate.
+
+- [ ] Add tests requiring `skills list/install/remove` in all four shells and rejecting invalid documented parent-child combinations.
+- [ ] Run the focused tests and capture the expected failures.
+- [ ] Render nested cases from the command tree rather than hard-coded parent names.
+- [ ] Change the documentation gate to compare full command paths extracted from executable snippets against registered paths.
+- [ ] Reset completion registry state per test and run focused tests green.
+
+### Task 4: Make release verification match the release promise
+
+**Files:**
+
+- Modify: `package.json`
+- Modify: `.github/workflows/release.yml`
+- Modify: `tests/package-release.test.ts`
+- Modify: `CHANGELOG.md`
+
+**Interfaces:**
+
+- Produces: `verify:full` that runs `verify` plus `test:coverage`.
+- Consumes: release workflow tag/version and npm provenance checks.
+
+- [ ] Add tests requiring the release job to call `verify:full` and requiring that script to include coverage.
+- [ ] Run `npx vitest run tests/package-release.test.ts` and confirm failure against the old release command.
+- [ ] Update scripts/workflow, and document the post-0.8 removal of model routing under Unreleased with a 0.9 migration note.
+- [ ] Run release contract tests green.
+
+### Task 5: Replace stale planning and package metadata
+
+**Files:**
+
+- Modify: `MASTERPLAN.md`
+- Modify: `package.json`
+- Modify: `tests/package-release.test.ts`
+
+**Interfaces:**
+
+- Produces: one current roadmap that contains no fixed vulnerabilities, removed paths, or routing feature claims.
+- Produces: npm metadata aligned with GitHub positioning and search terms.
+
+- [ ] Add metadata assertions for the canonical description and keywords.
+- [ ] Run the package contract test red.
+- [ ] Rewrite `MASTERPLAN.md` around remaining post-audit work and align npm description/keywords.
+- [ ] Run metadata and README claim tests green.
+
+### Task 6: Complete open-source contribution scaffolding
+
+**Files:**
+
+- Create: `CONTRIBUTING.md`
+- Create: `CODE_OF_CONDUCT.md`
+- Create: `.github/ISSUE_TEMPLATE/bug_report.yml`
+- Create: `.github/ISSUE_TEMPLATE/feature_request.yml`
+- Create: `.github/pull_request_template.md`
+- Create or modify: `tests/community-health.test.ts`
+- Modify: `README.md`
+
+**Interfaces:**
+
+- Produces: a contributor path with exact setup, verification, security, and PR expectations.
+
+- [ ] Add file/content contract tests and run them red.
+- [ ] Add concise community files and link contribution guidance from the README.
+- [ ] Run community and README tests green.
+
+### Task 7: Make the README convert quickly
+
+**Files:**
+
+- Modify: `README.md`
+- Create: `docs/REFERENCE.md`
+- Modify: `tests/readme-product-flow.test.ts`
+- Modify: `scripts/readme-product-flow.mjs`
+
+**Interfaces:**
+
+- Produces: a proof-first README under 400 lines with hero, first win, demo, install, handoff, trust, concise reference links, and contributor CTA.
+- Produces: detailed material moved without loss to `docs/REFERENCE.md`.
+
+- [ ] Change README structure assertions to require the demo before deep explanation and enforce the line budget.
+- [ ] Run focused README tests red.
+- [ ] Move detailed profiles, discovery, MCP, runtime tools, and long command tables into the reference document.
+- [ ] Keep all material claims and generated marker blocks valid, then run README/evidence tests green.
+
+### Task 8: Prepare a social preview asset
+
+**Files:**
+
+- Create: `docs/assets/loadout-social-preview.png`
+- Modify: `tests/readme-product-flow.test.ts`
+
+**Interfaces:**
+
+- Produces: solid-background 1280x640 PNG under 1 MB for manual upload in GitHub Settings.
+
+- [ ] Add dimension, format, and size assertions and run them red while the asset is absent.
+- [ ] Generate a concise social card using the established visual language and handoff differentiator.
+- [ ] Optimize without reducing readability and run asset tests green.
+
+### Task 9: Split oversized modules along existing responsibilities
+
+**Files:**
+
+- Modify: `src/commands/catalog.ts`
+- Create: `src/commands/catalog-skills.ts`
+- Create: `src/commands/catalog-discovery.ts`
+- Modify: `src/core/discovery/candidate-intelligence.ts`
+- Create: `src/core/discovery/candidate-signals.ts`
+- Create: `src/core/discovery/candidate-report.ts`
+- Test: existing catalog, discovery, candidate, CLI help, and completion suites
+
+**Interfaces:**
+
+- Produces: command registration functions imported by `catalog.ts` with no CLI contract change.
+- Produces: pure candidate signal/report helpers imported by candidate intelligence.
+
+- [ ] Record current CLI/help and candidate JSON fixtures through existing behavior tests.
+- [ ] Extract command groups without changing option names, output, or action wiring.
+- [ ] Extract pure candidate scoring/reporting groups and keep exported compatibility.
+- [ ] Require each former 1,000-line hotspot to fall below 850 lines.
+- [ ] Run all catalog/discovery/CLI suites green and scan for orphaned exports.
+
+### Task 10: Final review and local release rehearsal
+
+**Files:**
+
+- Review: every changed file
+- Modify only defects found by review
+
+**Interfaces:**
+
+- Consumes: all previous task outputs.
+- Produces: a local release candidate for the user to test.
+
+- [ ] Run Prettier, lint, typecheck, dependency audit, documentation/evidence gates, all unit tests, E2E flows, package smoke, performance benchmark, and coverage.
+- [ ] Run `npm pack --dry-run --json` and install the resulting local package in a disposable directory.
+- [ ] Review correctness, readability, architecture, security, and performance; fix every required finding with red-green coverage.
+- [ ] Run `loadout handoff codex`, verify no pending tasks, and report exact remaining manual steps without publishing.
+
+## Risks and Mitigations
+
+| Risk                                                    | Impact | Mitigation                                                                                   |
+| ------------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------- |
+| Shared working tree edits collide                       | High   | Assign agents disjoint file sets and integrate only after reviewing diffs.                   |
+| README claim markers break during shortening            | High   | Move content around marker blocks intact and run both claim gates after each edit.           |
+| Generic fetch helper changes mock behavior              | Medium | Preserve injectable fetchers and test standard Response streams plus mocked consumers.       |
+| Command extraction changes Commander registration order | Medium | Snapshot public help/command paths before extraction and assert exact equivalence.           |
+| Social preview is not automatically active              | Low    | Deliver the validated file and clearly leave GitHub Settings upload as the only manual step. |
+
+## Self-Review
+
+- Every audit weakness maps to Tasks 1–9.
+- No task publishes or mutates remote repository state.
+- Each behavior change includes an explicit failing-test step and focused verification.
+- Shared interfaces are named before parallel implementation.
+- No placeholders or deferred implementation steps remain.