docs(release): the AEN gate cleared for a pre-release floor, not for stable (#802)

[hkngln]

Closes #802.

What was false

docs/release-contract.md's "Currently outstanding" table said NO in its "In a tag?" column for d639e777 (alp-sdk#1289) and 7d58ef32 (alp-sdk#1352), on the evidence that git tag --contains d639e777 is empty. It is not empty. The cell's own re-check command — the one the section prescribes one line above the table — contradicted the cell.

Re-measured, not taken from the issue

$ git -C <alp-sdk> tag --contains d639e777
v0.16.0-rc1
$ git -C <alp-sdk> tag --contains 7d58ef32
v0.16.0-rc1

$ git -C <alp-sdk> merge-base --is-ancestor d639e777 v0.15.0 ; echo $?
1
$ git -C <alp-sdk> merge-base --is-ancestor 7d58ef32 v0.15.0 ; echo $?
1

$ gh release list --repo alplabai/alp-sdk --limit 3
v0.16.0-rc1   Pre-release   2026-08-15T02:05:12Z
v0.15.0       Latest        2026-08-07T13:36:18Z
v0.15.0-rc1   Pre-release   2026-07-31T21:54:56Z

Every claim the issue makes reproduced. One did not: the surviving upstream string is at scripts/gen_zephyr_board.py:637, not :687 — the issue is off by fifty, and the doc now cites the verified line.

The decision I did not make for you

Both facts are in the table now, because neither is the whole answer:

• the gate's stated condition — "contained in a published alp-sdk tag" — is met;
• v0.15.0 is still Latest and contains neither commit, so an AEN user on stable still cannot run tan generate --target zephyr-board.

Cutting now ships an AEN board emit whose floor is a pre-release. Waiting for alp-sdk v0.16.0 final removes the caveat outright. The section states that choice and asks for it to be recorded in the release PR, rather than a doc silently deciding it. That is why the heading is re-scoped ("Cleared for a PRE-RELEASE floor, not for the current stable") instead of deleted.

Worth keeping in view: this failed closed — falsely blocking, never falsely permitting — so nothing was ever mis-shipped on its strength. The cost was engineer time and a possibly-delayed v0.6.0.

One thing beyond the issue's stated scope

The issue says do not touch the follow-up block below the table, because the alp-sdk refusal string it quotes is still verbatim correct. That reason is sound and the quote is untouched. But the block opens:

When that release exists, two strings stop being true and must be revisited in the same change: [the alp-sdk ATOC refusal] and this table's "In a tag?" column.

The release exists, and this PR fixes the column. Leaving that sentence verbatim would leave the doc saying "when X happens, do A and B" while X has happened and B is done — a reader could not tell which half remains. It now says the trigger fired, the table is done, and the refusal string is not, with the quoted string, the alp-sdk#1354 tracking (still open) and the _aen_peripherals_dtsi() reasoning all preserved.

Say the word and I will revert that paragraph to verbatim; I would rather flag the deviation than make it quietly.

Also: a changelog fragment, which the issue said was not needed

The issue argues none is required because CHANGELOG.md:1105-1124 already records the v0.15.0-measured limitation. That records the old state; what changed here is what the gate says to a release engineer (do-not-cut → cut-with-a-named-caveat), and changelog.d/README.md carves out no exception for docs. Added as changelog.d/802.fixed.md. Drop it if you disagree — it is one file.

Test plan

• tests/gates — 476 passed, 3 skipped, including test_release_docs_match_the_workflow.py, the gate that parses this document
• Section re-read end to end after editing; an earlier revision of mine left a duplicated clause at the join, caught and repaired before commit
• The full Python suite was not run. This is a markdown-only change and no other suite is reachable from it — stated rather than implied.

[alpCaner]

The table update is right, and so is the call it leaves the release engineer: YES, pre-release only states both halves, keeps the still-true merge-base --is-ancestor clause, and replaces a blanket "do not cut" with a decision plus a request to record it. Executing half the "when that release exists" trigger and saying which half remains is better than the issue asked for.

One thing to fix before this merges, because it is the same class of defect the PR exists to remove.

The new line citation is wrong, and the correction is inverted

The doc and changelog.d/802.fixed.md both cite scripts/gen_zephyr_board.py:637, and the fragment adds:

That string is upstream's to fix and is still tracked as alp-sdk#1354 (open). ... the issue's :687 is off by fifty.

:687 is correct. Measured just now on all three refs of alplabai/alp-sdk:

$ git show v0.16.0-rc1:scripts/gen_zephyr_board.py | sed -n '686,688p'
            "commit.  The AEN board emit needs a checkout that contains it "
            "-- upgrade alp-sdk to a release that includes alp-sdk#1289.  "
            "(If you are AUTHORING this preset rather than consuming a "

$ git show origin/dev:scripts/gen_zephyr_board.py  | grep -n "upgrade alp-sdk to a release"
687:            "-- upgrade alp-sdk to a release that includes alp-sdk#1289.  "

$ git show origin/main:scripts/gen_zephyr_board.py | grep -n "upgrade alp-sdk to a release"
687:            "-- upgrade alp-sdk to a release that includes alp-sdk#1289.  "

Tag, dev and main all answer 687. Nothing in the file moved that string between them.

Why it is worth a round-trip

docs/release-contract.md is the document a release engineer follows under time pressure, and this section's remaining open item is precisely "go read that string upstream and replace it with a real version floor". Sending them to :637 costs them the lookup the citation was supposed to save, and a wrong file:line in the doc that fixes a wrong file:line is the failure mode this whole area keeps hitting — the same one alp-sdk#1416's citation gate exists to catch, and which alp-sdk#1498 records as still unenforced for CHANGELOG.md.

Fix

Two sites:

• docs/release-contract.md — the scripts/gen_zephyr_board.py:637 reference becomes :687.
• changelog.d/802.fixed.md — same change, and drop the "the issue's :687 is off by fifty" clause rather than reversing it; the fragment does not need to adjudicate the issue's line number at all.

Everything else here reads correctly to me.

[hkngln]

Fixed in 3885c27. Both sites now read :687, and the fragment no longer adjudicates the issue's line number.

Re-measured independently before changing anything, same three refs:

$ git show v0.16.0-rc1:scripts/gen_zephyr_board.py | grep -n "upgrade alp-sdk to a release"
687:            "-- upgrade alp-sdk to a release that includes alp-sdk#1289.  "
$ git show origin/dev:scripts/gen_zephyr_board.py  | grep -n "upgrade alp-sdk to a release"
687: ...
$ git show origin/main:scripts/gen_zephyr_board.py | grep -n "upgrade alp-sdk to a release"
687: ...

Worth recording what :637 actually is, since it explains the miss and confirms there is no ref where it was ever right — it is prose inside the module docstring, ~50 lines above the ATOC region logic:

$ git show v0.16.0-rc1:scripts/gen_zephyr_board.py | sed -n '635,639p'
    App MRAM alongside the ~2.6 MiB NPU MRAM-model budget" unconditionally,
    ~100 lines above a partition map derived from this same
    `memory_map:` -- so any dual-M55 AEN SoM with different slot sizes
    emitted a board file stating its MRAM budget two contradictory ways,

Same subsystem, same file, wrong string — which is exactly why it read plausible on the way in. The refusal string is not mirrored into tan-cli (grep -rn "upgrade alp-sdk to a release" python/ returns nothing), so there is no local copy whose numbering could have been the source either.

Changes:

• docs/release-contract.md:376 — scripts/gen_zephyr_board.py:637 → :687.
• changelog.d/802.fixed.md — same, and the "the issue's :687 is off by fifty" clause is dropped, not reversed.

Gates on the pushed head: python/tests/gates 470 passed, 9 skipped, rc=0; scripts/assemble_changelog.py --check rc=0 with 802.fixed.md listed.