docs(submitqueue): provider example configuration and landing runbook

[behinddwalls]

Summary

Why?

Every piece needed to land a change against a live provider was in place, but nothing said how to point the stack at one — and the pieces that vary by provider were scattered across environment variables and two config files with no worked example.

What?

Which provider a deployment targets becomes a bind-mounted directory: make local-provider-start PROVIDER=github mounts example/provider/<name>/ into the orchestrator and Runway. Because the choice is a mount rather than a build input, switching providers needs no rebuild, and adding one is a directory plus the extension implementations behind it — no compose, Makefile, or image change.

The compose overlay names no provider at all. It requires the token rather than defaulting it: falling back to the fake integrations would let the stack report a change as landed without having gone near the provider, which is a far worse failure than not starting.

example/provider/README.md carries the complete touchpoint list for adding a provider, and — more usefully — what is not on it: the merger's apply and push paths, the head-branch update, the pipeline, the wire contract, and the hermetic git E2E are all provider-independent.

The runbook covers the two first-run traps that are easy to misdiagnose. Branch protection on the target rejects the merger's push like anyone else's. And a change that lands but stays open is either a fork (expected and permanent — its head branch lives in another repository) or head-branch protection blocking the update; Runway's logs distinguish them.

Test Plan

✅ docker compose -f docker-compose.yml -f docker-compose.provider.yml config validates, and fails fast with required variable GITHUB_TOKEN is missing a value when the token is unset.

✅ make help lists land, local-provider-start, and local-provider-stop.

Landing against a live provider is manual by nature — it needs a scratch repository and a token, so it is not automated in CI. The runbook is the procedure.

Issues

[kevinlnew]

In service/submitqueue/demo/provider/github/profiles.yaml, the analyzer type is fileoverlap:

analyzer: {type: fileoverlap}

But PR #545 defines the valid types as all, none, and pathoverlap. This would fail validation at startup. Should be pathoverlap.

[kevinlnew]

In service/submitqueue/demo/provider/github/profiles.yaml, the analyzer type is fileoverlap:

analyzer: {type: fileoverlap}

But PR #545 defines the valid types as all, none, and pathoverlap. This would fail validation at startup. Should be pathoverlap.

AI review comment ^... if it works then I'm fine with it. but probably double check.

[behinddwalls]

Double-checked, and the AI comment is correct — fixed in b192addc.

fileoverlap does not exist anywhere in the tree. It was renamed in #575 (refactor(conflict)!: key path overlap by file or by directory, 910680c8), which replaced it with pathoverlap plus a by: file | directory granularity. The extension directory on main is submitqueue/extension/conflict/pathoverlap/; there is no fileoverlap package.

It would not have degraded gracefully. normalizeAndValidate in service/submitqueue/orchestrator/server/config.go switches on the type and its default: arm returns unknown analyzer type %q, so this profile fails at config load — the orchestrator would not have started. Confirmed that branch already carries the post-#575 loader (analyzerTypePathOverlap at config.go:44), so the value really is invalid here rather than just being from a newer revision.

Fixed as {type: pathoverlap, by: file}. by: file is the default and the pre-#575 behaviour, so this preserves what the comment describes; I made it explicit because this file is an example people copy from, and extended the comment to mention the directory granularity #575 added.

Verified the file still parses and needs no reformatting under make fmt, and //service/submitqueue/orchestrator/server:go_default_test passes (it covers pathoverlap defaulting to file and rejecting an unknown granularity).

Worth flagging separately: nothing tests that the shipped example configs actually load, which is why this got through. Happy to add that as a follow-up if you want it.

[behinddwalls]

Updated to by: directory in 09eab168 (amended onto the previous fix, so this PR keeps one commit).

Note the value is spelled directory, not folder — pathOverlapByDirectory = "directory" in orchestrator/server/config.go:50, and an unrecognised granularity is rejected the same way an unrecognised type is (unknown pathoverlap granularity %q).

Semantics, for the record: ByDirectory is path.Dir(p), so it keys on the immediate parent directory only — not any shared ancestor — and files at the repository root all share the key ".". It is strictly coarser than by-file: every file overlap is also a directory overlap. For the demo, which spreads each change over a sharded file tree, that gives the queue real dependency chains to show while changes in different folders still land in parallel.