[Agentic] Implementation plan: hashing substrate (merge/concatenate roadmap row 1) - #7275

Description

Follow-up to #7274, which banked the merge/concatenate design spec. This
pull request carries the implementation plan for row 1 of that spec's
roadmap (§6) — moving the array hashing machinery out of iris._concatenate
into a new private iris._combine_common, per §5.1.

It deliberately contains no implementation. The code change itself follows in
a separate pull request.

Why the plan ships on its own

A core developer opening the implementation pull request should see a diff they
can hold in their head: a module moved, an import repointed, a test added. A
four-hundred-line plan describing how an agent was told to do it is not evidence
about that change — it is homework handed in alongside the work, and it makes a
small, easily approved diff look like a large one.

So this becomes the standing convention for the programme, recorded in
docs/src/developers_guide/plans/README.md and in §6 of the spec: a plan
ships as its own pull request, ahead of the implementation it describes. The
implementation pull request then carries only the change under review, and can
be reviewed on its merits by someone who has never read the plan and does not
need to.

Plans are tracked in the repository for provenance but are excluded from the
Sphinx build (exclude_patterns in docs/src/conf.py), so nothing here is
published.

Also in here

• Changelog attribution for agentic work. [Agentic] Design spec: making merge and concatenate robust, efficient and configurable #7274's two news fragments credited
  :user:bjlittle; the work was Claude's, so they now credit `:user:`claude.
  Attribution should say who did the work — the pull request record already shows
  who authored and reviewed it. The :user: role resolves to
  https://github.com/%s, and github.com/claude is Anthropic's own
  account, so the rendered link is correct. The rule is recorded in AGENTS.md.
  Both fragments are merged but unreleased, so this costs nothing.
• One sentence in spec §6 recording the plan-ships-separately convention.

What the plan actually says, for anyone curious

Three tasks. The move itself is atomic — creating the new module without
removing the original duplicates the definitions, and removing the original
first breaks _concatenate. There is exactly one non-mechanical hazard, which
the plan calls out: _concatenate.py:604 and :1230 assign to a local variable
named array_id, so once the moved function loses its underscore prefix that
local shadows it and the right-hand-side call raises UnboundLocalError. Ruff
does not flag it and the type checker does not flag it; only the tests do.

The plan also adds a test for the property that justifies the module's
existence: _combine_common must import nothing from Iris at runtime, which is
what makes the merge-side import risk-free later. That check is static, over the
module's AST, because import iris._combine_common executes iris/__init__.py
first and so sys.modules cannot distinguish the substrate's own imports from
the package's.

Checklist

• Included a What's New entry
• Incorporated type hints in any changed code — n/a, no code changed
• Checked if tests need updating — n/a, no code changed
• Checked if benchmarks need updating — n/a
• Checked if documentation needs updating
• Checked if dependencies need updating — n/a
• Confirmed that the GitHub 'checks' on this PR are passing ✅