From c2f5e1ab7061127520a9eef8d9e3f5dc3a0e998f Mon Sep 17 00:00:00 2001
From: John <11795372+jigarkhwar@users.noreply.github.com>
Date: Fri, 16 Oct 2026 19:04:50 +0400
Subject: [PATCH] chore(process): add the feature milestones rule and the gate
 files

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .claude/hooks/linkage-guard.sh      | 103 ++++++++
 .claude/hooks/linkage-guard_test.sh | 107 +++++++++
 .githooks/pre-push                  |  68 ++++++
 .githooks/pre-push_test.sh          | 136 +++++++++++
 AGENTS.md                           |  11 +
 cspell.json                         |   1 +
 scripts/check-linkage.sh            | 260 +++++++++++++++++++++
 scripts/check-linkage_test.sh       | 348 ++++++++++++++++++++++++++++
 8 files changed, 1034 insertions(+)
 create mode 100755 .claude/hooks/linkage-guard.sh
 create mode 100755 .claude/hooks/linkage-guard_test.sh
 create mode 100755 .githooks/pre-push
 create mode 100755 .githooks/pre-push_test.sh
 create mode 100755 scripts/check-linkage.sh
 create mode 100755 scripts/check-linkage_test.sh

diff --git a/.claude/hooks/linkage-guard.sh b/.claude/hooks/linkage-guard.sh
new file mode 100755
index 0000000..3141b9f
--- /dev/null
+++ b/.claude/hooks/linkage-guard.sh
@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# PreToolUse(Bash) guard — gate ONLY release tagging. ~0 tokens. Normal push/merge untouched.
+# Fires ONLY on a real git tag/push command, never on text that merely mentions one.
+# Bypass a deliberate release: LINKAGE_OFF=1 <cmd>
+#
+# This is the source every Galaxio repository copies. Change it here and carry the
+# change outward; linkage-guard_test.sh beside it is the contract those copies
+# share. It reached this shape after two repositories hit the same failure
+# independently — a `gh pr create` whose body documented the hook was blocked by
+# it, reporting a version that came from prose.
+#
+# One divergence, carried back the other way: the push rule does not treat a
+# release/N branch as a release. Publishing is what the tag does, a branch push
+# publishes nothing, and the version was being read out of the branch name — but
+# a release branch serves a whole minor line (release/1.2.0 -> v1.2.0, v1.2.1, …),
+# so for every patch release that name is the wrong version and the guard went
+# looking for a milestone that never existed. It blocked the documented release
+# procedure at its second step.
+#
+# This is the fast in-session failure, not the whole gate: it only ever sees
+# commands an agent runs, so a push from a terminal or an IDE never reaches it.
+# .githooks/pre-push catches those by reading the refs git hands it. Both run
+# locally and can be skipped; nothing checks server-side unless the project's
+# release workflow runs scripts/check-linkage.sh --for-tag itself.
+set -uo pipefail
+input=$(cat)
+cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // ""' 2>/dev/null || true)
+[ -n "$cmd" ] || exit 0
+[ "${LINKAGE_OFF:-}" = "1" ] && exit 0
+case "$cmd" in *LINKAGE_OFF=1*) exit 0 ;; esac
+case "$cmd" in *git*) ;; *) exit 0 ;; esac
+root="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"
+checker="$root/scripts/check-linkage.sh"
+block() { printf 'BLOCKED by linkage-guard:\n%s\n' "$1" >&2; exit 2; }
+
+# Scope the guard to what the shell would actually RUN. Matching the raw command string
+# made any *argument* mentioning a tag look like a release — a `gh pr create` whose heredoc
+# body documented this hook was blocked, reporting a version that came from prose.
+# So: drop heredoc bodies, split on shell separators, keep only segments that invoke git.
+strip_heredocs() {
+  local line trimmed term="" re='<<-?[[:space:]]*["'"'"']?([A-Za-z_][A-Za-z0-9_]*)["'"'"']?'
+  while IFS= read -r line; do
+    if [ -n "$term" ]; then
+      trimmed="${line#"${line%%[![:space:]]*}"}"
+      [ "$trimmed" = "$term" ] && term=""
+      continue
+    fi
+    printf '%s\n' "$line"
+    [[ $line =~ $re ]] && term="${BASH_REMATCH[1]}"
+  done
+}
+
+split_segments() {
+  local s="$1"
+  s="${s//&&/$'\n'}"; s="${s//||/$'\n'}"; s="${s//;/$'\n'}"; s="${s//|/$'\n'}"
+  printf '%s\n' "$s"
+}
+
+# Peel leading env assignments and wrappers so `rtk proxy git tag …` still counts as git.
+peel() {
+  local s="$1" head
+  s="${s#"${s%%[![:space:]]*}"}"
+  while :; do
+    head="${s%% *}"
+    case "$head" in
+      [A-Za-z_]*=*) s="${s#"$head"}" ;;
+      rtk|proxy|sudo|env|nohup|time|command|builtin|exec|xargs) s="${s#"$head"}" ;;
+      *) break ;;
+    esac
+    s="${s#"${s%%[![:space:]]*}"}"
+  done
+  printf '%s' "$s"
+}
+
+is_tag=0
+hit=""
+segments=$(split_segments "$(printf '%s\n' "$cmd" | strip_heredocs)")
+while IFS= read -r seg; do
+  seg=$(peel "$seg")
+  case "$seg" in git|git\ *) ;; *) continue ;; esac
+  # Non-release subcommands are out of scope. Scoped to THIS segment: the old global
+  # reset let `git commit -m … && git tag vX.Y.Z` through ungated.
+  printf '%s' "$seg" | grep -qE '^git[[:space:]]+(commit|log|show)\b' && continue
+  # Any `git tag …` carrying a vX.Y.Z, in any flag order — upstream required the version
+  # to sit immediately after `tag`, so the documented annotated form (`git tag -a vX.Y.Z -m …`)
+  # slipped through. Read-only/destructive subcommands (-l/--list, -d/--delete, -v/--verify,
+  # -n) are not release creation and stay out of scope.
+  if printf '%s' "$seg" | grep -qE '^git[[:space:]]+tag\b' \
+     && printf '%s' "$seg" | grep -qE '\bv?[0-9]+\.[0-9]+\.[0-9]+' \
+     && ! printf '%s' "$seg" | grep -qE '^git[[:space:]]+tag[[:space:]]+(-l\b|--list\b|-d\b|--delete\b|-v\b|--verify\b|-n)'; then
+    is_tag=1; hit="$seg"; break
+  fi
+  if printf '%s' "$seg" | grep -qE '^git[[:space:]]+push\b' \
+     && printf '%s' "$seg" | grep -qE '(--tags|refs/tags/|[[:space:]](origin[[:space:]]+)?v[0-9]+\.[0-9]+\.[0-9]+([[:space:]]|$))'; then
+    is_tag=1; hit="$seg"; break
+  fi
+done <<<"$segments"
+[ "$is_tag" = 1 ] || exit 0
+[ -x "$checker" ] || block "checker missing ($checker) — release cannot be verified"
+ver=$(printf '%s' "$hit" | grep -oE 'v?[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+[ -n "$ver" ] || block "tag/release push without explicit vX.Y.Z — verify: scripts/check-linkage.sh --for-tag <version>"
+out=$("$checker" --for-tag "$ver" 2>&1) || block "$out"
+exit 0
diff --git a/.claude/hooks/linkage-guard_test.sh b/.claude/hooks/linkage-guard_test.sh
new file mode 100755
index 0000000..ea730c4
--- /dev/null
+++ b/.claude/hooks/linkage-guard_test.sh
@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+#
+# linkage-guard_test.sh — regression suite for .claude/hooks/linkage-guard.sh.
+#
+# This suite travels with the guard. It is the contract the copies in every
+# Galaxio repository share, and each case below is a shape the guard got wrong
+# at some point — keep them, and add to them rather than trimming.
+#
+# The guard must gate release tagging and nothing else. Two symmetric failures matter:
+# blocking a command that merely *mentions* tagging, and waving through a real tag hidden
+# in a compound command. Both are covered below.
+#
+# The real scripts/check-linkage.sh is replaced by a stub, so the suite is deterministic,
+# offline, and independent of milestone state. It asserts only the guard's scope decision:
+# exit 0 = passed through, exit 2 = gated.
+#
+# Usage: bash scripts/test-linkage-guard.sh   [GUARD=/path/to/linkage-guard.sh]
+# Exit:  0 all green | 1 at least one case failed
+set -uo pipefail
+
+# The suite sits beside the hook it tests, as .githooks/pre-push_test.sh does.
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+GUARD="${GUARD:-$here/linkage-guard.sh}"
+[ -r "$GUARD" ] || { echo "guard not found: $GUARD" >&2; exit 1; }
+command -v jq >/dev/null || { echo "jq is required" >&2; exit 1; }
+
+fake=$(mktemp -d)
+trap 'rm -rf "$fake"' EXIT
+mkdir -p "$fake/scripts"
+cat >"$fake/scripts/check-linkage.sh" <<'STUB'
+#!/usr/bin/env bash
+echo "stub check-linkage: $*"
+exit 1
+STUB
+chmod +x "$fake/scripts/check-linkage.sh"
+
+pass=0
+fail=0
+
+run() { # run <expected rc> <label> <command>
+  local want="$1" label="$2" cmd="$3" out rc
+  out=$(jq -n --arg c "$cmd" '{tool_input:{command:$c}}' \
+        | CLAUDE_PROJECT_DIR="$fake" bash "$GUARD" 2>&1)
+  rc=$?
+  if [ "$rc" = "$want" ]; then
+    pass=$((pass + 1))
+    printf '  ok   [%s] %s\n' "$rc" "$label"
+  else
+    fail=$((fail + 1))
+    printf '  FAIL want=%s got=%s  %s\n       cmd: %s\n       out: %s\n' \
+      "$want" "$rc" "$label" "$cmd" "$out"
+  fi
+}
+
+echo "== must pass through (0) — not a release =="
+run 0 'gh pr create, heredoc body mentions tagging' \
+  "$(printf 'gh pr create --body-file - <<%sEOF%s\nRatified at v1.0.0.\nlinkage-guard blocks git tag vX.Y.Z until the milestone passes.\nEOF' "'" "'")"
+run 0 'gh pr create, quoted body mentions tagging' \
+  'rtk proxy gh pr create --title "x" --body "the guard blocks git tag v1.2.3"'
+run 0 'gh issue create quoting a tag command' \
+  'gh issue create --body "repro: git tag v2.3.4 then git push origin v2.3.4"'
+run 0 'echo of a tag command'        'echo "git tag v9.9.9"'
+run 0 'git status'                   'git status --short'
+run 0 'git log over a tag range'     'git log --oneline v1.0.6..origin/main'
+run 0 'git show a tag'               'git show v1.0.6'
+run 0 'git push a feature branch'    'git push -u origin feat/some-work'
+run 0 'git commit mentioning a tag'  'git commit -m "docs: describe git tag v1.0.7 flow"'
+run 0 'git tag --list glob'          "git tag -l 'v1.*'"
+run 0 'git tag --list long flag'     'git tag --list v1.0.0'
+run 0 'git tag --delete'             'git tag -d v1.0.0'
+run 0 'git tag --verify'             'git tag -v v1.0.0'
+run 0 'git branch'                   'git branch -a'
+run 0 'LINKAGE_OFF prefix bypass'    'LINKAGE_OFF=1 git tag v1.0.7'
+run 0 'no git anywhere'              'ls -la'
+
+echo "== must gate (2) — a real release =="
+run 2 'lightweight tag'              'git tag v1.0.7'
+run 2 'annotated tag'                'git tag -a v1.0.7 -m "release 1.0.7"'
+run 2 'tag behind the rtk wrapper'   'rtk proxy git tag v1.0.7'
+run 2 'push a version tag'           'git push origin v1.0.7'
+run 2 'push --tags'                  'git push --tags'
+run 2 'push refs/tags'               'git push origin refs/tags/v1.0.7'
+# parsec diverges here, and the divergence belongs upstream too: publishing is
+# what the tag does, and a release branch serves a whole minor line, so its name
+# is the wrong version for every patch release in the repository that found it.
+run 0 'push a release branch'        'git push origin release/1.0'
+run 0 'fast-forward the release branch' 'git push origin origin/main:refs/heads/release/0.0.0'
+run 2 'commit && tag'                'git commit -m "prep" && git tag v1.0.7'
+run 2 'cd && tag'                    'cd /tmp && git tag v1.0.7'
+run 2 'log && tag'                   'git log --oneline -1 && git tag v1.0.7'
+run 2 'tag behind sudo'              'sudo git tag v1.0.7'
+run 2 'push behind xargs'            'xargs git push --tags'
+run 2 'push behind an env assignment' 'GIT_SSH_COMMAND=ssh git push origin v1.0.7'
+run 2 'heredoc first, tag after' \
+  "$(printf 'cat > /tmp/notes.md <<%sMD%s\n## v1.0.7\nMD\ngit tag v1.0.7' "'" "'")"
+
+echo "== the version handed to the checker =="
+out=$(jq -n --arg c 'git tag v1.0.7' '{tool_input:{command:$c}}' \
+      | CLAUDE_PROJECT_DIR="$fake" bash "$GUARD" 2>&1 || true)
+if printf '%s' "$out" | grep -q -- '--for-tag v1.0.7'; then
+  pass=$((pass + 1)); printf '  ok   [-] the checker is asked about the tag being created\n'
+else
+  fail=$((fail + 1)); printf '  FAIL the checker was asked: %s\n' "$out"
+fi
+
+printf '\n%d passed, %d failed\n' "$pass" "$fail"
+[ "$fail" = 0 ]
diff --git a/.githooks/pre-push b/.githooks/pre-push
new file mode 100755
index 0000000..ea16c21
--- /dev/null
+++ b/.githooks/pre-push
@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+#
+# pre-push — refuse to publish a release tag whose milestone is not ready.
+#
+# git hands this hook the refs it is about to push, one line per ref:
+#
+#     <local ref> <local sha1> <remote ref> <remote sha1>
+#
+# so there is nothing to parse and nothing to guess. That is the whole reason
+# the gate lives here. It used to live in a Claude Code PreToolUse hook that
+# read the raw text of every Bash command and tried to work out whether it was
+# a release; eleven shapes walked straight through it — a wrapper like `xargs`
+# or `sudo`, a `bash -c` body, a subshell, a line continuation, a heredoc
+# anywhere in the command — and two ordinary `git commit` messages were blocked
+# for quoting the word push. None of that is expressible here: git says which
+# refs are moving, whoever asked it to.
+#
+# It also covers pushes that hook never sees at all — from a terminal, from an
+# IDE, from a script — because git runs this for every client.
+#
+# It is not a guarantee. A local hook is opt-in (core.hooksPath) and can be
+# skipped with --no-verify, and nothing server-side repeats the check unless
+# the project's own release workflow runs `scripts/check-linkage.sh --for-tag`.
+# Even then the workflow starts after the tag is public, so it can hold back the
+# release but not the tag. This is the fast failure that saves you from finding
+# out after the tag is public and cannot be taken back.
+
+set -uo pipefail
+
+# Bypass a deliberate release: LINKAGE_OFF=1 git push ...
+[ "${LINKAGE_OFF:-}" = "1" ] && exit 0
+
+root=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+checker="$root/scripts/check-linkage.sh"
+
+status=0
+
+while read -r _local_ref local_sha remote_ref _remote_sha; do
+  # Only a tag publishes a release. A branch push moves no version.
+  case "$remote_ref" in
+    refs/tags/v[0-9]*) ;;
+    *) continue ;;
+  esac
+
+  # A deletion carries the all-zero object id on the local side. Deleting a tag
+  # publishes nothing, and the rule against deleting a released tag is a matter
+  # for review, not for this hook — refusing here would only teach --no-verify.
+  case "$local_sha" in
+    *[!0]*) ;;
+    *) continue ;;
+  esac
+
+  version=${remote_ref#refs/tags/}
+
+  if [ ! -x "$checker" ]; then
+    printf 'pre-push: %s is missing, so %s cannot be verified\n' "$checker" "$version" >&2
+    status=1
+    continue
+  fi
+
+  if ! out=$("$checker" --for-tag "$version" 2>&1); then
+    printf '%s\n' "$out" >&2
+    printf 'pre-push: refusing to publish %s — its milestone is not ready\n' "$version" >&2
+    status=1
+  fi
+done
+
+exit "$status"
diff --git a/.githooks/pre-push_test.sh b/.githooks/pre-push_test.sh
new file mode 100755
index 0000000..ce417c4
--- /dev/null
+++ b/.githooks/pre-push_test.sh
@@ -0,0 +1,136 @@
+#!/usr/bin/env bash
+#
+# pre-push_test.sh — regression tests for the release-tag gate in pre-push
+# (constitution Principle III: a bug fix ships with a test that fails without
+# the fix).
+#
+# check-linkage.sh is replaced by a stub, so the tests are hermetic: no network,
+# no milestones, same result on a laptop and on a runner. What is under test is
+# the hook's own decisions — which refs it gates, which it lets by, and whether
+# it fails closed.
+#
+# Note what is absent. The gate this replaced had to be tested against `xargs`,
+# `sudo`, `bash -c`, subshells, line continuations and heredocs, because it
+# guessed at command text. git reports the refs directly, so that entire class
+# of test has nothing to assert: the same four fields arrive however the push
+# was invoked.
+
+set -uo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+hook="$here/pre-push"
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+
+pass=0; fail=0
+ok()  { printf '  ✓ %s\n' "$1"; pass=$((pass + 1)); }
+bad() { printf '  ✗ %s\n     %s\n' "$1" "$2"; fail=$((fail + 1)); }
+
+zero=0000000000000000000000000000000000000000
+sha=a1b2c3d4e5f60718293a4b5c6d7e8f9012345678
+
+# ---- a repository whose checker is a stub ----------------------------------
+repo="$tmp/repo"
+mkdir -p "$repo/scripts"
+git -C "$repo" init -q 2>/dev/null
+: > "$repo/f"; git -C "$repo" add f
+git -C "$repo" -c user.email=t@t -c user.name=t commit -qm init
+
+# The stub records what it was asked and answers from CHECKER_VERDICT.
+cat > "$repo/scripts/check-linkage.sh" <<'STUB'
+#!/usr/bin/env bash
+printf '%s\n' "$*" >> "$CHECKER_LOG"
+if [ "${CHECKER_VERDICT:-ready}" = "ready" ]; then
+  echo "PASS: milestone is tag-ready"
+  exit 0
+fi
+echo "FAIL: issue #7 is open — must be closed before tagging"
+exit 1
+STUB
+chmod +x "$repo/scripts/check-linkage.sh"
+
+# run <verdict> <stdin lines> -> prints "rc|calls"
+run() {
+  local verdict="$1" input="$2"
+  : > "$tmp/log"
+  ( cd "$repo" && CHECKER_LOG="$tmp/log" CHECKER_VERDICT="$verdict" \
+      bash "$hook" origin https://example.invalid/r.git <<< "$input" >/dev/null 2>&1 )
+  printf '%s|%s' "$?" "$(wc -l < "$tmp/log" | tr -d ' ')"
+}
+
+check() { # check <name> <want rc|calls> <verdict> <stdin>
+  local got; got=$(run "$3" "$4")
+  if [ "$got" = "$2" ]; then ok "$1"; else bad "$1" "want rc|calls = $2, got $got"; fi
+}
+
+printf 'pre-push\n'
+
+check "a ready tag is published" \
+  "0|1" ready "refs/tags/v1.2.3 $sha refs/tags/v1.2.3 $zero"
+
+check "an unready tag is refused" \
+  "1|1" unready "refs/tags/v1.2.3 $sha refs/tags/v1.2.3 $zero"
+
+check "a branch push is not a release, and asks nothing" \
+  "0|0" unready "refs/heads/main $sha refs/heads/main $sha"
+
+check "pushing the release branch is not a release" \
+  "0|0" unready "refs/heads/release/0.0.0 $sha refs/heads/release/0.0.0 $zero"
+
+check "deleting a tag publishes nothing" \
+  "0|0" unready "(delete) $zero refs/tags/v1.2.3 $sha"
+
+check "a tag that is not a release version is left alone" \
+  "0|0" unready "refs/tags/nightly $sha refs/tags/nightly $zero"
+
+# --tags sends one line per tag; each is judged, and one bad one refuses the push.
+check "--tags checks every tag it carries" \
+  "0|3" ready "refs/tags/v1.0.0 $sha refs/tags/v1.0.0 $zero
+refs/tags/v1.1.0 $sha refs/tags/v1.1.0 $zero
+refs/tags/v1.2.3 $sha refs/tags/v1.2.3 $zero"
+
+check "one unready tag refuses the whole push" \
+  "1|2" unready "refs/tags/v1.0.0 $sha refs/tags/v1.0.0 $zero
+refs/tags/v1.2.3 $sha refs/tags/v1.2.3 $zero"
+
+check "a tag riding along with a branch is still checked" \
+  "1|1" unready "refs/heads/main $sha refs/heads/main $sha
+refs/tags/v1.2.3 $sha refs/tags/v1.2.3 $zero"
+
+check "nothing to push is not a failure" \
+  "0|0" unready ""
+
+# Fails closed: a missing checker must refuse, not wave the tag through.
+mv "$repo/scripts/check-linkage.sh" "$repo/scripts/check-linkage.sh.away"
+check "a missing checker refuses the tag" \
+  "1|0" ready "refs/tags/v1.2.3 $sha refs/tags/v1.2.3 $zero"
+mv "$repo/scripts/check-linkage.sh.away" "$repo/scripts/check-linkage.sh"
+
+# The version handed to the checker is the tag's own, never guessed from a path
+# or an earlier ref — the defect that let the old gate vet the wrong release.
+: > "$tmp/log"
+( cd "$repo" && CHECKER_LOG="$tmp/log" CHECKER_VERDICT=ready \
+    bash "$hook" origin https://example.invalid/v9.9.9/r.git \
+    <<< "refs/tags/v1.2.3 $sha refs/tags/v1.2.3 $zero" >/dev/null 2>&1 )
+if grep -qx -- "--for-tag v1.2.3" "$tmp/log"; then
+  ok "the checker is asked about the tag being pushed"
+else
+  bad "the checker is asked about the tag being pushed" "asked: $(cat "$tmp/log")"
+fi
+
+# LINKAGE_OFF=1 bypasses the gate entirely, before the checker is ever asked —
+# the same escape hatch linkage-guard.sh already gives an in-session release.
+: > "$tmp/log"
+( cd "$repo" && CHECKER_LOG="$tmp/log" CHECKER_VERDICT=unready LINKAGE_OFF=1 \
+    bash "$hook" origin https://example.invalid/r.git \
+    <<< "refs/tags/v1.2.3 $sha refs/tags/v1.2.3 $zero" >/dev/null 2>&1 )
+rc=$?
+calls=$(wc -l < "$tmp/log" | tr -d ' ')
+if [ "$rc" = 0 ] && [ "$calls" = 0 ]; then
+  ok "LINKAGE_OFF=1 bypasses the gate without consulting the checker"
+else
+  bad "LINKAGE_OFF=1 bypasses the gate without consulting the checker" "rc=$rc calls=$calls"
+fi
+
+printf '\n%d passed, %d failed\n' "$pass" "$fail"
+[ "$fail" -eq 0 ]
diff --git a/AGENTS.md b/AGENTS.md
index 70c1098..589d98b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -169,3 +169,14 @@ Assertions check the _message_, not just the exit code — an error must name th
 - Prettier: single quotes in `.mjs`, double in JSON, 100 columns; `.gitattributes` forces LF, since `sync --check` compares byte-for-byte
 - New vocabulary in Markdown or code comments must be added to `cspell.json` or CI fails
 - `plugins/`, `scripts/`, `schemas/`, `tests/`, `.github/` and `package.json` are CODEOWNERS-protected
+
+## Feature milestones (ALWAYS)
+
+A feature is an issue in `galax-io/galaxio-sdlc-backlog`. It belongs to exactly one backlog milestone whose description has the line `Release: business`. Backlog milestones without that line (the backlog's own tooling and documents) are not releases and follow "Milestones" above.
+
+- **Feature issue.** Lists the work in every repository it touches as a checklist, one line per issue or PR: `- [ ] galax-io/<repo>#<N> → <repo milestone>`. A line is checked when that work is merged and the repository milestone it names has been released, so its tag exists.
+- **Repository work.** Every issue and PR of a feature carries the version milestone of its own repository and writes `Part of galax-io/galaxio-sdlc-backlog#<feature>`. A repository ships its own version when its milestone is complete, as under "Release Process". `scripts/check-linkage.sh` skips the same-milestone rule for a link to a feature; the PR still needs its own milestone.
+- **Feature done.** A feature issue is closed only when every line of its checklist is checked.
+- **Release.** When every feature of a business milestone is closed, close the milestone and publish a GitHub Release in `galax-io/galaxio-sdlc-backlog` that lists each feature with the repository versions that carry it. Name the release and its tag by the milestone's id, the title up to its first em dash, lowercased (`M1 — first run` → `m1`).
+- **Published releases are not edited.** A revert after the release is a new feature in the next business milestone.
+- **Never** close a business milestone with an open feature, release a feature whose repository version is not tagged, or leave a repository version out of the release text.
diff --git a/cspell.json b/cspell.json
index 9877666..d6c54d3 100644
--- a/cspell.json
+++ b/cspell.json
@@ -56,6 +56,7 @@
     "println",
     "qpid",
     "scalafmt",
+    "sdlc",
     "SECRETISH",
     "semver",
     "shellcheck",
diff --git a/scripts/check-linkage.sh b/scripts/check-linkage.sh
new file mode 100755
index 0000000..f4a833e
--- /dev/null
+++ b/scripts/check-linkage.sh
@@ -0,0 +1,260 @@
+#!/usr/bin/env bash
+#
+# check-linkage.sh — verify the issue ↔ PR ↔ milestone contract (see AGENTS.md "Milestones (ALWAYS)").
+# Run `scripts/check-linkage.sh --help` for full usage.
+
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+check-linkage.sh — verify the issue <-> PR <-> milestone contract (see AGENTS.md "Milestones (ALWAYS)").
+
+What each entity owes (this script enforces it):
+  Issue      an important task, not a technical one; belongs to exactly one milestone;
+             closed only when its fix is on main.
+  PR         carries a milestone. One that completes an important task links its
+             issue with a real closing link (Closes owner/repo#N); one PR of several
+             writes "Part of owner/repo#N". A linked issue sits in the PR's milestone.
+             A technical PR (sync, pins, docs, CI) links no issue: its commit is the record.
+  Milestone  one release (vX.Y.Z); tag only when every issue is closed, every PR that
+             links one is merged, and no PR is still open.
+  Feature    an issue in the backlog repository whose milestone says "Release: business"
+             on a line of its own. It sits in that business milestone, not in the version
+             milestone of the PR that does a part of it, so a link to a feature skips the
+             same-milestone rule. The PR still carries its own version milestone.
+
+Usage:
+  scripts/check-linkage.sh --pr <N>          # GATE one PR: milestone + any linked issue in the same milestone
+  scripts/check-linkage.sh --for-tag vX.Y.Z  # GATE a release: tag-readiness of that version's milestone
+  scripts/check-linkage.sh [milestone]       # audit a milestone (default: lowest-numbered open)
+  scripts/check-linkage.sh --tag [ms]        # also assert tag-readiness (issues closed, linked PRs merged, none open)
+  scripts/check-linkage.sh --help
+
+Env:
+  REPO=owner/name          # override repo (default: gh repo view of the current checkout)
+  BACKLOG_REPO=owner/name  # the repository whose business milestones hold features
+                           # (default: galax-io/galaxio-sdlc-backlog)
+
+Exit: 0 all rules hold | 1 at least one violation | 2 usage/prereq error.
+EOF
+}
+
+for bin in gh jq; do
+  command -v "$bin" >/dev/null 2>&1 || { echo "error: '$bin' not found on PATH" >&2; exit 2; }
+done
+
+REPO="${REPO:-$(gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || true)}"
+[ -n "$REPO" ] || { echo "error: cannot determine repo — run inside a GitHub checkout or set REPO=owner/name" >&2; exit 2; }
+
+BACKLOG_REPO="${BACKLOG_REPO:-galax-io/galaxio-sdlc-backlog}"
+
+TAG_MODE=0
+MS=""
+PR_NUM=""
+FOR_TAG=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --tag)      TAG_MODE=1 ;;
+    --pr)       shift; PR_NUM="${1:-}"
+                [[ "$PR_NUM" =~ ^[0-9]+$ ]] || { echo "error: --pr needs a numeric PR id" >&2; exit 2; } ;;
+    --for-tag)  shift; FOR_TAG="${1:-}"
+                [[ "$FOR_TAG" =~ ^v?[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "error: --for-tag needs vX.Y.Z" >&2; exit 2; } ;;
+    --help|-h)  usage; exit 0 ;;
+    [0-9]*)     MS="$1" ;;
+    *)          echo "error: unknown argument '$1'" >&2; usage; exit 2 ;;
+  esac
+  shift
+done
+
+# Issues may live in another repository (the SDLC backlog), so every reference is
+# owner/repo#N and is looked up in its own repository. A bare #N means this one.
+closing_refs() { # pr-json -> registered GitHub closing links
+  jq -r '.closingIssuesReferences[]? | "\(.repository.owner.login)/\(.repository.name)#\(.number)"' <<<"$1"
+}
+body_refs() { # pr-json, regex of what precedes a link -> "[owner/repo]#N" links in the body
+  jq -r '.body // ""' <<<"$1" \
+    | grep -oiE "$2([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)?#[0-9]+" \
+    | grep -oE '([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)?#[0-9]+$' \
+    | sed "s|^#|$REPO#|" || true
+}
+issue_ms() { # owner/repo#N -> the issue's milestone title
+  gh issue view "${1##*#}" --repo "${1%#*}" --json milestone -q '.milestone.title // ""' 2>/dev/null || echo ""
+}
+feature_ms() { # owner/repo#N -> the business milestone's title when the issue is a feature of the backlog
+  [ "${1%#*}" = "$BACKLOG_REPO" ] || return 0
+  gh issue view "${1##*#}" --repo "${1%#*}" --json milestone -q '
+    select(.milestone != null and ((.milestone.description // "")
+      | test("(^|\n)[ \t]*Release:[ \t]*business[ \t]*\r?(\n|$)"; "i"))) | .milestone.title' 2>/dev/null || true
+}
+pr_links() { # pr-json -> its issue links: registered closing links, else "Part of" lines
+  local refs
+  refs=$(closing_refs "$1")
+  [ -n "$refs" ] || refs=$(body_refs "$1" "$PART_OF")
+  printf '%s' "$refs"
+}
+# "Part of owner/repo#N" marks one PR per repository of a multi-repository change. It is
+# this project's convention, not a GitHub keyword, so it counts only at the start of a
+# line: prose such as "part of #190's follow-up" links nothing.
+PART_OF='^[[:space:]]*part of +'
+# GitHub's closing keywords start a word and may take a colon: "prefix #5" closes nothing.
+CLOSES='(^|[^[:alnum:]_])(close[sd]?|fix(e[sd])?|resolve[sd]?):? +'
+
+# Gate one PR (the merge gate). Fails if the PR is missing a milestone or links an
+# issue in a different milestone. A PR that links no issue passes: a technical PR
+# needs none. A link is a registered GitHub closing link, or "Part of owner/repo#N"
+# for one PR of several. A Closes in the body of a PR that does not target the
+# default branch still fails: GitHub links closing keywords only there, so merging
+# would not close that issue. On the default branch, a Closes GitHub did not link
+# names no issue (a pull request, say) and is not a link (the lenient text
+# fallback is audit-mode only).
+if [ -n "$PR_NUM" ]; then
+  pj=$(gh pr view "$PR_NUM" --repo "$REPO" --json number,title,state,milestone,closingIssuesReferences,body,baseRefName) \
+    || { echo "error: PR #$PR_NUM not found in $REPO" >&2; exit 2; }
+  p_title=$(jq -r '.title' <<<"$pj")
+  p_ms=$(jq -r '.milestone.title // ""' <<<"$pj")
+  p_links=$(pr_links "$pj")
+  e=0
+  printf 'PR #%s  %s\n' "$PR_NUM" "$p_title"
+  if [ -z "$p_ms" ]; then printf '  ✗ no milestone — assign one (gh pr edit %s --milestone "…")\n' "$PR_NUM"; e=1
+  else printf '  ✓ milestone: %s\n' "$p_ms"; fi
+  if [ -z "$p_links" ]; then
+    p_text=$(body_refs "$pj" "$CLOSES")
+    p_base=$(jq -r '.baseRefName' <<<"$pj")
+    default=$p_base
+    if [ -n "$p_text" ]; then
+      default=$(gh api "repos/$REPO" --jq '.default_branch') \
+        || { echo "error: cannot read the default branch of $REPO" >&2; exit 2; }
+    fi
+    if [ "$p_base" != "$default" ]; then
+      printf '  ✗ the body closes %s, but the PR targets %s, not %s, and GitHub links closing keywords only on the default branch, so merging would not close it — retarget the PR, or write "Part of …"\n' \
+        "$(paste -sd, - <<<"$p_text")" "$p_base" "$default"; e=1
+    else
+      printf '  ✓ links no issue (a technical PR needs none)\n'
+    fi
+  else
+    for i in $p_links; do
+      i_feature=$(feature_ms "$i")
+      i_ms=$(issue_ms "$i")
+      if [ -n "$i_feature" ]; then printf '  ✓ links %s (feature of business milestone "%s")\n' "$i" "$i_feature"
+      elif [ -z "$p_ms" ]; then printf '  - links %s (its milestone is "%s")\n' "$i" "${i_ms:-none}"
+      elif [ "$i_ms" = "$p_ms" ]; then printf '  ✓ links %s (same milestone)\n' "$i"
+      else printf '  ✗ links %s but its milestone is "%s", not "%s"\n' "$i" "${i_ms:-none}" "$p_ms"; e=1; fi
+    done
+  fi
+  if [ "$e" = 0 ]; then printf 'PASS: PR #%s is well-formed.\n' "$PR_NUM"; exit 0; fi
+  printf 'FAIL: PR #%s is malformed — fix the above before merge.\n' "$PR_NUM"; exit 1
+fi
+
+# Map a release version (vX.Y.Z) to its milestone, then assert tag-readiness on it.
+# Patch versions map to the vX.Y.0 milestone (e.g. v1.23.1 -> "v1.23.0 …").
+if [ -n "$FOR_TAG" ]; then
+  v="${FOR_TAG#v}"; minor="v${v%.*}.0"
+  MS=$(gh api "repos/$REPO/milestones?state=all&per_page=100" \
+        | jq -r --arg t "$minor" 'map(select(.title | startswith($t))) | .[0].number // empty')
+  [ -n "$MS" ] || { echo "error: no milestone whose title starts with '$minor' for tag $FOR_TAG" >&2; exit 2; }
+  TAG_MODE=1
+fi
+
+# Default to the lowest-numbered open milestone (the "active" one).
+if [ -z "$MS" ]; then
+  MS=$(gh api "repos/$REPO/milestones?state=open&per_page=100" --jq 'sort_by(.number) | .[0].number // empty')
+  [ -n "$MS" ] || { echo "error: no open milestone found in $REPO" >&2; exit 2; }
+fi
+
+ms_json=$(gh api "repos/$REPO/milestones/$MS") || { echo "error: milestone #$MS not found in $REPO" >&2; exit 2; }
+ms_title=$(jq -r '.title' <<<"$ms_json")
+ms_state=$(jq -r '.state' <<<"$ms_json")
+
+errors=0
+warns=0
+err()  { printf '  ✗ %s\n' "$1"; errors=$((errors + 1)); }
+warn() { printf '  ! %s\n' "$1"; warns=$((warns + 1)); }
+ok()   { printf '  ✓ %s\n' "$1"; }
+
+printf 'Repo:      %s\n' "$REPO"
+printf 'Milestone: #%s  %s  (%s)\n' "$MS" "$ms_title" "$ms_state"
+[ "$TAG_MODE" = 1 ] && printf 'Mode:      tag-readiness\n'
+printf '\n'
+
+# All issues + PRs carrying this milestone (REST returns both; PRs carry a .pull_request key).
+items=$(gh api --paginate --slurp "repos/$REPO/issues?milestone=$MS&state=all&per_page=100" | jq 'add')
+
+pr_numbers=$(jq -r '.[] | select(.pull_request != null) | .number' <<<"$items")
+issue_numbers=$(jq -r '.[] | select(.pull_request == null) | .number' <<<"$items")
+
+linked_issues=" "   # space-delimited set of issue numbers a PR points at
+
+printf 'Pull requests\n'
+if [ -z "$pr_numbers" ]; then
+  warn "no PRs carry milestone #$MS yet"
+fi
+for pr in $pr_numbers; do
+  pr_json=$(gh pr view "$pr" --repo "$REPO" --json number,title,state,milestone,closingIssuesReferences,body)
+  pr_state=$(jq -r '.state' <<<"$pr_json")
+  pr_title=$(jq -r '.title' <<<"$pr_json")
+
+  # The PR's links, else a text fallback for Closes/Fixes/Resolves [owner/repo]#N
+  # in the body.
+  ref_nums=$(pr_links "$pr_json")
+  if [ -z "$ref_nums" ]; then
+    ref_nums=$(body_refs "$pr_json" "$CLOSES")
+    [ -n "$ref_nums" ] && warn "PR #$pr links via body text only (not a registered GitHub closing link): $pr_title"
+  fi
+
+  # A technical PR (sync, pins, docs, CI — a bot's too) links no issue and needs
+  # none. Before a tag it must still be merged or closed.
+  if [ -z "$ref_nums" ]; then
+    if [ "$TAG_MODE" = 1 ] && [ "$pr_state" = OPEN ]; then
+      err "PR #$pr is OPEN — merge or close it before tagging: $pr_title"
+    else
+      ok "PR #$pr ($pr_state) → no issue (technical)"
+    fi
+    continue
+  fi
+
+  pr_ok=1
+  for ri in $ref_nums; do
+    linked_issues="$linked_issues$ri "
+    [ -z "$(feature_ms "$ri")" ] || continue   # a feature sits in its business milestone
+    ri_ms=$(issue_ms "$ri")
+    if [ "$ri_ms" != "$ms_title" ]; then
+      err "PR #$pr links issue $ri but that issue's milestone is '${ri_ms:-none}', not '$ms_title'"
+      pr_ok=0
+    fi
+  done
+
+  if [ "$TAG_MODE" = 1 ] && [ "$pr_state" != "MERGED" ]; then
+    err "PR #$pr is $pr_state — must be MERGED before tagging: $pr_title"
+  elif [ "$pr_ok" = 1 ]; then
+    ok "PR #$pr ($pr_state) → $(echo "$ref_nums" | paste -sd, -)"
+  fi
+done
+
+printf '\nIssues\n'
+if [ -z "$issue_numbers" ]; then
+  warn "no issues carry milestone #$MS"
+fi
+for is in $issue_numbers; do
+  is_state=$(jq -r --argjson n "$is" '.[] | select(.number == $n) | .state' <<<"$items")
+  case "$linked_issues" in
+    *" $REPO#$is "*) linked="linked" ;;
+    *)         linked="" ;;
+  esac
+
+  if [ "$TAG_MODE" = 1 ] && [ "$is_state" != "closed" ]; then
+    err "issue #$is is $is_state — must be closed before tagging"
+  elif [ -z "$linked" ]; then
+    warn "issue #$is ($is_state) has no PR closing it"
+  else
+    ok "issue #$is ($is_state) ← linked"
+  fi
+done
+
+printf '\n'
+if [ "$errors" -gt 0 ]; then
+  printf 'FAIL: %d error(s), %d warning(s).\n' "$errors" "$warns"
+  exit 1
+fi
+printf 'PASS: 0 errors, %d warning(s).\n' "$warns"
+[ "$TAG_MODE" = 1 ] && printf 'Milestone #%s is tag-ready.\n' "$MS"
+exit 0
diff --git a/scripts/check-linkage_test.sh b/scripts/check-linkage_test.sh
new file mode 100755
index 0000000..471dbbe
--- /dev/null
+++ b/scripts/check-linkage_test.sh
@@ -0,0 +1,348 @@
+#!/usr/bin/env bash
+#
+# check-linkage_test.sh — tests for scripts/check-linkage.sh.
+#
+# Hermetic: a stub `gh` sits first on PATH and answers, from fixture files, the
+# only calls the script makes (milestone lookup, the milestone's issues and PRs,
+# `pr view`, `issue view`), so there is no network and no credentials; REPO is
+# set so the script never asks GitHub which repository it is in. What is under
+# test is the rule the script enforces: a PR carries a milestone; it links an
+# issue only when it does an important task (Closes owner/repo#N, or Part of
+# owner/repo#N for one PR of several), and a linked issue sits in the PR's
+# milestone, whichever repository it lives in; a technical PR links none and
+# passes. Before a tag no PR may still be open and every linked one is merged.
+
+# Every `check` condition is a $(... && echo 0 || echo 1) that yields exactly one
+# token, so the unquoted substitution cannot split.
+# shellcheck disable=SC2046
+set -uo pipefail
+
+here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+script="$here/check-linkage.sh"
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+
+command -v jq >/dev/null 2>&1 || { echo "error: 'jq' not found on PATH" >&2; exit 2; }
+
+pass=0; fail=0
+ok()  { printf '  ✓ %s\n' "$1"; pass=$((pass + 1)); }
+bad() { printf '  ✗ %s\n     %s\n' "$1" "$2"; fail=$((fail + 1)); }
+check() { # description, condition-exit-code, detail
+  if [ "$2" -eq 0 ]; then ok "$1"; else bad "$1" "$3"; fi
+}
+
+# ---- the stub `gh` ---------------------------------------------------------------
+# Fixtures live in $FIXTURES: items.ndjson (the milestone's issues and PRs as REST
+# returns them), pr-<N>.json and issue-<owner>_<repo>-<N>.json. A call it does not
+# know is logged to unexpected.log, so a test sees that the script reached for
+# something else.
+bin="$tmp/bin"; mkdir -p "$bin"
+cat > "$bin/gh" <<'STUB'
+#!/usr/bin/env bash
+fx="${FIXTURES:?}"
+unexpected() { echo "gh $*" >> "$fx/unexpected.log"; echo "stub gh: unexpected call: gh $*" >&2; exit 99; }
+all="$*"
+cmd="${1:-}"; [ $# -gt 0 ] && shift
+expr=""; paginate=0; repo=""; positional=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --jq|-q)            shift; expr="${1:-}" ;;
+    --paginate|--slurp) paginate=1 ;;
+    --repo)             shift; repo="${1:-}" ;;
+    --json)             shift ;;
+    *)                  positional+=("$1") ;;
+  esac
+  shift
+done
+reply() { # file — the fixture, filtered through the --jq/-q expression when given
+  if [ -n "$expr" ]; then jq -r "$expr" "$1"; else cat "$1"; fi
+}
+case "$cmd" in
+  api)
+    path="${positional[0]:-}"
+    case "$path" in
+      "repos/$REPO/milestones?state=open&per_page=100")
+        echo '[{"number":8,"title":"v0.8.0"}]' | jq -r "${expr:-.}" ;;
+      "repos/$REPO/milestones?state=all&per_page=100")
+        echo '[{"number":7,"title":"v0.7.0"},{"number":8,"title":"v0.8.0"}]' ;;
+      "repos/$REPO")
+        echo '{"default_branch":"main"}' | jq -r "${expr:-.}" ;;
+      "repos/$REPO/milestones/8")
+        echo '{"title":"v0.8.0","state":"open"}' ;;
+      "repos/$REPO/issues?milestone=8&state=all&per_page=100")
+        [ "$paginate" = 1 ] || unexpected "$all"
+        jq -sc '[.]' "$fx/items.ndjson" ;;   # --paginate --slurp: an array of pages
+      *) unexpected "$all" ;;
+    esac ;;
+  pr)
+    [ "${positional[0]:-}" = view ] && [ "$repo" = "$REPO" ] && [ -f "$fx/pr-${positional[1]:-}.json" ] || unexpected "$all"
+    reply "$fx/pr-${positional[1]}.json" ;;
+  issue)
+    f="$fx/issue-${repo//\//_}-${positional[1]:-}.json"
+    [ "${positional[0]:-}" = view ] && [ -f "$f" ] || unexpected "$all"
+    reply "$f" ;;
+  *) unexpected "$all" ;;
+esac
+STUB
+chmod +x "$bin/gh"
+
+# ---- fixtures --------------------------------------------------------------------
+# One open milestone, v0.8.0 (#8), holding whatever a case adds to it.
+REPO=galax-io/test
+BACKLOG=galax-io/backlog
+new_case() { # name
+  fx="$tmp/fx-$1"; mkdir -p "$fx"; : > "$fx/items.ndjson"
+}
+issue_in() { # owner/repo, number, milestone title, [milestone description] — an issue the script may look up
+  jq -nc --arg ms "$3" --arg desc "${4:-}" '{milestone: (if $ms == "" then null else {title: $ms, description: $desc} end)}' \
+    > "$fx/issue-${1//\//_}-$2.json"
+}
+add_issue() { # number, state (open|closed) — an issue of this repository in v0.8.0
+  printf '{"number":%s,"state":"%s"}\n' "$1" "$2" >> "$fx/items.ndjson"
+  issue_in "$REPO" "$1" v0.8.0
+}
+pr_json() { # number, state (OPEN|CLOSED|MERGED), closing link owner/repo#N or "", body, milestone title or "", [base branch]
+  jq -nc --argjson n "$1" --arg state "$2" --arg link "$3" --arg body "$4" --arg ms "$5" --arg base "${6:-main}" '{
+    number: $n, title: "PR \($n)", state: $state, body: $body, baseRefName: $base,
+    milestone: (if $ms == "" then null else {title: $ms} end),
+    closingIssuesReferences: [$link | select(. != "")
+      | capture("^(?<owner>[^/]+)/(?<name>[^#]+)#(?<n>[0-9]+)$")
+      | {number: (.n | tonumber), repository: {name, owner: {login: .owner}}}]
+  }' > "$fx/pr-$1.json"
+}
+add_pr() { # number, state, closing link or "", [body] — a PR in v0.8.0
+  local rest=closed
+  [ "$2" = OPEN ] && rest=open
+  printf '{"number":%s,"state":"%s","pull_request":{}}\n' "$1" "$rest" >> "$fx/items.ndjson"
+  pr_json "$1" "$2" "$3" "${4:-}" v0.8.0
+}
+run() { # the script's arguments; sets $out and $rc
+  out="$(PATH="$bin:$PATH" REPO="$REPO" BACKLOG_REPO="$BACKLOG" FIXTURES="$fx" bash "$script" "$@" 2>&1)"; rc=$?
+}
+has() { grep -qF -- "$1" <<<"$out"; }
+only_known_calls() { [ ! -s "$fx/unexpected.log" ]; }
+
+echo "check-linkage.sh"
+
+# 1. audit: a PR that closes an issue of the milestone, plus a technical PR that
+#    links nothing — both are fine, and nothing is even a warning
+new_case audit-technical
+add_issue 1 open
+add_pr 2 OPEN "$REPO#1"
+add_pr 3 OPEN ""
+run
+check "audit: a technical PR without a link does not fail the audit" $([ "$rc" -eq 0 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "audit: it is listed as a technical PR" $(has '✓ PR #3 (OPEN) → no issue (technical)' && echo 0 || echo 1) "out=$out"
+check "audit: the verdict is PASS without warnings" $(has 'PASS: 0 errors, 0 warning(s)' && echo 0 || echo 1) "out=$out"
+check "audit: the linked PR is accepted" $(has "✓ PR #2 (OPEN) → $REPO#1" && echo 0 || echo 1) "out=$out"
+check "audit: the script made only the calls the stub knows" $(only_known_calls && echo 0 || echo 1) "$(cat "$fx/unexpected.log" 2>&1)"
+
+# 2. audit: a PR that closes an issue of another milestone is still an error
+new_case audit-other-milestone
+add_pr 2 OPEN "$REPO#1"
+issue_in "$REPO" 1 v0.7.0
+run
+check "audit: a link to an issue of another milestone fails the audit" $([ "$rc" -eq 1 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "audit: it names both milestones" $(has "links issue $REPO#1 but that issue's milestone is 'v0.7.0', not 'v0.8.0'" && echo 0 || echo 1) "out=$out"
+check "audit: the failing PR gets no ✓ line" $(! has '✓ PR #2' && echo 0 || echo 1) "out=$out"
+
+# 3. tag: everything is merged and closed, but a technical PR is still OPEN
+new_case tag-open
+add_issue 1 closed
+add_pr 2 MERGED "$REPO#1"
+add_pr 3 OPEN ""
+run --tag
+check "tag: an open technical PR blocks the tag" $([ "$rc" -eq 1 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "tag: it says to merge or close the PR" $(has 'PR #3 is OPEN — merge or close it before tagging' && echo 0 || echo 1) "out=$out"
+check "tag: it is the only error" $(has 'FAIL: 1 error(s)' && echo 0 || echo 1) "out=$out"
+
+# 4. tag (through --for-tag, a patch of v0.8.0): technical PRs merged or closed
+new_case tag-technical
+add_issue 1 closed
+add_pr 2 MERGED "$REPO#1"
+add_pr 3 MERGED ""
+add_pr 4 CLOSED ""
+run --for-tag v0.8.1
+check "for-tag: merged and closed technical PRs do not block the tag" $([ "$rc" -eq 0 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "for-tag: the patch maps to its minor's milestone" $(has 'Milestone: #8  v0.8.0' && echo 0 || echo 1) "out=$out"
+check "for-tag: the milestone is tag-ready" $(has 'Milestone #8 is tag-ready.' && echo 0 || echo 1) "out=$out"
+check "for-tag: the script made only the calls the stub knows" $(only_known_calls && echo 0 || echo 1) "$(cat "$fx/unexpected.log" 2>&1)"
+
+# 5. tag: a PR that links an issue must be merged, not just closed
+new_case tag-closed-linked
+add_issue 1 closed
+add_pr 2 CLOSED "$REPO#1"
+run --tag
+check "tag: a closed, unmerged PR that links an issue blocks the tag" $([ "$rc" -eq 1 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "tag: it says the PR must be merged" $(has 'PR #2 is CLOSED — must be MERGED before tagging' && echo 0 || echo 1) "out=$out"
+
+# 6. gate: a technical PR with a milestone and no issue passes
+new_case gate-technical
+pr_json 3 OPEN "" "Bumps the pins." v0.8.0
+run --pr 3
+check "gate: a technical PR without an issue passes" $([ "$rc" -eq 0 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "gate: it says no issue is needed" $(has '✓ links no issue (a technical PR needs none)' && echo 0 || echo 1) "out=$out"
+check "gate: the script made only the calls the stub knows" $(only_known_calls && echo 0 || echo 1) "$(cat "$fx/unexpected.log" 2>&1)"
+
+# 7. gate: a PR without a milestone fails, issue or not
+new_case gate-no-milestone
+pr_json 3 OPEN "" "" ""
+run --pr 3
+check "gate: a PR without a milestone fails" $([ "$rc" -eq 1 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "gate: it says to assign one" $(has '✗ no milestone' && echo 0 || echo 1) "out=$out"
+
+# 8. gate: Closes for an issue of the same milestone passes
+new_case gate-closes
+pr_json 3 OPEN "$REPO#1" "Closes #1" v0.8.0
+issue_in "$REPO" 1 v0.8.0
+run --pr 3
+check "gate: closing an issue of the same milestone passes" $([ "$rc" -eq 0 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "gate: it names the link" $(has "✓ links $REPO#1 (same milestone)" && echo 0 || echo 1) "out=$out"
+
+# 9. gate: Closes for an issue of another milestone fails
+new_case gate-closes-other
+pr_json 3 OPEN "$REPO#1" "Closes #1" v0.8.0
+issue_in "$REPO" 1 v0.7.0
+run --pr 3
+check "gate: closing an issue of another milestone fails" $([ "$rc" -eq 1 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "gate: it names both milestones" $(has "✗ links $REPO#1 but its milestone is \"v0.7.0\", not \"v0.8.0\"" && echo 0 || echo 1) "out=$out"
+
+# 10. gate: Part of an issue in another repository is looked up there
+new_case gate-part-of
+pr_json 3 OPEN "" "Part of $BACKLOG#30" v0.8.0
+issue_in "$BACKLOG" 30 v0.8.0
+run --pr 3
+check "gate: Part of an issue in another repository passes" $([ "$rc" -eq 0 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "gate: the issue is looked up in its own repository" $(has "✓ links $BACKLOG#30 (same milestone)" && echo 0 || echo 1) "out=$out"
+check "gate: the script made only the calls the stub knows" $(only_known_calls && echo 0 || echo 1) "$(cat "$fx/unexpected.log" 2>&1)"
+
+# 11. gate: off the default branch GitHub links no Closes, so merging would not close
+#     the issue — it fails, the colon form too
+new_case gate-unregistered
+pr_json 3 OPEN "" "Closes: $BACKLOG#30" v0.8.0 feat/stack
+run --pr 3
+check "gate: a Closes off the default branch fails" $([ "$rc" -eq 1 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "gate: it names the base branch and the default one" $(has "✗ the body closes $BACKLOG#30, but the PR targets feat/stack, not main" && echo 0 || echo 1) "out=$out"
+check "gate: the script made only the calls the stub knows" $(only_known_calls && echo 0 || echo 1) "$(cat "$fx/unexpected.log" 2>&1)"
+
+# 12. gate: a keyword inside another word is not a link
+new_case gate-inside-word
+pr_json 3 OPEN "" "Drops the prefix #5 and the counterpart of #6." v0.8.0
+run --pr 3
+check "gate: \"prefix #5\" and \"counterpart of #6\" are not links" $([ "$rc" -eq 0 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "gate: the PR counts as technical" $(has '✓ links no issue' && echo 0 || echo 1) "out=$out"
+
+# 13. gate: on the default branch, a Closes GitHub did not link names no issue
+#     (here a pull request) — the PR is technical
+new_case gate-closes-pr
+pr_json 3 OPEN "" "Fixes #190's typo." v0.8.0
+run --pr 3
+check "gate: an unlinked Fixes on the default branch passes" $([ "$rc" -eq 0 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "gate: the PR counts as technical" $(has '✓ links no issue' && echo 0 || echo 1) "out=$out"
+
+# 14. gate: "part of" in prose is not the Part of convention
+new_case gate-prose-part-of
+pr_json 3 OPEN "" "Small cleanup that is part of #190's follow-up." v0.8.0
+run --pr 3
+check "gate: \"part of #190\" in prose is not a link" $([ "$rc" -eq 0 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "gate: no issue is looked up" $(only_known_calls && echo 0 || echo 1) "$(cat "$fx/unexpected.log" 2>&1)"
+
+# 15. gate: a registered closing link to an issue in another repository
+new_case gate-closes-backlog
+pr_json 3 OPEN "$BACKLOG#30" "Closes $BACKLOG#30" v0.8.0
+issue_in "$BACKLOG" 30 v0.8.0
+run --pr 3
+check "gate: closing an issue in another repository passes" $([ "$rc" -eq 0 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "gate: the issue is looked up in its own repository" $(has "✓ links $BACKLOG#30 (same milestone)" && echo 0 || echo 1) "out=$out"
+
+# 16. gate: without a milestone, a linked issue is not "the same milestone"
+new_case gate-no-milestone-link
+pr_json 3 OPEN "$REPO#1" "Closes #1" ""
+issue_in "$REPO" 1 ""
+run --pr 3
+check "gate: a PR without a milestone still fails" $([ "$rc" -eq 1 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "gate: the link gets no ✓" $(! has '✓ links' && has "- links $REPO#1" && echo 0 || echo 1) "out=$out"
+
+# 17. audit: a Closes in the body that GitHub did not register is a warning, and
+#     the issue still counts as linked; "part of" in prose links nothing
+new_case audit-text
+add_issue 1 open
+add_pr 2 OPEN "" "Closes #1"
+add_pr 3 OPEN "" "Small cleanup that is part of #190's follow-up."
+run
+check "audit: an unregistered Closes does not fail the audit" $([ "$rc" -eq 0 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "audit: it is reported as a warning" $(has '! PR #2 links via body text only' && echo 0 || echo 1) "out=$out"
+check "audit: the issue counts as linked" $(has '✓ issue #1 (open) ← linked' && echo 0 || echo 1) "out=$out"
+check "audit: prose \"part of\" leaves the PR technical" $(has '✓ PR #3 (OPEN) → no issue (technical)' && echo 0 || echo 1) "out=$out"
+
+BUSINESS='Release: business'
+
+# 18. gate: a PR with a version milestone may link a feature of the backlog; the feature
+#     sits in a business milestone of its own, so the milestones need not match
+new_case gate-feature
+pr_json 3 OPEN "" "Part of $BACKLOG#30" v0.8.0
+issue_in "$BACKLOG" 30 'M1 — first run' "$BUSINESS"
+run --pr 3
+check "gate: Part of a backlog feature in a business milestone passes" $([ "$rc" -eq 0 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "gate: it names the business milestone" $(has "✓ links $BACKLOG#30 (feature of business milestone \"M1 — first run\")" && echo 0 || echo 1) "out=$out"
+check "gate: the script made only the calls the stub knows" $(only_known_calls && echo 0 || echo 1) "$(cat "$fx/unexpected.log" 2>&1)"
+
+# 19. gate: the marker may sit among other lines of the milestone description
+new_case gate-feature-multiline
+pr_json 3 OPEN "" "Part of $BACKLOG#30" v0.8.0
+issue_in "$BACKLOG" 30 'M1 — first run' $'First real run of the process.\nRelease: business\nDue: autumn'
+run --pr 3
+check "gate: the marker on its own line of a longer description counts" $([ "$rc" -eq 0 ] && echo 0 || echo 1) "rc=$rc out=$out"
+
+# 20. gate: a backlog issue in an ordinary milestone is not a feature
+new_case gate-backlog-plain
+pr_json 3 OPEN "" "Part of $BACKLOG#31" v0.8.0
+issue_in "$BACKLOG" 31 'v0.7.0' 'Tooling of the backlog itself.'
+run --pr 3
+check "gate: a backlog issue in an ordinary milestone still has to match" $([ "$rc" -eq 1 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "gate: it names both milestones" $(has "✗ links $BACKLOG#31 but its milestone is \"v0.7.0\", not \"v0.8.0\"" && echo 0 || echo 1) "out=$out"
+
+# 21. gate: the marker only counts in the backlog repository
+new_case gate-marker-elsewhere
+pr_json 3 OPEN "$REPO#1" "Closes #1" v0.8.0
+issue_in "$REPO" 1 'M1 — first run' "$BUSINESS"
+run --pr 3
+check "gate: the marker in another repository does not make a feature" $([ "$rc" -eq 1 ] && echo 0 || echo 1) "rc=$rc out=$out"
+
+# 22. gate: a backlog issue without a milestone is not a feature
+new_case gate-feature-no-milestone
+pr_json 3 OPEN "" "Part of $BACKLOG#32" v0.8.0
+issue_in "$BACKLOG" 32 ""
+run --pr 3
+check "gate: a backlog issue without a milestone fails" $([ "$rc" -eq 1 ] && echo 0 || echo 1) "rc=$rc out=$out"
+
+# 23. gate: the PR itself still needs its version milestone
+new_case gate-feature-no-pr-milestone
+pr_json 3 OPEN "" "Part of $BACKLOG#30" ""
+issue_in "$BACKLOG" 30 'M1 — first run' "$BUSINESS"
+run --pr 3
+check "gate: a feature link does not replace the PR's own milestone" $([ "$rc" -eq 1 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "gate: it says to assign one" $(has '✗ no milestone' && echo 0 || echo 1) "out=$out"
+check "gate: the feature link is still reported" $(has "✓ links $BACKLOG#30 (feature of business milestone" && echo 0 || echo 1) "out=$out"
+
+# 24. audit: a PR of the milestone that links a backlog feature is not an error
+new_case audit-feature
+add_issue 1 open
+add_pr 2 OPEN "" "Part of $BACKLOG#30"
+issue_in "$BACKLOG" 30 'M1 — first run' "$BUSINESS"
+run
+check "audit: linking a backlog feature passes the audit" $([ "$rc" -eq 0 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "audit: the PR is listed with its link" $(has "✓ PR #2 (OPEN) → $BACKLOG#30" && echo 0 || echo 1) "out=$out"
+
+# 25. tag: a merged PR of a feature does not block the tag of its repository
+new_case tag-feature
+add_issue 1 closed
+add_pr 2 MERGED "$REPO#1"
+add_pr 3 MERGED "" "Part of $BACKLOG#30"
+issue_in "$BACKLOG" 30 'M1 — first run' "$BUSINESS"
+run --tag
+check "tag: a merged PR that links a feature does not block the tag" $([ "$rc" -eq 0 ] && echo 0 || echo 1) "rc=$rc out=$out"
+check "tag: the milestone is tag-ready" $(has 'Milestone #8 is tag-ready.' && echo 0 || echo 1) "out=$out"
+
+printf '\n%d passed, %d failed\n' "$pass" "$fail"
+[ "$fail" -eq 0 ]