… and configurable (#7274)

* Add design spec for merge/concatenate improvement programme

Specifies a twelve-PR programme to make cube merge and concatenate more
robust, efficient, configurable, extensible, lazy and lenient, without a
rewrite. Each PR is either a behaviour-preserving refactor or a standalone
user-visible improvement; together they grow a shared substrate beneath
both engines.

Includes a confirmed diagnosis and fix for the separability bug open since
2017 (#2761), verified end-to-end against the reporter's case.

Co-Authored-By: Claude Opus 5 <[email protected]>

* Record design-spec location in AGENTS.md

Co-Authored-By: Claude Opus 5 <[email protected]>

* docs: publish design specs as MyST Markdown

Adopt the spec/plan convention used in bjlittle/tephpy.

Agreed design specs now live in `docs/src/developers_guide/specs/` and are
published as part of the documentation.  They are written in MyST Markdown,
are living documents revised as a design evolves, and each declares a
citation prefix so its sections can be cited from issues and pull requests.

Implementation plans live in the sibling `docs/src/developers_guide/plans/`.
A plan is point-in-time and frozen once its pull request merges, so plans are
tracked in the repository but excluded from the Sphinx build.

This requires `myst-parser`, added to `requirements/py*.yml` and inserted into
the three lock files following the precedent of #7095 and #7100.  Markdown is
used only for specs; all other documentation remains reStructuredText.

The merge/concatenate design spec moves here from `docs/superpowers/specs/`
and is reworked to the new conventions.

Co-Authored-By: Claude Opus 5 <[email protected]>

* docs: add a plan roadmap and decision register to the merge spec

The spec described a twelve-PR programme but had nowhere to record how far
it had got, which assumptions it rested on, or what it had left open.

Restructure §6 from a static table of work into the programme's live
progress record: dependencies as a partial order rather than a chain, a
status vocabulary, an "Outside the roadmap" list, and a numbered register
of assumptions and open decisions - each item owned by the pull request
that must resolve it. Add §10 for the questions the programme raises but
does not answer, renumbering References to §11.

Also exclude "_build" and "_static" from the Sphinx build. myst-parser
makes ".md" a source suffix, so the README of each was being read as a
document.

Co-Authored-By: Claude Opus 5 <[email protected]>

* docs: record how agentic contributions are pushed and labelled

This work is long-running partly because it is also an exercise in earning
core-developer buy-in for agentic contributions, so the mechanics of how it
reaches them are worth writing down rather than re-deciding each session.

Add a "Contribution Workflow" section to AGENTS.md carrying the general
rule: branches to the fork, pull requests to a feature branch rather than
main, honest "Agentic" labelling, clear attribution, and ask before doing
anything outward-facing when unsure. Drop the "Getting Help" link list to
stay inside the file's 200-line budget - the links it held are all reachable
from CONTRIBUTING.md.

The programme-specific parts - base branch "greenfield" and the
"Feature: Merge/Concatenate" label - go in the spec's cross-cutting rules
instead, where a reviewer can see why these pull requests do not target main.

Co-Authored-By: Claude Opus 5 <[email protected]>

* docs: add changelog fragments for the design spec

Co-Authored-By: Claude Opus 5 <[email protected]>

* docs: rebase the spec baseline onto greenfield

The branch was cut from main at c508ac8; greenfield carries #7270 on top
of that, which re-solved all three lock files. The lock additions here are
re-derived against those fresh locks, and remain minimal - the myst-parser
dependency closure and the input_hash, nothing else.

The cube.py line references the spec cites are unaffected: #7270's changes
are confined to rolling_window, some 4500 lines below the merge and
concatenate methods.

Co-Authored-By: Claude Opus 5 <[email protected]>

* Spell out spec section citation runs

Give every cited section its own section sign, and separate a run of them
with a comma or a solidus rather than a dash.  A dashed range such as
"5.6-5.7" reads as a single citation carrying a stray suffix, so only its
first section is unambiguously identified -- by a reader now, and by any
cross-reference tooling later.

Records the rule on the Design Specs index page, next to the citation
prefix table it belongs with, and applies it to the one occurrence in the
merge/concatenate spec.

Co-Authored-By: Claude Opus 5 <[email protected]>

---------

Co-authored-by: Claude Opus 5 <[email protected]>

…oadmap row 1) (#7275)

* Credit Claude for agentic changelog entries

Attribution should say who did the work.  The pull request record already
shows who authored and reviewed it, so crediting the human in the changelog
as well overstates their hand in it.

Records the rule in AGENTS.md and applies it to the two news fragments from
#7274, which are merged but unreleased.  The ``:user:`` role resolves to
https://github.com/%s, and github.com/claude is Anthropic's own account, so
the rendered link is correct.

Co-Authored-By: Claude Opus 5 <[email protected]>

* Add the implementation plan for the hashing substrate

Covers row 1 of the merge/concatenate roadmap: moving the array hashing
machinery out of _concatenate.py into a new private _combine_common.py.

Records the convention that a plan ships as its own pull request, ahead of
the implementation it describes.  A reviewer opening the implementation
pull request should see a diff they can hold in their head; a plan bundled
alongside is not evidence about the change, and makes a small diff look
like a large one.

Co-Authored-By: Claude Opus 5 <[email protected]>

* Add changelog fragment

Co-Authored-By: Claude Opus 5 <[email protected]>

* Correct the hashing substrate plan from implementation findings

Three corrections, all found by executing the plan rather than reading
it.

The import block was wrong.  `from __future__ import annotations` makes
`Mapping` annotation-only in Ruff's eyes, so `TC003` requires it behind
`TYPE_CHECKING`; `_concatenate.py` has no `__future__` import, so the
rule never fires there and copying the import across unchanged fails
lint.

The move is not quite mechanical.  Dropping the underscore from
`_array_id` collides with three local bindings inside `compute_hashes`
itself, not just the five call sites the plan already anticipated in
`_concatenate.py`.  Spell out the three, and say why the exception to
"do not otherwise touch the moved code" is narrower than it looks --
every one of the eight renames exists only to clear the unprefixed
name's path, so conceding decision 6 retires all of them at once.

Verification 1 therefore no longer expects an empty diff.  It expects
two hunks and three lines, which is a stronger check than "identical":
it names what may differ instead of asserting that nothing does.  The
`\b` anchors stay, with an accurate reason -- they change nothing over
lines 305-541, but protect `bound_array_id` if the range is ever
widened.

Co-Authored-By: Claude Opus 5 <[email protected]>

---------

Co-authored-by: Claude Opus 5 <[email protected]>