Merge flow contradicts the documented "squash-merge, linear history" policy — enforce it or fix the docs

[dgenio]

Summary

The repository's documented merge policy ("Squash-merge. Maintain a linear history.") does
not match what actually happens on main. Either enforce the policy with branch protection
or update the docs to describe the real flow. The mismatch is itself a source of
branch-drift merges and rebase rework.

Why this matters

AGENTS.md:96 says "One logical change per PR. Squash-merge." and
docs/agent-context/workflows.md:32 says "Squash-merge. Maintain a linear history." But
the history is not linear and PRs are not squashed:

• 34 merge commits exist (git log --oneline --merges | wc -l), e.g.
  Merge pull request #229 …, #148, #115 — each landing multiple commits, not one squashed commit.
• Branch-drift reconciliation merges are present:
  e7852e8 Merge branch 'main' into claude/triage-issues-69bSW,
  820ce18 Merge branch 'main' into claude/triage-issues-5Bt4u.
• PRs commonly land internal review-rework commits rather than a clean single commit
  (e.g. b2be0e0 fix: address review feedback on PR #115,
  5f004af fix: address Copilot review …).

Because the merge button isn't constrained, contributors/agents who follow the docs ("I'll
squash") and the maintainer who merges differently produce inconsistent history. The
Merge branch 'main' into <feature> pattern is exactly the drift that also yields the
recurring CHANGELOG.md conflicts (see companion issue), and it makes git bisect and
per-PR review harder. A further symptom of process churn: PRs #81 and #82 carry the
identical title "feat(registry,federation): namespaces, BM25 search, capability manifests"
and were both merged.

Current evidence

• AGENTS.md:96, docs/agent-context/workflows.md:32 (documented squash + linear history).
• git log --merges → 34 merge commits incl. two Merge branch 'main' into … drift merges.
• mcp__github__list_pull_requests → feat(registry,federation): namespaces, BM25 search, capability manifests #81 and feat(registry,federation): namespaces, BM25 search, capability manifests #82 are duplicate-titled, both merged.

Proposed implementation

Pick one and make code+docs agree:

• (Recommended) Enforce the stated policy. On main, enable branch protection with
  Require linear history, set the repo's merge button to squash-only (disable merge
  commits), and require branches to be up to date before merge. Document the setting in
  CONTRIBUTING.md. This makes the Merge branch 'main' into … pattern impossible (rebase
  instead) and yields one commit per PR as the docs already promise.
• (Alternative) Document reality. If merge commits are intentional, remove the
  "squash-merge / linear history" claims from AGENTS.md and workflows.md and describe the
  actual flow (merge commits, allowed fix-up commits), so agents stop being told to squash.

AI-agent execution notes

• Branch-protection settings are repo configuration, not code — this issue likely needs the
  maintainer to toggle GitHub settings; the code/doc part is updating CONTRIBUTING.md,
  AGENTS.md, and workflows.md to match the chosen option.
• Do not change the "one logical change per PR" or conventional-commit-title rules; only the
  merge-strategy claim is in question.

Acceptance criteria

• The documented merge strategy matches what the GitHub merge button allows.
• If enforcing: main rejects non-linear history; the merge button offers only squash.
• CONTRIBUTING.md states the merge strategy and how to keep a branch current (rebase, not
  merge-from-main).
• No remaining doc text promises behavior the repo does not enforce.

Test plan

After enabling protection, open a trial PR and confirm only the squash option is offered and
that an out-of-date branch must update via rebase. Verify docs reference the live setting.

Documentation plan

Update CONTRIBUTING.md, AGENTS.md (Workflow), docs/agent-context/workflows.md
(PR conventions). CHANGELOG Changed (process/docs).

Migration and compatibility notes

No code or API impact. Affects how future PRs are merged only.

Risks and tradeoffs

Squash-only loses intra-PR commit granularity in history; that is already the documented
intent. Rebase-to-update can surprise contributors used to merge-from-main — call it out in
CONTRIBUTING.md.

Suggested labels

contributor-experience, reliability, documentation