loadout-ai 0.8.0 → 0.9.0

package/docs/FEATURE_TEST_MATRIX.md

@@ -108,11 +108,11 @@ 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.
+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                                    |
 | -------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |

package/docs/LIVE_COLLABORATION.md

@@ -0,0 +1,234 @@
+# 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)
+
+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.
+
+## 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.
+
+## 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.
+
+## 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,163 @@
+# 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.
+
+## 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:

package/docs/USER_TEST_GUIDE.md

@@ -192,7 +192,142 @@ GitHub token; use `loadout mcp-recipe --credential-free` to exclude every servic
 credential too. Browser configuration and real connection testing remain explicit.
 Graphify is a separate runtime tool, not an MCP server.
 
-## 8. Preview complete cleanup
+## 8. Test handoff and live coordination in a disposable repository
+
+Create a temporary Git repository so the test does not add handoff files to a
+real project:
+
+```bash
+mkdir loadout-coordination-test
+cd loadout-coordination-test
+git init
+```
+
+First test the stable session-boundary inbox:
+
+```bash
+loadout handoff codex "Implement the frontend" --context "Claude owns src/api; consume checkout-api"
+loadout handoff codex
+loadout handoff
+```
+
+Copy the task ID printed by the inbox, then settle it:
+
+```bash
+loadout handoff --done <task-id>
+loadout handoff codex
+```
+
+Next test structured coordination without running either model:
+
+```bash
+loadout coord own claude-code src/api
+loadout coord own codex src/web
+loadout coord contract checkout-api --agent claude-code \
+  --body "POST /api/checkout -> 201 { id: string }"
+loadout coord snapshot codex
+loadout coord ack codex 2
+loadout coord status
+loadout coord replay
+```
+
+Sequence numbers are printed by each command; use the actual latest relevant
+sequence if it differs from `2`. Confirm that the first overlapping exclusive
+claim is refused, then release the original path and confirm the retry succeeds:
+
+```bash
+loadout coord own codex src/api/checkout.ts
+loadout coord release claude-code src/api
+loadout coord own codex src/api/checkout.ts
+```
+
+Test the authenticated live dashboard in one terminal:
+
+```bash
+loadout daemon start
+```
+
+Open the exact dashboard URL it prints. In a second terminal, run another
+`loadout coord update` and confirm it appears. A bare `/api/status` request
+without the bearer token should return `401`. Press Ctrl+C in the daemon
+terminal when finished.
+
+Test the packaged MCP transport without changing either agent's configuration:
+
+```bash
+loadout serve
+```
+
+The process waits for MCP JSON-RPC on stdin and should print no banners or prose
+to stdout. Press Ctrl+C. Host-specific configuration and the exact tool list are
+in [the live coordination guide](./LIVE_COLLABORATION.md).
+
+Finally, inspect the provider bridge surface:
+
+```bash
+loadout coord agents detect
+loadout coord agents list
+loadout coord agents bridge --help
+```
+
+The next commands run real provider turns and may consume Claude/Codex quota.
+Only run them when you intentionally want that test:
+
+```bash
+loadout coord agents start claude-code "Claim backend files and publish a test contract"
+loadout coord agents start codex "Read the shared snapshot and acknowledge the contract"
+loadout coord agents bridge claude-code:<session-id> codex:<thread-id> --max-turns 4
+```
+
+While the bridge runs, publish a new contract from another terminal. Confirm
+both provider sessions can proceed concurrently and that the bridge prints
+their responses. Progress-only `update` events remain passive by default. Use
+Ctrl+C to stop the bridge. Activate `loadout daemon kill "user test"` to verify
+that new coordination writes and provider turns stop, then run
+`loadout daemon resume`.
+
+Now test an actual back-and-forth design discussion. This spends exactly three
+provider turns: one Claude proposal, one Codex critique, and one Claude
+synthesis. Neither agent should edit the disposable repository.
+
+```bash
+loadout coord discuss start "Should this test service expose REST or GraphQL?" \
+  --agents claude-code,codex \
+  --rounds 1 \
+  --max-turns 3 \
+  --timeout 120
+```
+
+Confirm all of the following before publishing:
+
+1. stderr announces exactly three paid provider turns before either provider
+   runs;
+2. Claude Code proposes a design and Codex directly critiques that proposal;
+3. Claude's synthesis names a decision, rationale, alternatives, and any
+   unresolved disagreement;
+4. `loadout coord discuss list` reports the thread as `closed`;
+5. `loadout coord discuss show <thread-id>` shows the linked public transcript;
+6. `loadout coord replay` includes the discussion and the resulting decision;
+7. `git status --short` shows that neither agent edited a project file.
+
+Repeat with known real session IDs to validate resumption:
+
+```bash
+loadout coord discuss start "What validation boundary should this service use?" \
+  --sessions claude-code:<session-id> codex:<thread-id> \
+  --rounds 1 --max-turns 3
+```
+
+For the kill-switch check, start a two-round discussion in one terminal and run
+`loadout daemon kill "stop design room"` in another while the first provider
+turn is active. The in-flight provider may finish, but its response must not be
+persisted and Codex must not receive the next turn. Run `loadout daemon resume`
+after confirming the halt.
+
+Delete the disposable repository after inspection. Its `.handoff` directory
+contains the local task/event audit trail, token, and session IDs.
+
+## 9. Preview complete cleanup
 
 ```bash
 loadout uninstall
@@ -211,7 +346,7 @@ cleanup deliberately deletes Loadout's snapshots, so it is the last lifecycle te
 ## Troubleshooting and recovery
 
 - **`loadout` is not found after installation:** confirm `npm install --global
-loadout-ai@0.5.9` completed, run `hash -r`, and confirm npm's global binary
+loadout-ai@0.9.0` completed, run `hash -r`, and confirm npm's global binary
   directory is on `PATH`. For a source checkout, run `npm run build` and `npm link`.
 - **A preview asks for `--approve-risk`:** read the reported scripts, domains,
   credentials, binaries, or instruction findings. If you accept that specific plan,
@@ -238,7 +373,7 @@ loadout-ai@0.5.9` completed, run `hash -r`, and confirm npm's global binary
   Unmanaged content is preserved, and modified managed files can make cleanup refuse
   until you explicitly review the command's force path.
 
-## 9. Advanced surface
+## 10. Advanced surface
 
 The first help screen deliberately focuses on daily use. Existing advanced
 commands have not been removed:

package/docs/decisions/001-coordination-jsonl-locking.md

@@ -0,0 +1,35 @@
+# ADR 001: JSONL plus a project lock for coordination state
+
+- Status: accepted
+- Date: 2026-09-03
+
+## Context
+
+Loadout coordinates a small number of local coding-agent processes in one
+repository. Events need durable ordering, human inspectability, recovery after
+partial writes, and parity across CLI, MCP, HTTP, and provider adapters. A
+database would add installation, migration, backup, and corruption-recovery
+surface before the expected workload requires indexed storage.
+
+## Decision
+
+Use `.handoff/coordination.jsonl` as the source of truth. Serialize every
+mutation with `.handoff/coordination.lock`, created exclusively with owner-only
+permissions. Allocate event sequences and contract revisions while holding that
+lock. Derive current ownership, contracts, acknowledgements, and snapshots from
+validated events.
+
+Compaction holds the same lock, writes a complete owner-only archive first,
+then atomically replaces the working log with a valid summary and retained
+events. Missing files mean empty state; other I/O errors propagate. Invalid
+lines are reported without hiding valid neighbors.
+
+## Consequences
+
+- The audit trail is readable and easy to back up or remove.
+- Independent local processes cannot allocate duplicate sequences or accept
+  conflicting ownership claims concurrently.
+- Reads are linear in the active log, so retention must keep it bounded.
+- This design is for local repository coordination, not a remote multi-user
+  service. A future remote transport would require a separate trust and storage
+  decision rather than exposing this daemon to a network.