agent-merge-broker 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 0.13.0 — 2026-09-04
+
+### Added
+
+- Added validation-only Gate intake for trusted Git refs already present in the broker repository.
+  `candidate authority setup` first records a versioned protected-target trust root at a fixed path
+  in Git's common directory; `candidate adopt --ref` then pins the exact commit, derives its
+  base-relative history and paths, loads committed policy from the registered base, and records a
+  standalone, schema-backed submission without manufacturing tasks, leases, receipts, or batches.
+- Added `candidate list` and `candidate show`, plus recovery of interrupted `received` and
+  `validating` submissions.
+
+### Changed
+
+- Validator environments now expose `MERGE_BROKER_SUBMISSION_ID` during trusted local-ref intake.
+- Validators now receive an owner-readable UTF-8 JSON path list through
+  `MERGE_BROKER_FILES_FILE`, `MERGE_BROKER_FILES_FILE_FORMAT=json`, and shell-safe `{filesFile}`.
+  Inline input remains the compatibility default but fails closed when either legacy representation
+  exceeds 4 KiB; `filesInput: "json"` explicitly selects file-only transport for large path sets.
+- Gate requires Git 2.46 or newer, binds protected-base refresh to the canonical fetch URL (separate
+  from any publication `pushurl`), rejects and scrubs Git repository/index/object/history and
+  configuration-injection or transport-command overrides, refuses configured URL/transport
+  rewrites, proxy/TLS/routing overrides, and exact-locator remote shorthand collisions, physically
+  binds local transport paths, rejects URL forms whose Git and web interpretations differ,
+  recursively inspects the owned object store, recomputes commit/tree/blob identities,
+  applies documented aggregate diff/tree/path ceilings, materializes raw filter-free blob bytes,
+  binds state/worktree/cache/hook directories to physical filesystem identities, journals retained-ref
+  establishment and later loss, bounds untracked-path diagnostics, and serializes authority
+  replacement against adoption and recovery.
+
+### Fixed
+
+- Kept exact-target checks compatible with Git for Windows' standard unscoped Schannel TLS backend,
+  and made lock release retry transient Windows sharing violations without weakening nonce fencing.
+
+## 0.12.1 — 2026-09-04
+
+### Added
+
+- Added a truthful product vision and capability-based roadmap that distinguish today's Coordinate
+  mode from planned external-candidate Gate and generalized Verify modes.
+
+### Changed
+
+- Reframed the README, package metadata, and website around crash-recoverable exact-candidate
+  repository transactions while preserving the current package, CLI, and project identities.
+- Expanded the architecture, protocol, security, compatibility, and operations documentation to
+  cover v0.12 locks, durable intents, reconciliation, topology proofs, adapter obligations, upgrade
+  boundaries, and actionable error recovery.
+
+### Fixed
+
+- Aligned the published configuration schema with runtime support for declaring auto-merge while
+  publication remains disabled, while continuing to reject branch-mode and draft auto-merge.
+- Made the documentation site redeploy for every canonical content source and replaced its
+  inaccurate source-declaration test count with the supported cross-platform CI matrix.
+- Replaced a historical but copyable nonexistent `verify@v1` reference with an existing immutable
+  action tag.
+- Made abandoned-integration cleanup replayable across another process stop, use the persisted
+  branch name and expected SHA, remove partial worktree directories, and preserve branches checked
+  out for operator inspection.
+- Made JSON CLI usage errors follow the documented machine-readable error envelope and made
+  `serve --once --json` return exactly one summary document.
+- Made human refresh output distinguish an already-current batch, terminal reconciliation, and a
+  pull request that a reviewer had already closed.
+
 ## 0.12.0 — 2026-09-04
 
 ### Added
@@ -28,7 +94,8 @@
 - Merge reconciliation proves the accepted fast-forward, squash, two-parent merge, or linear rebase
   topology before releasing dependent tasks.
 - Revocation, reviewer closure, force-push, reopened pull request, remote retargeting, and
-  configuration-downgrade races now fail closed without leaving a possibly-live merge queue behind.
+  configuration-downgrade races now fail closed without leaving a possibly-live auto-merge request
+  behind.
 
 ### Fixed
 
@@ -332,7 +399,7 @@ not have to rebuild them.
   already contain. Verification policy is read from the configuration committed on the base branch,
   never from the change under review.
 - A composite GitHub Action at `verify/action.yml`, so requiring the gate is two lines:
-  `uses: WeSpitfire/agent-merge-broker/verify@v1`.
+  `uses: WeSpitfire/agent-merge-broker/verify@v0.3.0`.
 - `merge-broker task submit --since-base` submits the linear commits made after the base the broker
   handed out. Commits whose change is already upstream are skipped by patch identity, so a rebased
   branch does not resubmit landed work.

package/README.md

@@ -1,18 +1,61 @@
 # Agent Merge Broker
 
-**Four agents just finished at the same time. Who merges first?**
+**Crash-recoverable repository transactions for code-producing agents and humans.**
 
-Agent Merge Broker answers that so your agents never have to. Workers commit their work and stop. The broker decides what can safely go together, cherry-picks it into a disposable worktree, runs your test suite against the combination, and lands one validated branch or pull request.
+Many producers can create code. The repository still needs one contract for deciding what is safe to
+validate, publish, and merge. Agent Merge Broker is a local-first transaction coordinator for that
+boundary: participating workers submit receipts naming immutable commits, while Gate intake can
+submit one retained trusted-local Git ref for validation without fabricated coordination history.
+The complete Coordinate path derives one batch candidate and keeps
+publication bound to the recorded Git and forge target.
 
-No agent pushes. No agent rebases. No agent quietly clobbers another agent's `package-lock.json`.
+In Coordinate mode, exact-candidate approval ties evidence and authorization to the candidate SHA,
+base SHA, and policy revision. Durable operation state lets the broker reconcile a crash or lost
+forge response before it releases dependent work.
 
-## The problem
+It does not spawn agents, decide policy with AI, or replace CI, review, protected branches, or a
+native forge queue. The forge remains the final branch authority.
 
-Put four coding agents on one repository and the bottleneck stops being code. It becomes Git.
+## What ships today
 
-Two agents edit the same file and find out at merge time. A third rebases onto a branch that moved twenty minutes ago. Everyone regenerates the lockfile. CI runs four times to test four things that were never once tested *together*. And the pull request that has been sitting there since lunch is now so far behind `main` that nothing can merge it at all.
+### Coordinate mode
 
-The work is parallel. Integration is not. Every worker doing its own integration turns a coordination problem into a coordination disaster.
+The current workflow coordinates workers that participate through the broker's claim and receipt
+protocol:
+
+```text
+claim → lease → commit → nominate → batch → validate → publish → reconcile
+```
+
+- Expiring, cross-worktree leases prevent predictable collisions before editing.
+- Commit receipts separate implementation from integration authority.
+- A deterministic conflict/dependency scheduler forms bounded batches.
+- Every batch is tested through real cherry-picks in a disposable worktree.
+- Focused checks run after each task; the complete gate runs either in the broker or as required CI.
+- Successful work becomes one local branch, remote branch, or GitHub pull request.
+- Optional exact-candidate policy separates nomination, verification, approval, and mechanical merge.
+- Published branches can carry a signed provenance manifest for remote policy checks.
+- Target fingerprints, durable intents, and forge observation make interrupted publication recoverable.
+- Automatic completion waits until the accepted Git history proves that the batch merged.
+
+### Gate intake for trusted local refs
+
+Version `0.13.0` adds a first Gate slice for a Git ref whose objects are already available in the
+broker's local repository. An explicit `candidate authority setup` ceremony records the reviewed
+protected-target locator outside candidate commits. `candidate adopt` then resolves and retains the
+exact commit, independently resolves that registered base, loads committed policy from the base,
+derives the raw commit chain and changed paths, and runs focused plus authoritative broker validators
+over filter-free materialized bytes. The resulting `SubmissionRecord` is validation evidence only:
+this slice does not create a task, lease, receipt, batch, approval candidate, provenance statement,
+branch, pull request, or merge authority.
+
+### A concrete coordination problem
+
+Four coding agents finish at once. Two touched the same file, a third started from a base that has
+already moved, and each produced a lockfile. Testing four branches independently never proves that
+their combined result works. Coordinate mode orders that work, rejects overlapping claims early,
+validates compatible commits together, and retains one candidate without giving workers merge
+authority.
 
 ## Try it in one minute
 
@@ -25,39 +68,61 @@ Two workers race on a throwaway repository, a third gets turned away for claimin
 
 It is also this project's acceptance test in CI — so if the demo ever stops telling the truth, the build goes red.
 
-## How it works
-
-One integration authority; implementation stays distributed:
-
-- Expiring, cross-worktree leases prevent predictable collisions before editing.
-- Commit receipts separate implementation from integration authority.
-- A deterministic conflict/dependency scheduler forms bounded batches.
-- Every batch is tested through real cherry-picks in a disposable worktree.
-- Focused checks run after each task; the complete gate runs either in the broker or as required CI.
-- Successful work becomes one local branch, remote branch, or GitHub pull request.
-- Optional exact-candidate policy separates nomination, verification, approval, and mechanical merge.
-- Published branches can carry a committed provenance manifest for fast remote policy checks.
-- Tasks are dependency-complete only after their batch is actually merged.
-- An append-only audit stream records lifecycle decisions and validation results.
+## How Coordinate mode works
 
-It is deliberately **not** an agent framework and **not** a replacement for protected branches. Codex, Claude, Cursor, custom agents, CI jobs, and humans all speak the same small commit-receipt protocol, and your forge keeps the final say on what merges.
+Implementation stays distributed while one broker owns ordering, batching, validation, publication,
+and recovery. Codex, Claude, Cursor, custom agents, CI jobs, and humans can use the same small
+commit-receipt protocol. An append-only audit stream records lifecycle decisions and validation
+results, while the forge keeps the final say on what merges.
 
 ## Status
 
 `0.3.0` was the first public release: the local broker core, the GitHub CLI publishing adapter with auto-merge, and the remote provenance verifier.
 
-`0.12.0` is the current release. It makes pull-request auto-merge crash-recoverable and
-target-bound, adds unattended publication and stale-base recovery, and closes approval, refresh,
-revision, remote-retargeting, and reopened-pull-request races. It also retains the first-class
-Windows support, permission-separated MCP servers, diagnostics, and bootstrap detection added in
-`0.11.0`.
+`0.13.0` is the current release. It adds validation-only Gate intake for trusted repository-local
+Git refs, with an explicit protected-target authority, exact retained artifact identity,
+filter-free validation, and crash-safe recovery. It builds on the `0.12.1` documentation and
+machine-readable CLI consolidation around the `0.12.0` core. That core made
+pull-request auto-merge crash-recoverable and target-bound, added unattended publication and
+stale-base recovery, and closed approval, refresh, revision, remote-retargeting, and reopened-PR
+races, while retaining the first-class Windows support, permission-separated MCP servers,
+diagnostics, and bootstrap detection added in `0.11.0`.
+
+The on-disk state, receipt, submission, candidate, and provenance formats are versioned, but
+compatibility is not guaranteed until `1.0.0`. Expect format migrations before then.
+
+## Product direction
+
+Coordinate mode remains the complete repository-transaction workflow in `0.13.0`. The release also
+ships a deliberately narrower local-ref Gate validation intake; Gate merge authority and Verify mode
+remain planned.
+
+### Gate mode — validation intake in 0.13.0
+
+`merge-broker candidate adopt --ref <git-ref>` accepts a completed candidate from a producer that did
+not use path leases while coding. Before adoption, an operator must run `candidate authority setup`
+from a reviewed protected checkout. This first slice is trusted-source and validation-only. The ref
+must already be available in the local repository, descend linearly from the registered base, and fit
+both `scheduling.maxCommits` and Gate's 1,000-commit hard ceiling; the protected base must contain
+matching committed broker policy with
+`validation.authority: "broker"`. Approval, provenance, publication, merge reconciliation,
+pull-request intake, bundles, and remote submission for these records are not implemented yet.
 
-The on-disk state, receipt, and provenance formats are versioned, but compatibility is not guaranteed until `1.0.0`. Expect format migrations before then.
+### Verify mode — planned
+
+Verify mode will be a lightweight admission check for policy and attestations produced through a
+wider set of workflows. Today's `verify-provenance` command is intentionally narrower: it verifies
+provenance created by the current broker workflow, not arbitrary external candidates.
+
+See [Vision](VISION.md) for the durable product boundary and
+[Roadmap](ROADMAP.md) for the capability-based sequence. Planned work is labeled explicitly and
+is not part of npm until a release says otherwise.
 
 ## Requirements
 
 - Node.js 20.12 or newer
 - Git 2.31 or newer with worktree support
+- Git 2.46 or newer specifically for trusted local-ref Gate intake
 - GitHub CLI only when `publish.mode` is `pull-request`
 
 Windows, macOS, and Linux are supported and release-gating in CI. Windows validation defaults to
@@ -99,9 +164,10 @@ and owner-written `AGENTS.md` content. Use `--no-detect` or `--no-agent-contract
 installer or repository template owns those concerns itself.
 
 It also creates an Ed25519 provenance private key, mode `0600`, under Git's common runtime directory.
-Only its public key is written to the committed configuration. Runtime state, receipt records,
-manifests, keys, locks, and integration worktrees therefore stay outside commits while every linked
-worktree sees the same broker authority.
+Only its public key is written to the committed configuration. Runtime state, receipt, batch, and
+Gate submission records, keys, locks, and disposable worktrees therefore stay outside commits while
+every linked worktree sees the same broker authority. When provenance is enabled, a separate signed
+or unsigned provenance manifest is deliberately committed as a Coordinate-mode branch head.
 
 ## Quick start
 
@@ -116,9 +182,9 @@ git add .merge-broker AGENTS.md && git commit -m 'Configure authenticated merge
 merge-broker doctor
 ```
 
-`merge-broker status` now includes the safe next command for each active task and batch. For a bug
-report, `merge-broker doctor --support-bundle` emits diagnostics and recent audit events with paths,
-URLs, and secret-bearing fields redacted; review the JSON before sharing it.
+`merge-broker status` includes the safe next command for each active task, batch, and retained Gate
+submission. For a bug report, `merge-broker doctor --support-bundle` emits diagnostics and recent
+audit events with paths, URLs, and secret-bearing fields redacted; review the JSON before sharing it.
 
 An orchestrator or worker claims a narrowly scoped task:
 
@@ -139,16 +205,17 @@ merge-broker task heartbeat CRM-142
 Pass `--token`, `--token-file`, or `MERGE_BROKER_TOKEN` when the worker runs somewhere else, or
 claim with `--no-store-token` to handle custody yourself.
 
-Before handing anything over, the worker can check its own work against the same validators
-integration will run:
+Before handing anything over, the worker can run a local preflight using the same validator
+definitions integration will use:
 
 ```bash
 merge-broker validate
 ```
 
-This is the answer integration would give, not an approximation of it, because it reads the same
-`validation` configuration. It includes uncommitted and untracked files, writes no state, needs no
-lease, and exits non-zero when a validator fails — so a worker script can gate on it.
+This checks the caller's current working tree, including uncommitted and untracked files, writes no
+state, needs no lease, and exits non-zero when a validator fails. It does not reproduce integration's
+per-task focused sequencing or its unchanged-`HEAD` and clean-worktree postconditions, so the retained
+integration transaction remains authoritative.
 
 The worker commits its change and nominates a candidate receipt. It does not merge or push:
 
@@ -179,7 +246,57 @@ merge-broker integrate --publish
 merge-broker batch sync <batch-id>
 ```
 
-`batch sync` checks the GitHub PR when available. For branch-only publication it fetches the configured base and verifies ancestry. `batch complete` exists as an explicit manual escape hatch for squash/rebase workflows that cannot be reconciled automatically.
+`batch sync` checks the GitHub PR when available. For branch-only publication it fetches the batch's
+fingerprint-bound recorded target and verifies exact-head ancestry. GitHub fast-forward, squash,
+two-parent merge, and linear-rebase outcomes are reconciled automatically when their topology can be
+proved. `batch complete` remains an explicit manual authority fallback for workflows that expose no
+sufficient automatic proof.
+
+## Validate a trusted local Git candidate
+
+When another trusted local workflow has already assembled a linear candidate, retain and validate
+its exact commit without manufacturing Coordinate-mode history:
+
+```bash
+merge-broker candidate authority setup
+merge-broker candidate authority show
+merge-broker candidate adopt --ref refs/heads/external-candidate
+merge-broker candidate list
+merge-broker candidate show <submission-id>
+```
+
+Run setup from a reviewed protected checkout after committing `.merge-broker/config.json`. The
+config-independent record binds the base locator, refresh behavior, state directory, and, when
+available, the canonical fetch-URL fingerprint without storing the URL. A changed target requires
+explicit `--replace`. There is intentionally no caller-supplied `--base` or path list. Adoption
+rejects an empty, unrelated, merged-history, or over-limit candidate (the smaller of
+`scheduling.maxCommits` and Gate's 1,000-commit ceiling) and currently requires
+`validation.authority: "broker"`. It pins the resolved commit under
+`refs/merge-broker/adopted/<submission-id>`, derives raw paths and history, materializes filter-free
+blob bytes in a disposable worktree, recomputes retained commit/tree/blob IDs, and verifies the
+retained identity after validation. It durably records successful ref establishment before any
+validator and journals any later ref loss before create-only repair, so recovery cannot forget a
+retention violation. If a
+validator rejects the candidate and the final artifact identity remains provable, the durable record
+and results are returned but the command exits nonzero. An irreproducible object identity or
+wrong/symbolic retained ref stays `validating` for fail-closed recovery instead of producing an
+unretained terminal claim.
+
+When refresh is enabled and the configured ref denotes the base branch, setup requires a configured
+fetch URL and will not fall back to a stale local ref. Set `integration.refreshBase` to false for an
+intentionally offline/local Gate target.
+
+Gate also rejects ambient or protected-validator Git repository/index/object/history and
+configuration-injection or transport-command overrides, rejects configured URL/transport rewrites
+and exact-locator remote shorthand collisions, recursively inspects the repository-owned object store, binds the
+disposable worktree's Git administration identity, and bounds its untracked-path diagnostic. See
+[Compatibility and current limits](docs/COMPATIBILITY.md) for the exact deny-list and ceilings.
+
+This is not an integration shortcut. A `validated` submission is not approved, published,
+provenanced, or authorized to merge, and cannot be passed to `batch publish`. Use Coordinate mode
+for the current end-to-end merge workflow. If adoption is interrupted after its durable record is
+written, `merge-broker recover` replays `received` or `validating` submissions from the retained
+identity.
 
 ## See it work
 
@@ -234,7 +351,7 @@ installing dependencies:
   with:
     ref: ${{ github.event.pull_request.head.sha }}
     fetch-depth: 0
-- uses: WeSpitfire/agent-merge-broker/verify@v0.12.0
+- uses: WeSpitfire/agent-merge-broker/verify@v0.13.0
 ```
 
 The check verifies the Ed25519 signature, branch and batch identity, real base history, one-file
@@ -300,11 +417,12 @@ to be current. Approval also rechecks the open PR head, target base, task state,
 and configured GitHub checks. Approval becomes merge-authorizing only after it is durable and the
 broker observes that exact PR still open; the final `gh pr merge` uses GitHub's head-SHA guard.
 
-Protect the target branch with either “require branches to be up to date before merging” or a merge
-queue, and restrict bypass permission. GitHub's merge API can guard the head SHA but cannot
-atomically guard a base SHA. The broker rechecks the base immediately before queueing and proves the
-merged Git history afterward, but branch protection prevents an out-of-band base update in that
-final remote interval.
+Protect the target branch with “require branches to be up to date before merging” and restrict
+bypass permission. GitHub's merge API can guard the head SHA but cannot atomically guard a base SHA.
+The broker rechecks the base immediately before queueing and proves the merged Git history afterward,
+while branch protection prevents an out-of-band base update in that final remote interval. Native
+merge-queue and `merge_group` verification are planned; the current topology proof does not treat a
+combined merge-group artifact as the authorized candidate.
 
 If verification finds a problem, keep the task and PR:
 
@@ -331,11 +449,13 @@ Two configuration combinations cannot work and are rejected at load time rather
 
 Auto-merge requires the setting to be enabled on the GitHub repository. Configurations written before this feature existed default to `autoMerge: false`, so upgrading never starts landing work on its own.
 
-The broker resolves and records the exact Git push URL locator and GitHub `HOST/OWNER/REPO` when it
-assembles a batch. Later changes to the named Git remote or to `gh repo set-default` cannot redirect
-publication. Standard GitHub and GitHub Enterprise remote URLs are derived automatically. If the
-Git remote is a local mirror or proxy, set `publish.repository` explicitly; otherwise pull-request
-mode fails closed rather than guessing a GitHub repository.
+The broker records the selected Git remote and a SHA-256 fingerprint of its canonical push URL when
+it assembles a publishable batch; the raw URL is not persisted because it may contain credentials.
+Pull-request batches also record a host-qualified GitHub `HOST/OWNER/REPO`. Later changes to the
+named remote or to `gh repo set-default` cannot redirect publication. Standard GitHub and GitHub
+Enterprise remote URLs are derived automatically. If the Git remote is a local mirror or proxy, set
+`publish.repository` explicitly; otherwise pull-request mode fails closed rather than guessing a
+GitHub repository.
 
 Running `merge-broker serve --publish` reconciles checks, finishes interrupted publication or
 auto-merge hand-offs, re-cuts stale batches, and only then integrates the next batch. With exact
@@ -365,10 +485,12 @@ deliberately instead.
 `integrate --dry-run` is a rehearsal in both directions: it retains no branch when it succeeds, and
 returns every task to the queue when it fails, so verifying costs nothing.
 
-Only one batch is in flight at a time. A batch is cut from the base branch tip so it is born
-mergeable, and cutting a second while the first is still open makes that expire — whichever merges
-first leaves the other behind a base that requires branches to be up to date. `integrate` refuses
-with `BATCH_OUTSTANDING` and names the batch to land first; `--force` overrides it.
+Only one batch is in flight at a time. In the default production shape—`baseRef` identifies the
+remote target and `integration.refreshBase` is enabled—a batch is cut from the fetched base-branch
+tip so it is born mergeable. A deliberately different `baseRef`, or disabling refresh, uses the
+configured construction revision instead. Cutting a second batch while the first is still open can
+leave either one stale, so `integrate` refuses with `BATCH_OUTSTANDING` and names the batch to land
+first; `--force` overrides it.
 
 When a batch does end up behind — something landed on the base by another route, or `--force` was
 used — re-cut it:
@@ -377,9 +499,10 @@ used — re-cut it:
 merge-broker batch refresh <batch-id>
 ```
 
-That closes the superseded pull request, returns the tasks to the queue without spending their retry
-budget, and integrates them again from the current tip, re-validating against the base that is
-actually being merged into. A batch already cut from the current tip is left alone.
+For PR publication, that closes the superseded pull request; branch-only publication has no PR to
+close. It returns the tasks to the queue without spending their retry budget and integrates them
+again from the current recorded target tip, re-validating against the base that is actually being
+merged into. A batch already cut from that tip is left alone.
 
 Publication is safe to retry. The pull request is recorded before auto-merge is attempted, and a
 durable intent is recorded before the remote queue is changed. A forge that fails halfway therefore
@@ -390,12 +513,13 @@ create anything new.
 
 A process that dies mid-integration can leave both a lock and durable `running` state. A holder on
 this machine is reclaimed automatically once its process is proven gone. A holder on another machine
-cannot be probed and is never stolen merely because it is old; after confirming that process is
-gone, inspect or release it explicitly with `unlock batch:<batch-id> --force` (or `state` /
-`integration`). Once the integration lock is safely acquired, `serve` and `integrate` automatically
-mark abandoned work failed, clean its broker-owned worktree and branch, and return its tasks to
-`submitted` without spending their attempt budget. `merge-broker recover` performs that
-reconciliation explicitly.
+cannot be probed and is never stolen merely because it is old. Inspect the locks with `doctor`; for
+an abandoned `running` integration, confirm the old authority is gone and release
+`unlock integration --force` (and `state` or `gate-authority` only if `doctor` shows it held). Dynamic
+`batch:<batch-id>` locks apply to interrupted operations after integration. Once the integration lock
+is safely acquired, `serve` and `integrate` automatically mark abandoned work failed, clean its
+broker-owned worktree and branch, and return its tasks to `submitted` without spending their attempt
+budget. `merge-broker recover` performs that reconciliation explicitly.
 
 Candidate revisions also carry a durable intent before the broker moves their branch. If a process
 stops after the branch update but before state finalization, `recover` compares the real PR/local
@@ -497,22 +621,32 @@ while broker credentials stay out of repository-defined commands.
 Validators receive these environment variables:
 
 - `MERGE_BROKER_TASK_ID`
-- `MERGE_BROKER_FILES`, newline-separated
+- `MERGE_BROKER_FILES_FILE`, the path to an owner-readable UTF-8 JSON array of validator-relative paths
+- `MERGE_BROKER_FILES_FILE_FORMAT=json`
+- `MERGE_BROKER_FILES`, the newline-separated form for the default `filesInput: "inline"`; empty in JSON mode
 - `MERGE_BROKER_BASE_SHA`
 - `MERGE_BROKER_HEAD_SHA`
 - `MERGE_BROKER_BATCH_ID`
+- `MERGE_BROKER_SUBMISSION_ID`, nonempty only for trusted local-ref adoption
 - `MERGE_BROKER_CACHE_DIR`, an isolated cache shared by validators in one integration transaction
 
-Commands may also use the shell-safe placeholders `{taskId}`, `{files}`, and
-`{validatorCacheDir}` (a stable validator-specific directory inside the transaction cache). `workingDirectory` can
-place a validator in a repository-relative package directory; file placeholders and environment
-paths are then relative to that directory. Validator output is captured with a fixed memory bound
-and retained in state with that cap. A timeout terminates the validator process tree.
-
-`merge-broker validate` runs these same broker-side validators against a working tree, so a worker
-can get the local integration answer before submitting rather than a weaker approximation of it. It reports
-`MERGE_BROKER_BATCH_ID=local`, which a validator can branch on if it needs to behave differently
-outside a batch.
+Commands may also use the shell-safe placeholders `{taskId}`, `{filesFile}`, `{files}`, and
+`{validatorCacheDir}` (a stable validator-specific directory inside the transaction cache).
+`{filesFile}` expands to `MERGE_BROKER_FILES_FILE`. Validators default to `filesInput: "inline"`,
+which supplies both the shell-quoted `{files}` arguments and newline `MERGE_BROKER_FILES` only when
+both representations fit within 4 KiB. If either is larger, validation fails closed with
+`VALIDATION_FAILED` before the validator starts, even when its command does not contain `{files}`.
+For potentially large path sets, set `filesInput: "json"` and parse the UTF-8 JSON array through
+`{filesFile}` or `MERGE_BROKER_FILES_FILE`; JSON mode leaves `MERGE_BROKER_FILES` empty and rejects a
+command that still contains `{files}`.
+`workingDirectory` can place a validator in a repository-relative package directory; paths in every
+file-list form are then relative to that directory. Validator output is captured with a fixed memory
+bound and retained in state with that cap. A timeout terminates the validator process tree.
+
+`merge-broker validate` is a preflight that runs the same broker-side validator definitions against
+the caller's working tree. It does not reproduce per-task focused sequencing or integration's
+post-validator candidate-preservation checks. It reports `MERGE_BROKER_BATCH_ID=local`, which a
+validator can branch on if it needs to behave differently outside a batch.
 
 A validator may set `"executionArchitecture": "native"` to run under the hardware architecture on
 macOS when Node itself is translated by Rosetta. Detected SwiftPM validators use this mode and put
@@ -520,7 +654,8 @@ their scratch build under `{validatorCacheDir}`, preventing Intel and Apple Sili
 from contaminating each other without rebuilding between the focused and authoritative stages of
 the same integration transaction.
 
-The JSON schemas in [`schemas/`](schemas/) can be used by editors, adapters, and independent receipt producers.
+The JSON schemas in [`schemas/`](schemas/) cover configuration, task receipts, exact approval
+candidates, batch provenance, and Gate authority/submission records.
 
 ### One authoritative CI pass
 
@@ -564,6 +699,11 @@ merge-broker install-hooks [--force] [--uninstall] [--print]
 merge-broker install-service [--uninstall] [--interval <seconds>] [--no-eager]
 merge-broker verify-provenance --branch <ref> --head <sha> --base <sha>
 merge-broker validate [--task <id>] [--scope focused|authoritative|all] [--base <ref>] [--cwd <path>]
+merge-broker candidate authority setup [--replace]
+merge-broker candidate authority show
+merge-broker candidate list
+merge-broker candidate adopt --ref <revision>
+merge-broker candidate show <submission-id>
 merge-broker task register|claim|extend|heartbeat|candidate|submit|reopen|revise|retry|release|cancel|abandon|show
 merge-broker status
 merge-broker plan
@@ -573,7 +713,7 @@ merge-broker audit
 merge-broker metrics
 merge-broker events
 merge-broker prune [--older-than <days>] [--dry-run]
-merge-broker unlock [state|integration|batch:<batch-id>] [--force]
+merge-broker unlock [state|integration|gate-authority|batch:<batch-id>] [--force]
 merge-broker recover
 merge-broker serve [--publish] [--eager] [--log-file <path>]
 merge-broker-mcp -C <directory> [--profile worker|operator]
@@ -600,6 +740,8 @@ resolve conflicts automatically. The complete supported/unsupported boundary is
 
 ## Documentation
 
+- [`VISION.md`](VISION.md) — durable product boundary and design principles
+- [`ROADMAP.md`](ROADMAP.md) — current, next, and later capability horizons
 - [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) — installation and production rollout
 - [`docs/COMPATIBILITY.md`](docs/COMPATIBILITY.md) — platform matrix, Windows notes, and current limits
 - [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — invariants, state model, scheduling, and transactions