loadout-ai 0.9.0 → 0.9.2

package/docs/FEATURE_TEST_MATRIX.md

@@ -114,17 +114,32 @@ npm run verify:full
 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: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. |
+| 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

@@ -43,6 +43,16 @@ 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
@@ -60,6 +70,19 @@ 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.
@@ -179,6 +202,29 @@ 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
@@ -223,6 +269,9 @@ provider bridge for agent-to-agent delivery.
 - 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
 

package/docs/REFERENCE.md

@@ -151,6 +151,106 @@ 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,

package/docs/USER_TEST_GUIDE.md

@@ -206,11 +206,23 @@ git init
 First test the stable session-boundary inbox:
 
 ```bash
-loadout handoff codex "Implement the frontend" --context "Claude owns src/api; consume checkout-api"
+mkdir -p src
+printf 'export const checkout = true;\n' > src/checkout.ts
+printf 'export type CheckoutId = string;\n' > src/types.ts
+loadout handoff codex "Implement the frontend" \
+  --context "Claude owns src/api; consume checkout-api" \
+  --bundle src/checkout.ts src/types.ts
 loadout handoff codex
 loadout handoff
 ```
 
+Confirm the inbox lists both bundled files and calls them untrusted project
+data. Inspect `.handoff/bundles/*.json`: the schema version is `1`, the task log
+contains only its bounded reference, and the bundle contains the source
+snapshots. For a redaction check, put a fake `sk-ant-` token longer than 20
+characters in a disposable file, bundle it, and confirm only `[REDACTED]` is
+stored. Never use a real credential.
+
 Copy the task ID printed by the inbox, then settle it:
 
 ```bash
@@ -218,8 +230,66 @@ loadout handoff --done <task-id>
 loadout handoff codex
 ```
 
+Test the closed completion loop with a harmless command:
+
+```bash
+loadout handoff codex "Verify Node" --verify "Node prints verified" \
+  --verify-command node --verify-args '["-e","console.log(\"verified\")"]'
+loadout handoff codex
+loadout handoff --done <new-task-id> --run-verification
+```
+
+Confirm the task closes with command evidence. Repeat with
+`--verify-args '["-e","process.exit(3)"]'`; approved `--done` must exit nonzero, record
+the failed attempt, and leave the task pending. No shell is used and no retry
+happens automatically. For a human-only check, omit the command and complete
+with `--evidence "what you inspected"`.
+
+To exercise a real Claude Code pickup in non-interactive print mode, grant only
+the handoff command and read access inside this disposable repository:
+
+```bash
+claude -p --allowedTools='Bash(loadout handoff *),Read' \
+  'Check loadout handoff claude-code, inspect its bundle, and complete the task with matching evidence. Do not edit files.'
+```
+
+Without that allowlist, Claude Code may read and report the task but its
+non-interactive permission gate will correctly refuse the completion command.
+Do not use a blanket permission bypass for this test. Confirm `loadout handoff`
+shows no pending task and that the fixture files remain unchanged.
+
 Next test structured coordination without running either model:
 
+```bash
+mkdir -p src/api src/web
+printf 'export interface Checkout { id: string; }\n' > src/api/types.ts
+printf 'import { Checkout } from "../api/types.js";\n' > src/web/page.ts
+loadout coord start --agents claude-code,codex
+loadout coord start --agents claude-code,codex --yes
+loadout coord detect
+loadout coord detect --publish
+loadout coord detect --publish --yes
+```
+
+The first `start` and `detect --publish` calls are previews. Confirm ownership
+contains no generated directories or redundant child paths, the candidate body
+contains the exact `Checkout` declaration, and the second detection reports the
+published contract as current. Change the declaration and confirm it becomes
+stale. Multiline declarations must be marked manual and refused by publication.
+
+Template behavior is also project-local and disposable:
+
+```bash
+loadout template list
+loadout handoff codex src/api/types.ts --template write-tests
+loadout handoff codex
+```
+
+Confirm the task says `Write tests for src/api/types.ts`, includes its template
+verification criteria, and can include bundle defaults from a custom template.
+
+The granular protocol remains available:
+
 ```bash
 loadout coord own claude-code src/api
 loadout coord own codex src/web
@@ -310,6 +380,9 @@ Confirm all of the following before publishing:
 6. `loadout coord replay` includes the discussion and the resulting decision;
 7. `git status --short` shows that neither agent edited a project file.
 
+A bounded real-provider record from the maintained release check is stored in
+[`docs/evidence/coordination-provider-check-2026-09-05.md`](./evidence/coordination-provider-check-2026-09-05.md).
+
 Repeat with known real session IDs to validate resumption:
 
 ```bash
@@ -346,7 +419,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.9.0` completed, run `hash -r`, and confirm npm's global binary
+loadout-ai@0.9.2` 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,

package/docs/evidence/coordination-provider-check-2026-09-05.md

@@ -0,0 +1,33 @@
+# Bounded provider coordination check — 2026-09-05
+
+This release check used the locally installed Claude Code 2.1.245 and the
+bundled Codex adapter. It intentionally consumed real provider quota. No source
+file was edited by either provider.
+
+## Design discussion
+
+- Thread: `prerelease-contract-validation-20260905`
+- Budget: three turns; used: three turns
+- Lifecycle: Claude proposal → Codex critique → Claude synthesis → closed
+- Decision: publish exact source declarations as a labeled convenience
+  snapshot while keeping the canonical source path and export name authoritative.
+- Persisted result: five public discussion events, including the decision,
+  rationale, alternatives, and unresolved evidence gaps.
+
+## Durable handoff pickup
+
+The test ran in a disposable repository and sent Claude Code a task with one
+bundled text fixture and manual verification criteria.
+
+- Task ID: `baeceff7`
+- Expected fixture token: `cobalt-otter-47`
+- First print-mode run: Claude recovered the task and token, but the native
+  permission gate denied the completion command.
+- Least-privilege rerun: `--allowedTools='Bash(node /absolute/path/to/loadout handoff *),Read'`
+- Result: Claude appended a `done` message resolving `baeceff7`, with passed
+  manual evidence `cobalt-otter-47`; the inbox then reported zero pending tasks.
+- Integrity check: the fixture content was unchanged.
+
+This proves the maintained build can transfer bounded source context from Codex
+to Claude Code and receive a verified completion. It does not claim hidden
+reasoning sharing, mid-turn provider injection, or universal host compatibility.

package/docs/specs/HANDOFF_CONTEXT_BUNDLES.md

@@ -0,0 +1,139 @@
+# Spec: Safe handoff context bundles
+
+## Objective
+
+Let a user attach the exact text files needed for a Claude Code ↔ Codex task so
+the receiving agent can begin from a bounded, durable snapshot instead of a
+manually written pointer. The feature must improve cold-start context without
+turning `.handoff/` into an unbounded secret or binary store.
+
+```bash
+loadout handoff codex "write auth tests" --bundle src/auth.ts src/types.ts
+```
+
+Success means the handoff message references a versioned bundle, the receiver's
+normal inbox output makes that bundle impossible to miss, and unsafe inputs fail
+before either the task or bundle is written.
+
+## Tech stack
+
+- TypeScript on Node.js 20+
+- Commander for the public CLI
+- Zod for persisted protocol validation
+- Vitest for unit and CLI tests
+- Existing coordination redaction and atomic-file helpers
+
+No new runtime dependency is permitted.
+
+## Commands
+
+```bash
+npm test -- tests/handoff-bundle.test.ts tests/handoff.test.ts
+npm run typecheck
+npm run lint
+npm run build
+npm run verify
+```
+
+## Project structure
+
+- `src/core/delegation/handoff-bundle.ts` — safe paths, bounded reads,
+  redaction, versioned persistence, and bundle inspection
+- `src/core/delegation/handoff.ts` — additive bundle reference and inbox output
+- `src/commands/catalog-workflows.ts` — `--bundle <paths...>` CLI boundary
+- `tests/handoff-bundle.test.ts` — filesystem and security behavior
+- `tests/handoff.test.ts` — message compatibility and receiver output
+- `README.md`, `docs/REFERENCE.md`, `docs/USER_TEST_GUIDE.md`, and
+  `skills/loadout-handoff/SKILL.md` — user and agent documentation
+
+## Public contract
+
+Task messages gain one optional additive field:
+
+```ts
+interface HandoffBundleReference {
+  schemaVersion: 1;
+  path: string;
+  fileCount: number;
+  storedBytes: number;
+  isTruncated: boolean;
+}
+```
+
+`path` is project-relative and always names `.handoff/bundles/<bundle-id>.json`.
+The referenced strict, versioned JSON contains records with `path`,
+`sourceBytes`, `storedBytes`, `sourceSha256`, `isTruncated`, and `content`.
+`sendHandoff` accepts an optional pre-created reference; old callers and logs
+remain valid.
+
+## Code style
+
+Use immutable values, Zod at persistence boundaries, and errors that name the
+rejected path and violated rule:
+
+```ts
+const result = handoffBundleSchema.safeParse(JSON.parse(raw));
+if (!result.success)
+  throw new Error(`Invalid handoff bundle: ${formatZodError(result.error)}`);
+```
+
+## Testing strategy
+
+- Unit tests use real temporary repositories and files.
+- Every new behavior starts as a failing test observed before implementation.
+- Cover happy path, Unicode, redaction, traversal, absolute paths, symlinks,
+  directories, binary content, per-file and total truncation, maximum file
+  count, corrupt reads, legacy compatibility, and CLI text/JSON output.
+- Run the complete project verification suite before claiming completion.
+
+## Boundaries
+
+- Always: explicit opt-in, repository-relative regular files, deterministic
+  order, secret redaction, atomic owner-only writes, strict validation, and
+  additive protocol evolution.
+- Ask first: new dependencies, changing the 50 KiB cap, automatically adding
+  bundles to Git, or executing verification commands.
+- Never: follow symlinks, leave the project, store binary files, silently omit a
+  requested path, include `.git/` or `.handoff/`, upload content, or mutate
+  source files.
+
+## Limits
+
+- Maximum files: 20
+- Maximum stored UTF-8 bytes per file: 32 KiB
+- Maximum stored UTF-8 bytes per bundle: 50 KiB
+- Larger text files are truncated on a valid UTF-8 boundary and marked.
+- Once the total limit is exhausted, remaining requested files are represented
+  with empty content and `isTruncated: true`; none disappear silently.
+
+## Security and trust model
+
+Bundle content is untrusted project data, not agent instructions. Common secret
+patterns are redacted before storage, but heuristic redaction is not a guarantee
+and users must not bundle credential files. Bundles are owner-only and are not
+automatically committed.
+
+## Success criteria
+
+- The example creates one task and one readable bundle.
+- The task JSON contains a valid additive reference.
+- Inbox output prints bundle path, file list, size, truncation warning, and an
+  untrusted-data notice without dumping all source into the terminal.
+- Unsafe files fail before a task is appended.
+- Stored content never exceeds the limits.
+- Secret fixture values are absent from persisted bundle text.
+- Old logs without `bundle` behave identically.
+- Complete repository verification passes.
+
+## Deferred work
+
+- Typed verification criteria and completion evidence
+- Bounded provider-driven retry loops
+- Handoff templates and automatic context selection
+- Cross-machine bundle publication policy
+
+These require separate contracts and are not hidden inside `--bundle`.
+
+## Open questions
+
+None for this conservative, opt-in slice.

package/docs/specs/HANDOFF_VERIFICATION.md

@@ -0,0 +1,83 @@
+# Spec: Handoff verification evidence
+
+## Objective
+
+Close the handoff reliability loop without an unbounded agent conversation or
+implicit shell execution. A sender can attach acceptance criteria and,
+optionally, an exact executable plus arguments. When the receiver explicitly
+adds `--run-verification` while completing the task, Loadout runs only that
+stored argv command from the project root. A
+passing check records bounded evidence and settles the task; a failing check
+records the attempt and leaves the task pending.
+
+```bash
+loadout handoff codex "write auth tests" \
+  --verify "the focused tests pass" \
+  --verify-command npm --verify-args '["test","--","tests/auth.test.ts"]'
+```
+
+Human-only criteria remain useful. They require an explicit completion note:
+
+```bash
+loadout handoff --done <task-id> --evidence "Reviewed the rendered states"
+```
+
+## Tech stack and structure
+
+- `src/core/delegation/handoff.ts` owns additive persisted types and schemas.
+- `src/core/delegation/handoff-verification.ts` owns no-shell command execution,
+  output bounding/redaction, and completion transitions.
+- `src/commands/catalog-workflows.ts` owns Commander validation and output.
+- Vitest unit and CLI tests use real temporary repositories; the command runner
+  is injectable for deterministic timeout/output/error cases.
+- No new dependency.
+
+## Public contract
+
+Task messages may add:
+
+```ts
+interface HandoffVerification {
+  criteria: string;
+  command?: {
+    executable: string;
+    args: string[];
+    timeoutMs: number;
+  };
+}
+```
+
+`done` and verification `status` messages may add bounded evidence with mode,
+status, command argv, exit code, duration, stdout, stderr, timeout, and
+truncation fields. Old messages remain valid.
+
+## Bounds and safety
+
+- Criteria and manual evidence: 2,000 UTF-8 characters maximum.
+- Command: one non-empty executable, at most 64 arguments and 4,096 characters
+  per argument; no shell is used.
+- Timeout: 1-900 seconds, default 120.
+- Persisted stdout and stderr: 8 KiB each after secret redaction, with a visible
+  truncation flag.
+- The command runs only with `--done <id> --run-verification`; legacy `--done`
+  alone never executes a stored command.
+- A nonzero exit, timeout, output overflow, or spawn failure never settles the
+  task.
+- There is no autonomous retry loop. The receiver fixes the work and explicitly
+  invokes `--done` again.
+
+## Success criteria
+
+- Existing sends and `--done` behave unchanged without verification.
+- `--verify-command` or `--verify-timeout` without `--verify` fails before send.
+- Human-only criteria cannot be completed without `--evidence`.
+- Commands receive literal argv with `shell: false` and run at project root.
+- Passing commands append one `done` event with redacted, bounded evidence.
+- Failing commands append a nonterminal `status` event and keep the task in the
+  receiver inbox, where the last failure is visible.
+- Full verification and coverage gates pass.
+
+## Deferred
+
+Provider-bridge retries may consume this evidence in a later feature, but must
+remain opt-in, preview their provider-turn budget, and enforce a hard round cap.