loadout-ai 0.8.0 → 0.9.1

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.

package/docs/superpowers/plans/2026-09-04-bounded-agent-discussions.md

@@ -0,0 +1,121 @@
+# Bounded Agent Discussions 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:** Let Claude Code and Codex conduct a safe, bounded, auditable design discussion and record a final decision.
+
+**Architecture:** Add one typed discussion event to the append-only coordination protocol and reconstruct thread state from those events. A provider-neutral orchestrator alternates two responders sequentially, while a thin Commander module starts or resumes concrete Claude/Codex sessions and enforces the paid-turn budget before any turn.
+
+**Tech Stack:** TypeScript, Commander, Zod, Vitest, existing provider adapters and JSONL coordination store.
+
+## Global constraints
+
+- Exactly two participants and 1-8 rounds in the MVP.
+- Required provider turns are `rounds * 2 + 1` and may never exceed `--max-turns`.
+- Only explicit design-room responses are persisted; private reasoning is never requested or stored.
+- Discussion prompts prohibit edits and command execution.
+- Every provider turn is preceded by a kill-switch check.
+- No new dependency.
+
+---
+
+### Task 1: Define the discussion protocol and state reader
+
+**Files:**
+
+- Modify: `src/core/coordination/events.ts`
+- Create: `src/core/coordination/discussion.ts`
+- Test: `tests/coordination-discussion.test.ts`
+
+**Interfaces:**
+
+- Produces: `discussionPayloadSchema`, `DiscussionPayload`,
+  `listDiscussions(projectRoot)`, and `getDiscussion(projectRoot, threadId)`.
+
+- [ ] Write schema/state tests for strict kinds, bounds, reply IDs, bounded lists,
+      and reconstruction from real coordination events.
+- [ ] Run `npx vitest run tests/coordination-discussion.test.ts` and confirm the
+      missing exports fail.
+- [ ] Add the event schema and minimal state reader.
+- [ ] Re-run the focused test until green.
+
+### Task 2: Implement the provider-neutral bounded orchestrator
+
+**Files:**
+
+- Modify: `src/core/coordination/discussion.ts`
+- Modify: `src/core/coordination/adapters/types.ts`
+- Test: `tests/coordination-discussion.test.ts`
+- Test: `tests/coordination-adapters.test.ts`
+
+**Interfaces:**
+
+- Consumes: `emit(projectRoot, EmitOptions)` and participant `respond(prompt)`.
+- Produces: `runDiscussion(projectRoot, options): Promise<DiscussionResult>` and
+  public transcript formatting.
+
+- [ ] Write failing tests for alternating turns, reply chains, safe prompts,
+      exact turn counts, final synthesis, provider rejection, and kill switch.
+- [ ] Run the focused tests and confirm behavioral failures.
+- [ ] Implement the minimum sequential orchestration and discussion formatting.
+- [ ] Re-run the focused suites until green.
+
+### Task 3: Add the public CLI and provider-session bridge
+
+**Files:**
+
+- Create: `src/commands/coordination-discussions.ts`
+- Modify: `src/commands/coordinate.ts`
+- Modify: `src/core/coordination/session-manager.ts`
+- Test: `tests/coordination-session-commands.test.ts`
+- Test: `tests/coordination-discussion.test.ts`
+
+**Interfaces:**
+
+- Produces: `parseDiscussionAgents`, `parseDiscussionSessions`,
+  `registerCoordinationDiscussions`, and a SessionManager-backed responder.
+
+- [ ] Write failing parser and provider-composition tests.
+- [ ] Reject invalid rounds, insufficient budgets, duplicate providers, and
+      simultaneous `--agents`/`--sessions` before starting a provider session.
+- [ ] Implement `start`, `list`, and `show` with JSON output.
+- [ ] Run CLI and discussion focused suites until green.
+
+### Task 4: Integrate visibility and documentation
+
+**Files:**
+
+- Modify: `src/core/coordination/replay.ts`
+- Modify: `src/core/coordination/interrupt-policy.ts`
+- Modify: `README.md`
+- Modify: `docs/LIVE_COLLABORATION.md`
+- Modify: `docs/USER_TEST_GUIDE.md`
+- Create: `docs/decisions/003-bounded-agent-discussions.md`
+- Test: `tests/coordination-replay.test.ts`
+- Test: `tests/coordination-interrupt-policy.test.ts`
+- Test: `tests/readme-product-flow.test.ts`
+
+**Interfaces:**
+
+- Consumes: additive `discussion` events.
+- Produces: readable replay, safe-boundary delivery, and copy-paste user flows.
+
+- [ ] Write failing formatting/policy/docs assertions.
+- [ ] Add replay and injection visibility without changing existing semantics.
+- [ ] Record why the design is bounded, sequential, and local-first.
+- [ ] Run focused tests until green.
+
+### Task 5: Release-quality verification and review
+
+**Files:**
+
+- Modify: `CHANGELOG.md`
+- Modify: `tasks/plan.md`
+- Modify: `tasks/todo.md`
+
+- [ ] Run `npx vitest run 'tests/coordination*.test.ts'`.
+- [ ] Run `npm run verify:full` and inspect every exit code and test count.
+- [ ] Run `git diff --check`, inspect the complete diff for correctness,
+      readability, architecture, security, and performance, and fix findings.
+- [ ] Update the 0.9.0 changelog and task checklist with the verified behavior.
+- [ ] Commit atomically and push the feature branch; do not tag or publish npm.

package/docs/superpowers/plans/2026-09-04-handoff-context-bundles.md

@@ -0,0 +1,109 @@
+# Safe Handoff Context Bundles Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use test-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add explicit, bounded, secret-redacted file snapshots to durable handoff tasks without breaking existing logs or callers.
+
+**Architecture:** A focused `handoff-bundle` module validates and snapshots files before the task is appended. `handoff.ts` stores only a typed reference in JSONL, while the versioned bundle lives in `.handoff/bundles/` and is loaded for receiver display or direct inspection. Commander composes both operations and preserves the existing no-bundle path.
+
+**Tech Stack:** TypeScript, Node.js filesystem/crypto/path APIs, Commander, Zod, Vitest.
+
+## Global constraints
+
+- No new runtime dependencies.
+- Maximum 20 files, 32 KiB stored content per file, and 50 KiB total.
+- Never follow symlinks, leave the repository, read binary files, or bundle `.git/`/`.handoff/`.
+- Redact before persistence; write owner-only bundle files atomically.
+- Keep existing handoff messages and callers backward compatible.
+
+---
+
+### Task 1: Define and persist safe bundles
+
+**Files:**
+
+- Create: `src/core/delegation/handoff-bundle.ts`
+- Create: `tests/handoff-bundle.test.ts`
+
+**Interfaces:**
+
+- Produces: `createHandoffBundle(projectRoot, taskId, requestedPaths)`
+- Produces: `readHandoffBundle(projectRoot, reference)`
+- Produces: bundle types and exported limits
+
+- [ ] Write the failing happy-path test and observe the missing module failure.
+- [ ] Implement strict schemas, path validation, bounded UTF-8 reads, redaction,
+      atomic persistence, and validated reads.
+- [ ] Add red-green tests for path escapes, internal state, symlinks,
+      directories, binary/missing files, limits, Unicode, and corruption.
+- [ ] Run `npm test -- tests/handoff-bundle.test.ts`.
+
+### Task 2: Extend the message protocol and receiver output
+
+**Files:**
+
+- Modify: `src/core/delegation/handoff.ts`
+- Modify: `tests/handoff.test.ts`
+
+**Interfaces:**
+
+- Consumes: `HandoffBundleReference`
+- Produces: optional `bundle` on messages and send options
+- Produces: resolved bundle summaries in inbox output
+
+- [ ] Write a failing round-trip test for a bundle reference plus a legacy task.
+- [ ] Add the optional strict field and run the test.
+- [ ] Write a failing output test for bundle metadata and trust warning.
+- [ ] Implement async inbox display loading while preserving old output.
+- [ ] Run both focused suites.
+
+### Task 3: Add the public CLI option
+
+**Files:**
+
+- Modify: `src/commands/catalog-workflows.ts`
+- Create or modify: `tests/cli-handoff.test.ts`
+
+**Interfaces:**
+
+- Consumes: `--bundle <paths...>`
+- Produces: bundle metadata in JSON and concise text confirmation
+
+- [ ] Write and observe a failing CLI happy-path test.
+- [ ] Add the variadic option and compose bundle creation before task append.
+- [ ] Remove a newly created orphan bundle if message persistence fails.
+- [ ] Add an invalid-path test proving there is no partial task.
+- [ ] Run CLI and handoff focused suites.
+
+### Task 4: Document receiver behavior and manual testing
+
+**Files:**
+
+- Modify: `README.md`
+- Modify: `docs/REFERENCE.md`
+- Modify: `docs/USER_TEST_GUIDE.md`
+- Modify: `skills/loadout-handoff/SKILL.md`
+- Modify: `src/core/delegation/handoff.ts`
+
+**Interfaces:**
+
+- Documents: exact command, limits, local persistence, and trust model
+
+- [ ] Add the command near the existing handoff quick start.
+- [ ] Document limits and failure modes in the reference.
+- [ ] Add a disposable-repository test for redaction and pickup.
+- [ ] Teach agents to inspect the bundle as untrusted project data.
+- [ ] Run documentation and first-party skill checks.
+
+### Task 5: Verify and review
+
+**Files:**
+
+- Modify: `tasks/plan.md`
+- Modify: `tasks/todo.md`
+
+- [ ] Run formatting, lint, typecheck, full verification, and inspect exits.
+- [ ] Review correctness, security, maintainability, performance, and tests.
+- [ ] Fix findings through new failing tests.
+- [ ] Run `loadout handoff codex` per repository instructions.
+- [ ] Commit the verified branch without tagging or publishing.

package/docs/superpowers/plans/2026-09-04-handoff-verification.md

@@ -0,0 +1,56 @@
+# Handoff Verification Evidence Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use test-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make handoff completion evidence-backed while keeping execution explicit, bounded, redacted, and shell-free.
+
+**Architecture:** Extend the JSONL message contract additively, then put command execution and state transitions in a dedicated verification module. The CLI validates option combinations and invokes verification only on an explicit completion command. Failed checks write a nonterminal status event, so the original task remains actionable.
+
+**Tech Stack:** TypeScript, Node.js child processes, Zod, Commander, Vitest.
+
+## Global constraints
+
+- No shell strings, automatic retries, provider turns, or new dependencies.
+- A stored command requires explicit `--run-verification` approval at completion.
+- Preserve legacy handoff behavior.
+- Bound and redact every persisted output.
+- Every behavior follows a red-green test cycle.
+
+### Task 1: Add typed verification and evidence fields
+
+**Files:** `src/core/delegation/handoff.ts`, `tests/handoff.test.ts`
+
+- [ ] Write a failing round-trip test for verification and evidence.
+- [ ] Add strict bounded optional schemas and types.
+- [ ] Render criteria and command argv in the task inbox.
+- [ ] Verify legacy logs still parse.
+
+### Task 2: Implement explicit completion verification
+
+**Files:** `src/core/delegation/handoff-verification.ts`,
+`tests/handoff-verification.test.ts`
+
+- [ ] Write a failing passing-command test with an injected runner.
+- [ ] Implement pass → `done` and fail → nonterminal `status` transitions.
+- [ ] Add red-green cases for manual evidence, missing evidence, nonzero exit,
+      timeout, spawn error, output truncation, and secret redaction.
+- [ ] Keep `markDone` compatible for tasks without criteria and make it refuse
+      to bypass criteria.
+
+### Task 3: Wire and document the CLI
+
+**Files:** `src/commands/catalog-workflows.ts`, `tests/cli-handoff.test.ts`,
+`README.md`, `docs/REFERENCE.md`, `docs/USER_TEST_GUIDE.md`,
+`skills/loadout-handoff/SKILL.md`, `CHANGELOG.md`
+
+- [ ] Test and add `--verify`, `--verify-command`, `--verify-timeout`, and
+      `--evidence`.
+- [ ] Validate incompatible combinations before writing a task.
+- [ ] Show pass/fail evidence in text and JSON output.
+- [ ] Document the exact trust boundary and lack of autonomous retries.
+
+### Task 4: Verify and commit
+
+- [ ] Run focused tests, formatting, lint, typecheck, `npm run verify:full`, and
+      a five-axis review.
+- [ ] Commit and push the isolated incremental change without publishing.