feat(mcp): add manage_adr mode='set_sections' and splice ADR sections instead of rebuilding

[DeusData]

Adds manage_adr mode='set_sections' — a retry-safe way to update named ADR sections — and fixes the document-rewriting it exposed. Distilled from #1243 with Co-authored-by: credit to @andis777, whose analysis and tests this builds on.

Why sections rather than append

#1243 proposed whole-document append. It is non-idempotent on client retry: a lost response means a silently duplicated chunk. Section updates are retry-safe by construction — the same request twice produces the same document.

The design that matters: splice, don't re-render

The first implementation merged by parsing the ADR, applying updates to the model, and re-rendering. That silently destroyed content, because parse → render is lossy today:

document shape	old behaviour
preamble before the first heading	dropped entirely
## Purpose (wrong case)	not a heading → whole block deleted
## CUSTOM in prose	absorbed into the section above
fenced ```md / ## Example	absorbed
sections out of canonical order	silently reordered
multi-blank separator runs, trailing newline	collapsed / trimmed

An ADR beginning ## Purpose instead of ## PURPOSE — an ordinary typo — would have lost that entire section on the first set_sections call. mode='update' never had this exposure because it writes the caller's bytes verbatim; the merge introduced it.

So the merge no longer rebuilds anything. cbm_adr_splice_section locates the target heading's byte span and replaces only that span, appending a block when the heading is absent. Nothing outside the span is reconstructed, so untouched bytes are byte-identical by construction rather than by care. Every row in that table is now a regression test asserting the exact expected document.

cbm_adr_parse_sections is untouched and TEST(adr_parse_sections_non_canonical) passes unchanged — documents parse exactly as they did. That test was the tripwire: wanting to edit it would have meant the design had drifted back toward re-rendering.

Arbitrary headings now work

Custom headings are real sections, which is what the original request needed. ## DECISIONS is simply a span to locate or a block to append — no format migration, because stored ADRs are never rewritten wholesale.

• Exact case matching: ## Purpose and ## PURPOSE are independently targetable in one document. Case-folding would silently merge two blocks a user deliberately kept apart.
• Canonical sections become conventional, not privileged — still the documented default set, but no ordering privilege and no required-presence. cbm_adr_validate_section_keys now rejects only names that cannot round-trip (empty, #-leading, newline-bearing, edge-whitespace, over-long).

The fence locator, made refusable rather than destructive

A ## inside a fenced block is a code sample, not a heading — pinned by test. An unterminated fence hides every heading after it, so a write would append a duplicate instead of replacing: that is refused with write_error naming the open fence, leaving the document byte-identical, and mode='sections' reports unterminated_code_fence rather than answering with a quietly partial list.

One scanner, not two

mode='sections' previously used a different classifier from the store parser, so users were told ## CUSTOM was a section while the store treated it as body text. adr_list_sections_from_content now calls the same cbm_adr_scan_headings the splice locates with, and a test pins that they agree — listing exactly the real headings on a document containing a preamble, # Title, ### Sub and a fenced ## Fenced, then writing one and asserting every unlisted line survives byte-for-byte.

Three defects fixed along the way

1. write_request classification (mcp.c) — a new write mode absent from that list runs through a query-only store handle with no mutation lease. Asserted by a mutation-guard probe (begin_count == 1), not by reasoning; rejection paths assert begin_count == 0 so a malformed write cannot block an index.
2. Legacy-ADR data loss — adding the mode to write_request skips the migration block that populates legacy (it is gated !write_request so it cannot block on the lease). The write path therefore reads the legacy file itself under the lease it already holds, rather than merging onto an empty document.
3. Lost-update race — BEGIN IMMEDIATE placed inside cbm_store_adr_update_sections, so it protects all three full-replace writers (MCP update, the UI at http_server.c:939, and the indexing pipeline at pipeline.c:1763), not just this call site.

Verification

• mcp store_arch store_nodes store_edges complexity httpd pipeline → 700 passed, 7 skipped, 0 failed.
• Idempotence proved by revert: breaking the merge to append-like produced exactly one failure — the idempotence test — confirming that test alone carries the property.
• Three further surgical breaks each failed the expected tests and only those: disabling fence awareness (4), dropping preserved separator runs (3), removing body newline normalisation (1). Reverted and green each time.
• All 13 new tests confirmed by name in runner output. Build exit code asserted before every run — it caught a test registered before its definition, where a stale binary would have reported the old result.
• Cap enforcement tested by observed failure, asserting the stored ADR is byte-identical afterwards (which also proves rollback).

Known, not touched

cbm_adr_validate_content still requires all six canonical sections. It has zero production callers (tests only), so under "canonical is conventional" it is arguably stale — flagged rather than quietly redefined, since that was outside the decision made here.