Why

The write-block increment rejects mid-merge writes with a hardcoded message string, and the only way for a client to tell "retry, this is transient" from "give up, this branch is read-only" was to string-match the error message. The E2E retry helper already did exactly this (error.message === MERGE_IN_PROGRESS_MESSAGE), which silently breaks the moment the wording changes. The new write-blocking behavior was also undocumented for both users and contributors.

Goal: give the merge write-block rejections stable, structured GraphQL error codes so clients (and the E2E suite) can branch on a code instead of a message, and document the during-merge write-blocking in the user docs and the dev knowledge base.

Non-goals: no change to the write-block behavior itself, the messages users see, or which operations are blocked (all from the prior increment); the MERGE_FAILED state and infrahub recover recovery flow are out of scope; REST endpoints keep their existing 422 wrapping.

Closes IFC-2562

What changed

Behavioral changes (API surface):

• Three branch-status rejections now carry a structured catalogue code in the GraphQL error extensions ({code, http_status, data}), in addition to the unchanged human message:
  • BRANCH_ALREADY_MERGED (HTTP 400) — write to a MERGED branch. Payload: {branch_name}.
  • BRANCH_NEEDS_REBASE (HTTP 400) — write to a NEED_REBASE branch. Payload: {branch_name}.
  • MERGE_IN_PROGRESS (HTTP 423 Locked) — write blocked by an in-progress merge, on either the branch being merged or the default branch. Payload: {branch_name, merging_branch}.
• MERGE_IN_PROGRESS is the transient/retryable signal; clients should match on the code and retry rather than treating the failure as permanent.
• The Playwright E2E mutation helper now retries on parseCatalogueError(error.extensions).code === ERROR_CODES.MERGE_IN_PROGRESS instead of comparing the message string.

Implementation notes:

• New MergeInProgressError(BranchStatusError) (HTTP 423) carrying a merging_branch attribute. Both gates in BranchStatusChecker.check_merging_status (source-branch and default-branch) and the cache-unreachable DB fallback raise it; the messages are unchanged. The default-branch DB-fallback case uses min(merging_branch_names) for a deterministic merging_branch.
• Both source-branch and default-branch blocks map to the single MERGE_IN_PROGRESS code (decision: one code for "blocked by an active merge"). A client retrying a write to the source branch self-corrects — once the merge lands the code flips to BRANCH_ALREADY_MERGED and the retry helper fails fast.
• HTTP 423 was chosen for the catalogue entry as the most precise "temporarily locked, retry later" status. It surfaces only in the GraphQL extensions.http_status.
• Drive-by fix in tasks/backend.py: export-error-catalogue built its output path from the shell-escaped repo path, so in a worktree whose path contains a . it wrote to a literal infrahub\.worktrees/... directory instead of the real one. Switched to the unescaped REPO_BASE since the path is used for a filesystem write, not a shell command.

How to review

Focus areas:

• backend/infrahub/branch/status_checker.py — the four raise-site swaps to MergeInProgressError and the merging_branch values passed on each path.
• backend/infrahub/errors/{catalogue,payloads}.py, exceptions.py, graphql/error_formatter.py — the catalogue entries, payload models, and the _build_payload match arms.
• frontend/app/tests/e2e/utils/graphql.ts — the actual consumer change (string match → code match).

Checklist

• Tests added/updated
• Changelog entry added (uv run towncrier create ...)
• External docs updated (if user-facing or ops-facing change)
• Internal .md docs updated (internal knowledge and AI code tools knowledge)
• I have reviewed AI generated content

Summary by cubic

Introduce a structured MERGE_IN_PROGRESS error and enforce merge-time write blocking on the source and default branches. Updates align with IFC-2437 by making merge state visible to clients so they can safely retry and by clarifying behavior in docs.

• New Features

  • Added MergeInProgressError (HTTP 423) with payload { branch_name, merging_branch }; raised by the status checker when merge protection is active (cache-first with DB fallback).
  • Expanded the error catalogue and GraphQL formatter with BRANCH_ALREADY_MERGED, BRANCH_NEEDS_REBASE, and MERGE_IN_PROGRESS.
  • Updated docs: merge flow now documents temporary write blocks and shows a MERGE_IN_PROGRESS example; error catalogue lists the new codes; internal knowledge base covers MERGING state and the write blocker.
  • Regenerated frontend error types and tests; e2e now matches on the MERGE_IN_PROGRESS code instead of the message.
  • Exported the updated error-catalogue.json; adjusted the export task to write to the repo base path.

• Migration

  • Update client error handling to check extensions.code === "MERGE_IN_PROGRESS" and retry after a short delay.
  • Prefer error codes over parsing messages in any existing logic.

^{Written for commit 9ff5cb3. Summary will update on new commits.}