docs(rfc): merge-request Layer 1 - command group RFC (DMD-1900)

[martinsifra]

RFC for the kbagent merge-request command group (Layer 1), over MergeRequestService from
#703 (Layer 2, DMD-1899).

Docs only — no code. Stacked on ms/dmd-1899/cli-layer-2, so the diff is one file:
docs/merge-requests-layer1.md. Retarget to main once #703 merges.

What it decides

Layer 2 settles most of the surface — eleven service methods map to eleven commands with no
invention. This RFC decides what Layer 2 deliberately left to the caller:

Group	merge-request + hidden mr alias, _DEV panel after branch
Files	commands/merge_request.py + commands/_merge_request_render.py (split up front — 11 commands + 4 non-trivial renderers vs. the 800-line soft ceiling; output.py is already at 1013/1000)
Target	--mr-id optional everywhere: --mr-id → resolve_branch() → find_merge_request_for_branch(). merge is not exempt
merge risk	destructive — --deny-destructive lets an agent run the whole flow and hands only the last step to a human
merge wait	no --wait/--timeout in v1 (L3 always awaits, 600 s; a flag would mean re-reviewing L2+L3)
resolve --all	no — rebase replaces; conflicts are meant to be walked, not waved away
serve	full router ships with the commands, plus a serve-only by-branch route
branch merge	deprecate-with-pointer, conditional — it works on projects without the feature, so it is not a 1:1 replacement

Facts the analysis surfaced

These shape the implementation and would otherwise be discovered at coding time:

• The MR serializer emits no timestamps. No Created/Updated column is possible; the
  list arrives server-side createdAt DESC, so the renderer must preserve that order — it is
  the only chronological signal that survives.
• FeatureNotEnabledError gets flattened by the house idiom. It is a ConfigError
  subclass carrying FEATURE_NOT_ENABLED; except ConfigError → error_code=CONFIG_ERROR
  (and the shared _handle_config_service_error) throws that away, leaving a --json
  consumer unable to tell "merge requests are not enabled" from a bad alias.
• An empty --reviewer-id list clears the reviewer set. _optional_mr_fields sends
  reviewerIds whenever it is not None, so a Typer option yielding () silently wipes
  reviewers on any update that did not mention them. Must be normalised to None.
• A scoped Storage token 403s on detail/conflicts/diff/resolve but list works —
  the list action has no voter.
• approve answers 422 in every state on a 0-approval project (its only from place,
  in_review, is unreachable because request_review is auto-finished). Neither it nor
  request-review has a happy path to assert. Same root cause means there is no close
  command: creator-request-changes is the UI's cancel but leaves state=development, so a
  close command would look like a no-op.

Open

E2E is not settled by this RFC and is marked as such. No project carries
branches-merge-requests, kbagent cannot provision one (ManageClient has no project create,
and Connection's suite makes its own), and the happy path necessarily merges into production.
The RFC records the proposed path — enable the feature on the existing E2E project via
kbagent feature project-add, gate with a FEATURE_NOT_ENABLED skip meanwhile — plus two
properties worth knowing: the merge writes to production (explicit teardown required) and
merge takes a project-wide lock, so concurrent runs collide.

🤖 Generated with Claude Code

[linear-code]

DMD-1900