loadout-ai 0.8.0 → 0.9.1

package/docs/FEATURE_TEST_MATRIX.md

@@ -108,23 +108,38 @@ the capability table names native, adapted, and unsupported surfaces honestly.
 Run the entire required gate with one command:
 
 ```bash
-npm run verify
+npm run verify:full
 ```
 
-`npm run verify:full` is an alias for the same CLI release gate. The individual stages
-are listed below for focused reruns and diagnosis.
-
-| Command                    | Coverage                                                                | Expected result                                    |
-| -------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
-| `npm run format:check`     | Repository formatting                                                   | Exit 0; no files changed.                          |
-| `npm run lint`             | TypeScript lint rules                                                   | Exit 0.                                            |
-| `npm run typecheck`        | TypeScript contract                                                     | Exit 0.                                            |
-| `npm run check:evidence`   | Catalog/discovery attribution, README claims, and release boundaries    | Exit 0; no claim is silently promoted.             |
-| `npm test`                 | Unit, integration, native filesystem, safety, and regression suites     | All tests pass.                                    |
-| `npm run test:e2e:cli`     | Disposable scan → compare → optimize → apply → rollback journey         | Prints a successful CLI product flow.              |
-| `npm run test:e2e:readme`  | Isolated library/activation/manifest/card/rollback journey              | Prints README product flow success.                |
-| `npm run test:package`     | `npm pack`, install outside the checkout, packaged CLI install/rollback | Prints package smoke success.                      |
-| `npm run test:performance` | Seven scans of 1,000 real on-disk skill directories                     | p95 remains below the enforced five-second budget. |
+This is the release gate. It runs the normal verification path plus coverage.
+The individual stages are listed below for focused reruns and diagnosis.
+
+| Command                         | Coverage                                                                | Expected result                                    |
+| ------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
+| `npm run format:check`          | Repository formatting                                                   | Exit 0; no files changed.                          |
+| `npm run lint`                  | TypeScript lint rules                                                   | Exit 0.                                            |
+| `npm run typecheck`             | TypeScript contract                                                     | Exit 0.                                            |
+| `npm run check:evidence`        | Catalog/discovery attribution, README claims, and release boundaries    | Exit 0; no claim is silently promoted.             |
+| `npm test`                      | Unit, integration, native filesystem, safety, and regression suites     | All tests pass.                                    |
+| `npm run test:e2e:cli`          | Disposable scan → compare → optimize → apply → rollback journey         | Prints a successful CLI product flow.              |
+| `npm run test:e2e:readme`       | Isolated library/activation/manifest/card/rollback journey              | Prints README product flow success.                |
+| `npm run test:e2e:coordination` | Disposable ownership/contract/template/verified-handoff journey         | Prints coordination product flow success.          |
+| `npm run test:package`          | `npm pack`, install outside the checkout, packaged CLI install/rollback | Prints package smoke success.                      |
+| `npm run test:performance`      | Seven scans of 1,000 real on-disk skill directories                     | p95 remains below the enforced five-second budget. |
+
+Coordination convenience regressions are covered by:
+
+```bash
+npx vitest run tests/handoff-templates.test.ts tests/cli-handoff.test.ts \
+  tests/handoff-verification.test.ts tests/coordination-quick-start.test.ts \
+  tests/auto-contract.test.ts tests/git-ownership.test.ts \
+  tests/discussion-pipeline.test.ts
+```
+
+These tests cover traversal rejection, template interpolation and bundles,
+non-blocking verified completion, normalized ownership splits, exact/current/
+stale contract candidates, Git author mappings, and idempotent linked handoffs.
+Windows CI is authoritative for native path behavior and must be green.
 
 The focused regression contract for the v0.3.x profile lifecycle is:
 

package/docs/LIVE_COLLABORATION.md

@@ -0,0 +1,283 @@
+# Live Claude Code ↔ Codex coordination
+
+Live coordination is beta in 0.9.0. The ordinary `loadout handoff` inbox is
+the stable fallback: it is durable, understandable, and does not run either
+provider automatically.
+
+## What “shared memory” means
+
+Loadout shares structured project facts, not private conversations or model
+context windows. Both agents can see the same tasks, file ownership, versioned
+contracts, decisions, progress, blockers, verification results, and cursors.
+Every accepted event is persisted before a watcher, dashboard, or provider
+bridge sees it.
+
+```text
+Claude Code CLI  <---->  provider bridge  <---->  Codex SDK
+                              |
+                    coordination protocol
+                    .handoff/coordination.jsonl
+                       /        |        \
+                    CLI        MCP     HTTP/SSE
+```
+
+The source of truth is an append-only project JSONL log protected by an
+exclusive cross-process lock. There is no cloud service and no SQLite database.
+Sequence numbers, acknowledgements, and snapshots make reconnects deterministic.
+
+## Three operating levels
+
+1. **Durable handoff (stable):** `loadout handoff` passes a bounded task and
+   context to the next agent session.
+2. **Shared coordination protocol (beta):** CLI or MCP tools publish and read
+   structured events. Agents see changes when they call `snapshot`/`subscribe`,
+   while the local daemon and dashboard can observe changes immediately.
+3. **Provider bridge (beta, opt-in):** a long-running local process resumes
+   provider sessions and submits relevant events as new follow-up turns.
+4. **Bounded design discussion (beta, opt-in):** Claude Code and Codex
+   alternate proposals and critiques on one question, then record a decision.
+
+The bridge does not inject into an already-running turn. Delivery happens at a
+safe turn boundary because that is what the supported Claude Code CLI and Codex
+SDK interfaces provide.
+
+## Quick protocol test (no paid agent turn)
+
+For the beginner path, preview and approve a normalized ownership split:
+
+```bash
+loadout coord start --agents claude-code,codex
+loadout coord start --agents claude-code,codex --yes
+```
+
+The command ignores generated directories and collapses redundant child paths.
+Any existing ownership makes it stop rather than overwrite active work.
+
+Run these commands in a disposable Git repository:
+
+```bash
+loadout coord own claude-code src/api
+loadout coord contract checkout-api --agent claude-code \
+  --body "POST /api/checkout -> 201 { id: string }"
+loadout coord snapshot codex
+loadout coord ack codex 1
+loadout coord release claude-code src/api
+loadout coord status
+loadout coord replay
+```
+
+The contract revision is allocated atomically when `--revision` is omitted.
+Overlapping exclusive ownership is rejected. A future acknowledgement or stale
+explicit contract revision is rejected as a conflict.
+
+After ownership exists, detect imports that cross agent boundaries:
+
+```bash
+loadout coord detect
+loadout coord detect --publish
+loadout coord detect --publish --yes
+```
+
+Detection is conservative. Exact supported one-line declarations may be
+published after the second approval; multiline or ambiguous declarations are
+marked `MANUAL` and refused. Existing generated bodies are reported as current
+or stale. This is an on-demand scan, not a background compiler or watcher.
+
+## Connect the MCP server
+
+`loadout serve` starts a protocol-only stdio MCP server in the current project.
+It exposes `claim_task`, `release_ownership`, `publish_contract`,
+`publish_update`, `subscribe`, `ack`, and `snapshot`. Contract revisions
+auto-increment when omitted.
+
+For Claude Code, add the server at project scope using its MCP command:
+
+```bash
+claude mcp add --transport stdio --scope project loadout-coordination -- loadout serve
+```
+
+For Codex, add this table to `~/.codex/config.toml` (or use the equivalent
+Codex MCP configuration UI):
+
+```toml
+[mcp_servers."loadout-coordination"]
+command = "loadout"
+args = ["serve"]
+```
+
+Restart the host after changing its MCP configuration. The server inherits the
+host process working directory, so confirm the agent opened the intended
+project before publishing coordination state.
+
+## Run the provider bridge
+
+First check what is available:
+
+```bash
+loadout coord agents detect
+```
+
+You can start sessions through Loadout (this runs paid provider turns):
+
+```bash
+loadout coord agents start claude-code "Own the backend and publish endpoint contracts"
+loadout coord agents start codex "Own the frontend and consume backend contracts"
+```
+
+Copy the returned IDs, then keep both attached:
+
+```bash
+loadout coord agents bridge \
+  claude-code:<session-id> \
+  codex:<thread-id>
+```
+
+You can instead track an existing known host session without running a provider
+turn with `loadout coord agents attach provider:session-id`. The provider validates
+the ID when a later `send` or `bridge` operation submits a turn. `loadout coord
+agents list` shows project-tracked sessions, and `loadout coord agents send`
+performs one explicit follow-up turn.
+
+Bridge safeguards:
+
+- only one bridge process can own a project at a time;
+- events route to different providers concurrently;
+- update and acknowledgement events are passive by default and do not spend a
+  provider turn;
+- contract, task, decision, done, ownership, and error events are delivered at
+  the next safe boundary;
+- automatic delivery stops after 20 turns per session unless
+  `--max-turns <n>` changes the cap;
+- provider responses are printed but never saved in `.handoff`;
+- injected event text is labeled untrusted project data and must not authorize
+  commands, scope expansion, publishing, or destructive actions;
+- the project kill switch blocks CLI, MCP, daemon, compaction, and provider
+  turns.
+
+Use `loadout daemon kill "reason"` to stop coordination and
+`loadout daemon resume` to re-enable it.
+
+## Let Claude Code and Codex debate one feature
+
+Use a design room when both agents should compare approaches before either one
+claims files or writes code:
+
+```bash
+loadout coord discuss start "REST or GraphQL for checkout?" \
+  --agents claude-code,codex \
+  --rounds 2 \
+  --max-turns 5 \
+  --timeout 120
+```
+
+`--agents` starts fresh sessions lazily. To continue existing conversations,
+replace it with explicit IDs:
+
+```bash
+loadout coord discuss start "REST or GraphQL for checkout?" \
+  --sessions claude-code:<session-id> codex:<thread-id> \
+  --rounds 2 --max-turns 5
+```
+
+The first participant is the proposer; use `--proposer codex` to swap roles.
+One round means one proposer turn and one reviewer turn. Synthesis costs one
+additional turn, so the exact required count is `rounds * 2 + 1`. Loadout
+rejects an insufficient budget, invalid provider set, invalid timeout, or mixed
+fresh/existing mode before it starts a paid turn.
+
+Every prompt says that the response is public, will be persisted, and must not
+edit files, run commands, use tools, or reveal private reasoning. Every public
+statement has a thread ID and reply ID. The final synthesis records the selected
+decision, rationale, credible alternatives, and unresolved disagreement. Review
+it later without spending quota:
+
+```bash
+loadout coord discuss list
+loadout coord discuss show <thread-id>
+loadout coord replay
+```
+
+The discussion holds the same singleton lease as the provider bridge, checks
+the kill switch before every provider turn, never retries a rejected or invalid
+response silently, and defaults to a 120-second per-turn timeout. It does not
+begin implementation automatically.
+
+Turn an accepted decision into implementation only after reviewing the dry run:
+
+```bash
+loadout coord discuss implement <thread-id>
+loadout coord discuss implement <thread-id> --yes
+```
+
+The approved command refuses mentioned paths without ownership, bundles files
+that already exist, attaches acceptance criteria, records generated handoff
+IDs, and uses a deterministic plan ID so retries do not duplicate tasks.
+Extracted paths are normalized inside the project and the plan fails before
+sending anything if it exceeds the 256-file coordination event limit.
+
+Git history can suggest ownership when commits carry distinguishable authors:
+
+```bash
+loadout coord git-ownership \
+  --agents "claude-code=Claude Opus 4.6,codex=Viraj Mishra"
+```
+
+Confidence includes commits by unmapped human authors. Add `--yes` only after
+reviewing the suggestions; Git history is evidence, not proof of current intent.
+
+## Optional daemon and dashboard
+
+```bash
+loadout daemon start
+```
+
+The daemon binds only to `127.0.0.1`. It prints an authenticated dashboard URL
+whose token is carried in the URL fragment, moved immediately into browser
+session storage, and removed from visible history. REST and SSE accept bearer
+headers only; query-string tokens, non-loopback Host headers, and cross-origin
+browser requests are rejected. The token and session state are project-local
+files with mode `0600`.
+
+The dashboard is observability, not an agent injector. Use the MCP tools or the
+provider bridge for agent-to-agent delivery.
+
+## Safety and data model
+
+- Event schemas cap names, descriptions, context, payloads, arrays, and paths.
+- Secret-like keys and values are redacted at the canonical write boundary, so
+  CLI, MCP, and HTTP writes follow the same rule.
+- Ownership claims use normalized project-relative paths and detect directory /
+  child overlap.
+- Contract revisions and event sequences are allocated while holding the same
+  project lock.
+- Compaction first writes a complete archival copy and aborts if archival fails.
+- Corrupt JSONL lines are reported rather than hiding valid neighboring events.
+- `.handoff/coordination.jsonl` is project data. Do not commit it when its facts
+  are private; add the appropriate `.handoff` paths to `.gitignore`.
+
+## Honest limitations
+
+- This is durable shared state plus follow-up turns, not one simultaneous model
+  context or provider-to-provider hidden channel.
+- Claude Code and Codex authentication, quotas, billing, and host session IDs
+  remain provider concerns.
+- The bridge cannot steer a turn already in progress.
+- The design-room kill switch cannot cancel a provider call already in flight;
+  it prevents persistence and the next provider turn.
+- A provider may fail, time out, reject a resume ID, or return output Loadout
+  cannot parse. The event stays durable and can still be consumed manually.
+- The bridge is local to one machine and one repository. Remote teams need a
+  separately designed authenticated transport; this release intentionally does
+  not expose the daemon to a network.
+- Contract detection supports relative TypeScript/JavaScript imports and exact
+  one-line declarations; aliases, generated clients, path mappings, and complex
+  multiline declarations may require a manual contract.
+
+## Evidence
+
+The coordination test suite covers concurrent writers, ownership conflicts,
+revision allocation, malformed logs, redaction, authenticated HTTP/SSE, MCP
+stdio framing, retention failure safety, kill-switch behavior, provider CLI/SDK
+shapes, session replay, concurrent provider delivery, passive policy, and the
+automatic-turn cap. The package smoke test verifies the compiled MCP artifact is
+included in the npm tarball.

package/docs/REFERENCE.md

@@ -0,0 +1,263 @@
+# Loadout Reference
+
+Detailed configuration, profiles, integrations, and discovery documentation.
+For the quick start, see the [README](../README.md).
+
+## Profiles
+
+Loadout is opinionated when you want it to be and precise when you do not. The
+modes differ in one thing: how much of the reviewed catalog they install.
+
+| Mode      | Sources               | Skills | Active by default                |
+| --------- | --------------------- | ------ | -------------------------------- |
+| `stable`  | 4                     | 30     | yes — recommended starting point |
+| `power`   | 8                     | 56     | yes                              |
+| `maximum` | all reviewed          | all    | **no — downloaded but disabled** |
+| `custom`  | your `--package` list | varies | yes                              |
+
+**Maximum is the one worth understanding.** It downloads the entire reviewed
+library and leaves every skill _disabled_. Nothing reaches an agent prompt until
+a project activates what it needs:
+
+```bash
+loadout setup --mode maximum --yes
+cd ~/code/my-app
+loadout optimize --project .   # scans the repo, proposes an active set
+loadout activate               # enable just those here
+```
+
+That trade is deliberate: disk is cheap and context is not. A large disabled
+library plus a small active set beats installing everything into every prompt.
+
+### Stable: the essentials
+
+Stable is the recommended daily driver: **30 selected skill directories from four
+pinned public sources**, installed into each agent you choose.
+
+| Included source                                                        | What Stable takes from it                                     | GitHub                                                                                                                                            |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Superpowers](https://github.com/obra/superpowers)                     | Planning, execution, testing, review, verification            | [![GitHub stars](https://img.shields.io/github/stars/obra/superpowers?style=flat&label=stars)](https://github.com/obra/superpowers)               |
+| [Context7](https://github.com/upstash/context7)                        | Current documentation and MCP workflows                       | [![GitHub stars](https://img.shields.io/github/stars/upstash/context7?style=flat&label=stars)](https://github.com/upstash/context7)               |
+| [Addy Osmani Agent Skills](https://github.com/addyosmani/agent-skills) | Engineering, frontend, debugging, performance, docs, shipping | [![GitHub stars](https://img.shields.io/github/stars/addyosmani/agent-skills?style=flat&label=stars)](https://github.com/addyosmani/agent-skills) |
+| [Agent Skills Marketplace](https://github.com/wshobson/agents)         | Architecture, review, error handling, JavaScript, Python      | [![GitHub stars](https://img.shields.io/github/stars/wshobson/agents?style=flat&label=stars)](https://github.com/wshobson/agents)                 |
+
+```bash
+loadout setup --mode stable
+loadout setup --mode stable --yes
+```
+
+### Power: a larger cross-project toolkit
+
+Power draws a skill-level allowlist from eight major collections.
+
+| Included source                                                          | Focus                                                     | GitHub                                                                                                                                                                      |
+| ------------------------------------------------------------------------ | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Anthropic Skills](https://github.com/anthropics/skills)                 | Documents, frontend, MCP building, web testing            | [![GitHub stars](https://img.shields.io/github/stars/anthropics/skills?style=flat&label=stars)](https://github.com/anthropics/skills)                                       |
+| [OpenAI Skills](https://github.com/openai/skills)                        | CLI, docs, browser work, images, security                 | [![GitHub stars](https://img.shields.io/github/stars/openai/skills?style=flat&label=stars)](https://github.com/openai/skills)                                               |
+| [Vercel Agent Skills](https://github.com/vercel-labs/agent-skills)       | React, web design, composition, deployment                | [![GitHub stars](https://img.shields.io/github/stars/vercel-labs/agent-skills?style=flat&label=stars)](https://github.com/vercel-labs/agent-skills)                         |
+| [Superpowers](https://github.com/obra/superpowers)                       | Planning, debugging, testing, collaboration               | [![GitHub stars](https://img.shields.io/github/stars/obra/superpowers?style=flat&label=stars)](https://github.com/obra/superpowers)                                         |
+| [UI UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) | UI systems, slides, styling, product design               | [![GitHub stars](https://img.shields.io/github/stars/nextlevelbuilder/ui-ux-pro-max-skill?style=flat&label=stars)](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) |
+| [Context7](https://github.com/upstash/context7)                          | Current documentation and MCP workflows                   | [![GitHub stars](https://img.shields.io/github/stars/upstash/context7?style=flat&label=stars)](https://github.com/upstash/context7)                                         |
+| [Agent Skills Marketplace](https://github.com/wshobson/agents)           | Architecture, testing, APIs, TypeScript, Python           | [![GitHub stars](https://img.shields.io/github/stars/wshobson/agents?style=flat&label=stars)](https://github.com/wshobson/agents)                                           |
+| [Awesome Copilot](https://github.com/github/awesome-copilot)             | Codebase knowledge, plans, browser and security workflows | [![GitHub stars](https://img.shields.io/github/stars/github/awesome-copilot?style=flat&label=stars)](https://github.com/github/awesome-copilot)                             |
+
+```bash
+loadout setup --mode power
+```
+
+### Maximum: download broadly, activate intelligently
+
+Downloads every non-archived, technically screened skill component into
+Loadout's **disabled local library**. Then let the current project choose:
+
+```bash
+loadout setup --mode maximum
+loadout recommend --project .
+loadout optimize --project . --limit 30
+loadout optimize --project . --limit 30 --yes
+```
+
+### Custom: take exact control
+
+```bash
+# Replace the managed profile
+loadout setup --mode custom --package superpowers --package context7
+
+# Add without replacing
+loadout install --mode custom --package humanizer
+loadout install --mode custom --package obsidian-skills --agents claude-code,cursor
+```
+
+Run `loadout profiles` to compare every mode.
+
+## MCP integrations
+
+Profiles never start MCP servers silently.
+
+```bash
+loadout mcp-recipe                                          # list recipes
+loadout mcp-recipe --credential-free                        # no-credential subset
+loadout mcp-recipe playwright --agent claude-code           # preview
+loadout mcp-recipe playwright --agent claude-code --yes     # configure
+loadout mcp-recipe playwright --agent claude-code --verify  # test
+```
+
+Configuration alone does not start the server. Test a real connection separately
+with `--connect --approve-risk`. Loadout can reference credentials from environment
+variables or the OS keychain without printing their values.
+
+## Optional runtime tools
+
+[Graphify](https://github.com/Graphify-Labs/graphify) is an optional codebase graph
+tool. It does not require an LLM API key:
+
+```bash
+loadout tool graphify
+loadout tool graphify --yes --approve-risk
+loadout tool graphify --remove --yes --approve-risk
+```
+
+Executable tools remain an explicit choice instead of hiding inside a profile.
+
+## Catalog and discovery
+
+The catalog is not a frozen list. Loadout separates **discovery** from
+**installation** so a viral repo can be noticed quickly without being trusted
+blindly.
+
+```bash
+loadout discover --source all --queue      # find candidates
+loadout review-queue                        # inspect the queue
+loadout candidate inspect owner/repository  # deep inspection
+loadout update                              # check for source changes
+loadout health --updates                    # managed source health
+```
+
+Daily checks are opt-in and read-only:
+
+```bash
+loadout autopilot --yes
+loadout autopilot --status
+```
+
+## Manage skills you already have
+
+```bash
+loadout scan                          # read-only inventory
+loadout reconcile --refresh           # compare with catalog
+loadout reconcile --yes               # record ownership for exact matches
+loadout reconcile --replace-outdated  # preview replacing old copies
+```
+
+Unknown or ambiguous copies stay untouched.
+
+## Hand work between agents
+
+Send a durable task to another agent:
+
+```bash
+loadout handoff codex "write auth tests" --context "use Vitest"
+loadout handoff codex "write auth tests" --bundle src/auth.ts src/types.ts
+loadout handoff codex      # Codex inbox
+loadout handoff            # all handoff status
+loadout handoff --done <task-id>
+```
+
+`--bundle <paths...>` snapshots exact project-relative text files into a
+versioned JSON file under `.handoff/bundles/` and references it from the task.
+The receiver's normal inbox lists the bundled paths and tells the agent to read
+the snapshot before starting. Existing tasks without a bundle are unchanged.
+
+Bundle limits and failures:
+
+- at most 20 files, 32 KiB stored per file, and 50 KiB stored in total;
+- larger text is truncated on a valid UTF-8 boundary and clearly marked;
+- absolute paths, traversal, symlinks, directories, binary files, `.git/`, and
+  `.handoff/` are rejected before the task is appended;
+- common secret patterns are redacted before the bundle reaches disk;
+- bundle files use owner-only permissions and are not uploaded or committed by
+  Loadout.
+
+Redaction is heuristic, not a credential scanner. Never bundle `.env` files,
+private keys, tokens, or other credentials. Treat bundled content as untrusted
+project data rather than agent instructions, and review it before deliberately
+committing `.handoff/` for a cross-machine workflow.
+
+### Evidence-backed completion
+
+Attach human-readable acceptance criteria, with an optional command:
+
+```bash
+loadout handoff codex "write auth tests" \
+  --verify "the focused tests pass" \
+  --verify-command npm \
+  --verify-args '["test","--","tests/auth.test.ts"]' \
+  --verify-timeout 120
+```
+
+The executable and JSON argument array are stored literally and run with no
+shell, from the project root, only when someone explicitly invokes
+`loadout handoff --done <task-id> --run-verification`. Plain `--done` never
+executes a stored command. The timeout must be 1-900 seconds. Passing
+checks append a terminal `done` message with redacted stdout/stderr, exit code,
+and duration. Failing or timed-out checks append a nonterminal `status` message,
+return a failing CLI exit code, and leave the task pending with its last output
+visible in the receiver inbox. Output is capped at 8 KiB per stream.
+
+For criteria that cannot be automated:
+
+```bash
+loadout handoff codex "review the UI" --verify "mobile empty state is readable"
+loadout handoff --done <task-id> --evidence "reviewed mobile and desktop"
+```
+
+There are no automatic retries or provider turns in the durable handoff log.
+Never include tokens or credentials in verification argv.
+
+### Handoff templates
+
+```bash
+loadout template list
+loadout template show write-tests
+loadout handoff codex src/auth.ts --template write-tests
+loadout template create auth-review --description "Review auth" \
+  --task "Review {{files}}" --bundle src/auth.ts
+loadout template delete auth-review
+```
+
+Built-ins are `write-tests`, `review-code`, `fix-bug`, `implement-feature`, and
+`refactor`. Positional task text fills `{{files}}`, `{{description}}`, and
+`{{task}}`. Custom templates live under `.handoff/templates/`; names are
+kebab-case and validated before all filesystem access. Template verification
+commands still run only after explicit `--done --run-verification` approval.
+
+## Coordinate simultaneous agents
+
+```bash
+loadout coord start --agents claude-code,codex       # preview ownership
+loadout coord start --agents claude-code,codex --yes # apply
+loadout coord detect                                 # contract candidates
+loadout coord detect --publish --yes                 # exact candidates only
+loadout coord discuss implement <thread-id>          # preview linked tasks
+loadout coord discuss implement <thread-id> --yes    # dispatch once
+loadout coord git-ownership --agents "codex=Git Author"
+```
+
+Every convenience mutation is preview-first. Contract detection is conservative
+and refuses manual placeholders. Discussion implementation refuses unowned
+mentioned paths and is idempotent by deterministic plan ID. Git history
+percentages include unmapped authors; use explicit agent/author mappings when
+the Git identity is not literally the agent name. See
+[`LIVE_COLLABORATION.md`](./LIVE_COLLABORATION.md) for the protocol, MCP server,
+provider bridge, daemon, and honest limitations.
+
+## Agent support
+
+Loadout's adapter capability matrix covers **12 agents**: Claude Code, Cline,
+Codex, Cursor, Gemini CLI, GitHub Copilot, Hermes, Junie, Kiro CLI, OpenCode,
+Roo Code, Windsurf.
+
+See the [complete feature matrix](./FEATURE_TEST_MATRIX.md) for configured
+paths, filesystem lifecycle, platform, and native-host evidence.
+
+Use `loadout doctor --verbose` for the local component matrix.

package/docs/RELEASE_REVIEW.md

@@ -22,6 +22,6 @@ For current behavior and evidence, use:
   [sanitized July 19 live checks](./evidence/live-checks-2026-07-19.json) only when
   investigating that historical release line.
 
-The current release gate is `npm run verify`. Publication status must be checked
+The current release gate is `npm run verify:full`. Publication status must be checked
 against the npm registry and the corresponding GitHub release rather than inferred
 from this archived document.

package/docs/TESTING.md

@@ -68,7 +68,23 @@ checks the current pinned Stable sources and remains network-dependent.
 
 Run `npm run verify` for formatting, lint, types, deterministic evidence checks, all
 Vitest suites, both CLI journeys, package smoke, and the performance gate.
-`npm run verify:full` is retained as an alias for the same complete CLI gate.
+Run `npm run verify:full` before a release; it runs that gate and then enforces
+the global and security-sensitive per-file coverage floors.
+
+The coordination suites exercise the protocol separately from paid providers:
+
+```bash
+npx vitest run 'tests/coordination*.test.ts'
+npm run test:package
+```
+
+They cover cross-process ordering, ownership/revision conflicts, redaction,
+retention and recovery, daemon authentication, MCP framing, provider command/SDK
+shapes, automatic watcher delivery, passive interrupt policy, singleton bridge
+ownership, bounded two-agent discussion turns and reply chains, leases, and
+runaway-turn limits. Fake provider drivers are used for deterministic
+tests; the suite does not spend Claude or Codex quota. Follow the disposable
+manual flow in `docs/USER_TEST_GUIDE.md` for an intentional real-host test.
 
 Current npm publication, the current pinned Stable repositories, and GitHub repository
 settings are external state. Check them separately with: