@mokoconsulting/mokoabs-mcp 0.0.0-stage → 4.0.2

package/.mokogit/workflows/auto-release.yml

@@ -0,0 +1,1787 @@
+# Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# FILE INFORMATION
+# DEFGROUP: MokoGIT.Workflow
+# INGROUP: MokoCLI.Release
+# REPO: https://git.mokoconsulting.tech/MokoConsulting/Template-Generic
+# PATH: /.mokogit/workflows/auto-release.yml
+# VERSION: 07.24.00
+# BRIEF: NEW (07.24.00): npmjs.org publish now FAILS LOUD (::error:: + exit $rc) on an AUTHORIZATION error (404 "not in this registry" / 401 / 403 / ENEEDAUTH / EOTP) instead of swallowing EVERY failure as a non-failing ::warning:: — a missing-scope / unauthorized / revoked / expired NPM_TOKEN previously hid behind a green release fleet-wide (the "secondary registry, not failing the run" catch masked a 404 PUT, which is exactly how npm reports an unauthorized scoped write; CI had in fact NEVER successfully published any MCP package to npmjs while every run reported success). Transient/5xx/network failures still stay a non-failing ::warning:: (npmjs is the SECONDARY mirror; the MokoGIT registry is primary and already hard-fails), and an unset NPM_TOKEN still skips cleanly — so repos that do not publish to npmjs are 100% unaffected. PREVIOUS (07.23.00): "Vendor PHP dependencies (build-time)" added to BOTH publish legs (promote-rc + stable) — this workflow had NO build-time composer vendoring at all, so any component declaring runtime PHP deps via a sub-package composer.json (vendor-dir admin/vendor, e.g. mPDF in MokonyxCRM/MokonyxCRMDCM) shipped its rc/stable zip WITHOUT admin/vendor while the component manifest lists <folder>vendor</folder> — JInstaller then aborts the ENTIRE package install on-site ("File does not exist [ROOT][TMP]/.../admin/vendor" → "Failed to copy administrator files"). The step mirrors pre-release.yml 07.15.00: no-op without a sub-package composer.json; provisions ext-gd when missing (the release runners' php-cli lacks it, which failed mpdf dependency RESOLUTION outright); verifies the CONFIGURED vendor-dir (composer config vendor-dir) materialized autoload.php; FAILS the build loud when vendoring fails for a package whose manifest ships <folder>vendor</folder> (a green build with an install-bricking artifact is strictly worse than a red build); fail-soft warning for packages whose manifests do not reference vendor/. Runs before `moko publish` (release_publish.php → release_package.php zips the plain working tree; vendor/ was never excluded — the tree simply never had it in CI). PREVIOUS (07.22.00): #498 — the #469 SRC_DIR gate no longer self-traps, and the fast-merge guard is MINOR-identity aware (fixes stable version never advancing; MokoCLI stuck re-publishing v10.20.00). (1) The gate read SRC_DIR with grep|sed, capturing the LITERAL unexpanded `$(shell …)` from the fleet-standard `SRC_DIR := $(shell [ -d src ] && echo src || echo source)` — an unmatchable directory that forced should_bump=false on EVERY push even when source changed. It now resolves SRC_DIR via `make --eval` expansion, falls back to the grep|sed read only if make is unavailable, nulls out a still-unexpanded `$(...)`/backtick value, and treats a declared-but-NONEXISTENT SRC_DIR (repos with code in cli/lib/bin, not src/source) as the non-source denylist fallback instead of an unmatchable INCLUSION prefix. (2) The "Guarantee monotonic release version (fast-merge bump guard)" compared the FULL version, so dev's per-merge PATCH bumps (10.20.00→10.20.04) fooled it into "normal path, no heal" and it re-published the already-released vMAJOR.MINOR.00. It now compares the MINOR identity (MAJOR.MINOR), so a fast dev→stable merge with no promote-rc cuts a new MINOR. Fleet-wide release-semantics change — validate on one repo before syncing. PREVIOUS (07.21.00): #469 — gate the version BUMP on whether the push touched the Makefile SRC_DIR. The former non-code paths-ignore denylist on the push trigger is REMOVED: a docs/workflow/sample push no longer skips the pipeline, it now RUNS in no-bump "update the existing stable release in place" mode (re-stamps the UNCHANGED current version via the existing `moko publish --bump none --no-commit`, refreshes notes/assets, no version advance, no new vNN tag). A new early step "Resolve SRC_DIR bump gate (#469)" (id: srcgate) decides should_bump: (1) ELECTRON (file-detected) or opt-out vars.RELEASE_SRCDIR_GATE=off -> BYPASS, always bump as today (electron has NO source dir, so a naive SRC_DIR test would never bump — a release-breaking trap); (2) else SRC_DIR is REQUIRED — a non-electron repo with no resolvable SRC_DIR FAILS LOUD (::error:: + exit 1), never silently never-bump; (3) else diff the push range (github.event.before..GITHUB_SHA, with a HEAD^1 / merge-base fallback) intersected with ${SRC_DIR}/ — source hit -> should_bump=true, none -> should_bump=false. workflow_dispatch always bumps. The self-heal monotonic bump + the new vNN semver tag are now gated on should_bump!='false' so no-bump mode keeps the version PUT; the publish + "Update release notes and reconcile changelog" (channel-pointer resolution) run on BOTH paths to refresh the current release. Loop-safety is unchanged: the job if: still re-checks [skip ci]/[skip sync], so the workflow's own commits never re-trigger. Fleet-wide release-semantics change — validate on one repo before syncing. PREVIOUS (07.20.00): the dev/promote bump + release steps now name the per-run token env var GITHUB_TOKEN (was the misleadingly-named MOKOGIT_TOKEN; the VALUE was always ${{ github.token }}). All token use in this workflow is SAME-REPO (release API, the release_bump_dev dev base bump, pushes to its own repo) — the org MOKOGIT_TOKEN secret is not referenced here. Naming-only; no behavior change. Mirrors the pre-release.yml fix (MokoGIT#1721). PREVIOUS: NEW (07.19.00): #1621 Phase 6 / .mokogit-private#76 — resolve the CURRENT stable release by its CHANNEL POINTER, not by a fixed tag_name=stable. Under version-primary releases (a release is born with the immutable tag_name=vNN and `stable`/`rc` attached as movable is_channel tags), GET /releases/tags/stable no longer resolves the current stable release, which would break two steps that read "the last released version". Both now call GET /repos/{owner}/{repo}/releases/channel/stable (#1702 — resolves whichever release the `stable` channel points at via ReleaseStreamMap) with a GRACEFUL FALLBACK to the legacy GET /releases/tags/stable for forges predating #1702 (the channel route 404s pre-rollout and the rolling `stable` tag still exists). (1) The monotonic-version guard ("Guarantee monotonic release version") resolves ROLLING_LAST by parsing the same `VERSION: NN.NN.NN` out of the channel-resolved release NAME. (2) "Update release notes and reconcile changelog" resolves the stable RELEASE_ID + VERSION the same channel-first way. The #386 integrity gate is UNCHANGED (it already keys off the immutable vNN version tag). SEQUENCING unchanged: do NOT enable in prod until #1702 server support is on stable/prod; works pre-#1702 via the fallback. PREVIOUS (07.18.00): #1621 Phase 6 — version/* BRANCHES retired in favor of dual-tagged version RELEASES. REMOVED three now-redundant steps: "Step 12: Create version branch from main", "Step 13: Prune superseded-major version branches", and "Advance rolling channel tag via git". A release's permanent version identity is now the git tag v<version>, attached by the publish as a MOVABLE channel tag on the dual-tagged release (MokoCLI release_publish -> release_create channel_tags[]/update_stream; the forge attaches/moves the tag at the release commit via AttachChannelTag server-side) — so a new cut is born dual-tagged (rolling `stable`/`release-candidate` primary tag + permanent v<version> channel tag) and the channel tag MOVES onto the new release instead of a new version/* branch being created. The rolling `stable` tag is still pinned by release_create forceTagRef() (#808), so the "Advance rolling channel tag" force-push was redundant. KEPT UNCHANGED: "Create semver tag" (v<version>), the #386 integrity gate (still resolves tags/stable to the built commit), and the monotonic guard (still reads the stable release name VERSION: NN.NN.NN). Pruning EXISTING version/* branches is a SEPARATE one-time manual reconcile — not done here. SEQUENCING: do NOT enable in prod until the #1621 SERVER channel_tags support is on stable/prod. PREVIOUS (07.17.00): Setup MokoCLI tools no longer installs a STALE mokocli during the registry publish-lag window (#1671). After the fresh registry install, the step now compares the installed /tmp/mokocli PROJECT_VERSION against the /opt/mokocli failsafe and PREFERS whichever is NEWER (sort -V), and the opportunistic /opt refresh is gated to only move FORWARD (never downgrade /opt when it is the newer, just-deployed copy). Backward-compatible: runners with no /opt/mokocli use the registry copy exactly as before. PREVIOUS (07.16.00): release-integrity + dev-channel fixes. (1) A new pre-publish "no stale (pre-merge) tree" guard (#428/MokoCLI#901) hard-FAILS the release if the triggering GITHUB_SHA is an ANCESTOR of the current branch tip (a concurrent merge landed mid-run) -- otherwise a green, version-bumped release silently ships old code missing that merge (reproduced: built ef8c1a5d while tip was 2740342). Fail-open on any unresolved/replica-lagged tip so a good release is never falsely blocked. Complements the mokocli engine assertion (packaged-tree == GITHUB_SHA), which cannot see that GITHUB_SHA itself trails the tip. (2) The "Post-release: Reset dev version" safety-net (#309/MokoCLI#900) no longer swallows failure: a failed dev-advance now emits ::error:: + a job-summary block (dev-channel would trail stable), and a SUCCESSFUL advance dispatches pre-release.yml (development) to actually publish the leading dev build -- the advance commit is [skip ci]+paths-ignored and never auto-fires. Stays green (continue-on-error) since stable already published. NEW (07.15.00): the rolling stable channel tag is now advanced via a git force-push BEFORE the #386 integrity gate. MokoGIT's tags API 405s on the release-attached `stable` tag, so release_publish.php could not move it ("Could not pin tag stable ... HTTP 405") and every Joomla/electron stable cut left the tag lagging the freshly-built commit -- red-failing a correct release on the integrity gate. A new step git-force-pushes refs/tags/stable to the built HEAD (force-push allowlist -- the same escape hatch the rc BRANCH pin already uses), so the gate passes and no manual tag repoint is needed. PREVIOUS (07.14.00): integrity gate #386 no longer false-fails. It compared the published tag against GITHUB_SHA (the triggering commit), but the publish step commits the CHANGELOG entry ("build NN.NN.NN [skip ci]") and mokocli pins the channel tag + semver tag to that POST-PUBLISH HEAD -- so every cut whose CHANGELOG wasn't pre-seeded on dev (e.g. a version set straight on the release branch) diverged by one commit and red-failed a correct release. The gate now compares against the actual built/published HEAD (git rev-parse HEAD, falling back to GITHUB_SHA), which equals what the tag is pinned to in both the commit and no-commit cases while still catching a tag pinned to a commit we did NOT build; the semver tag is pinned to the same built HEAD for consistency. PREVIOUS (07.13.00): RC is ON-DEMAND ONLY. The `pull_request` trigger (RC-preview on a PR to main/stable) is REMOVED and the promote-rc job now runs solely on workflow_dispatch action=promote-rc. Only dev + stable release automatically (dev via pre-release.yml push->dev; stable via the push->main release job here); alpha/beta/rc never auto-cut. PREVIOUS (07.12.00): electron repos create NO release on ANY channel (RC enabled=false + stable publish/tag/notes/integrity guarded on is_electron; opt back in with vars.ELECTRON_CI_BUILD=true) and build NO installer in CI — always built locally + uploaded manually; the dev/promote version BUMP still runs. Template-Generic #390. NEW (07.11.00): the electron installer build/attach steps (electron-builder via Wine/Xvfb) are gated to MANUAL workflow_dispatch only (`&& github.event_name == 'workflow_dispatch'`). An automatic push no longer auto-builds electron installers (heavy ~90m, runner-fragile — OOM/Wine-zombie; migrating to mokocli ElectronPackager, MokoCLI #756/#758). The version bump, CHANGELOG, tag and npm publish STILL run on push — only the electron installer is skipped and pushed MANUALLY via dispatch. Non-electron platforms (joomla/go/npm) unaffected. Template-Generic #390. Universal build & release - BUMP-ON-DEV: base version + CHANGELOG promoted on dev pre-promotion (promote-rc), main publishes --bump none --no-commit so it never diverges from dev. MokoCLI build agent (moko publish). NEW (07.06.00): npm stable publishing ABSORBED here from Template-NPM's retired npm-publish.yml as npm-gated dual-registry steps (MokoGIT registry via per-run token + npmjs.org best-effort), replacing the former npm-publish.yml dispatch. No-Makefile repos SKIP the release job gracefully (green) instead of failing. Conflict-marker scan reads git-tracked files only (git ls-files | xargs grep) so vendored/generated trees can't false-match. NEW (07.07.00): npm stamp normalizes the zero-padded Makefile PROJECT_VERSION (NN.NN.NN) to strict semver via awk before `npm version`, and an unstampable version now HARD-FAILS instead of silently keeping the old package.json version (#382). NEW (07.00.00): `moko assets:optimize` artifact-time step added before publish (graceful-skip on non-asset repos); Setup MokoCLI tools makes the fresh `moko` executable + first on PATH to fix exit-126 (mokocli #650).
+#
+# +=======================================================================+
+# |              UNIVERSAL BUILD & RELEASE PIPELINE                        |
+# +=======================================================================+
+# |                                                                        |
+# |  Native-manifest platform detect (joomla|generic) drives branching.  |
+# |                                                                        |
+# |  Platform-specific:                                                    |
+# |    joomla:   XML manifest, type-prefixed packages                      |
+# |    generic:  README-only, no update stream                             |
+# |                                                                        |
+# +=======================================================================+
+
+name: "Universal: Build & Release"
+
+on:
+  # Stable release on every PUSH to main (a merged promotion) -- the same
+  # push-based principle as pre-release's dev-channel build. A push trigger is
+  # race-free vs the old pull_request:closed, which could miss its run when this
+  # workflow file re-synced from the template concurrently with the merge.
+  # Loop-safe: the workflow's own commits to main carry [skip ci]/[skip sync]
+  # (mokocli's build commit + the changelog-promote commit), and the release job's
+  # if: re-checks [skip ci]/[skip sync], so a self-push never re-triggers a release.
+  # #469: the former non-code paths-ignore denylist (which SKIPPED docs/CI-only
+  # pushes entirely) is REMOVED. A docs/workflow/sample push must now RUN the
+  # pipeline in no-bump "update existing release" mode (refresh notes/assets on the
+  # current stable release, no version bump, no new vNN tag) rather than be dropped.
+  # The bump-vs-no-bump decision is made in-job by the SRC_DIR-diff gate (the
+  # "Resolve SRC_DIR bump gate" step: steps.srcgate.outputs.should_bump), not by a
+  # trigger-level path filter — so no release signal is ever lost. Loop-safety is
+  # still fully covered by the [skip ci]/[skip sync] re-checks in the job if:.
+  push:
+    branches:
+      - main
+      - stable
+  workflow_dispatch:
+    inputs:
+      action:
+        description: 'Action to perform'
+        required: false
+        type: choice
+        default: release
+        options:
+          - release
+          - promote-rc
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  MOKOGIT_URL: ${{ vars.MOKOGIT_URL || 'https://git.mokoconsulting.tech' }}
+  GIT_ORG: ${{ vars.MOKOGIT_ORG || github.repository_owner }}
+  GIT_REPO: ${{ vars.MOKOGIT_REPO || github.event.repository.name }}
+
+permissions:
+  contents: write
+  pull-requests: write
+  packages: write
+
+concurrency:
+  # Serialise the release path per CHANNEL BRANCH (ref), not per commit (#423):
+  # a rapid sequence of DISTINCT stable commits shares one group, so the newest
+  # push SUPERSEDES older *queued* releases (concurrency keeps one running + only
+  # the latest pending, cancelling older pending runs) -- avoiding a full
+  # build+publish+deploy of a commit that has already been superseded. Same-commit
+  # push / schedule / workflow_dispatch still collapse (same ref), preserving the
+  # fleet sync-burst de-dup. cancel-in-progress stays FALSE so a publish already in
+  # progress is NEVER cancelled (cancelling mid-publish could leave a half-created
+  # release -- npmjs published but Gitea-registry publish dropped); only *pending*
+  # superseded runs are dropped. Mirrors pre-release.yml's per-ref grouping.
+  group: auto-release-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  # -- On-demand RC promote (workflow_dispatch action=promote-rc) --------------------
+  # RC is NO LONGER auto-built on a PR to main/stable. A release-candidate is cut ONLY
+  # when a human runs this workflow with action=promote-rc. Only dev + stable release
+  # automatically (dev via pre-release.yml push->dev; stable via the push->main job below).
+  promote-rc:
+    name: Promote to RC
+    # LITERAL runner label — see #366/#134. Gitea does not resolve the
+    # `${{ vars.RELEASE_RUNNER_LABEL || 'release' }}` fallback for an unset var in
+    # `runs-on`, so the job aborts with no runner. The registered label is `release`.
+    runs-on: release
+    # Own-repo writes: move rc + create release (contents:write), and dispatch
+    # deploy-rc (actions:write) -- all via the per-repo github.token.
+    permissions:
+      contents: write
+      pull-requests: write
+      actions: write
+    # Skip on template repos (Template-*) -- they scaffold other repos and do not release.
+    # RC is ON-DEMAND ONLY: this job runs solely on a manual workflow_dispatch with
+    # action=promote-rc. The former auto-trigger (PR dev->main/stable) was removed so a
+    # promotion PR no longer auto-cuts an RC (and template-sync PRs can't spawn an
+    # RC-promote storm). A human explicitly chooses to run it.
+    if: >-
+      github.event.repository.name != '.vault' &&
+      github.event_name == 'workflow_dispatch' &&
+      inputs.action == 'promote-rc'
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          token: ${{ github.token }}
+          fetch-depth: 1
+          submodules: false
+
+      # #1672: the actions/checkout above intermittently aborts at step-0 under
+      # release-time load on the shared `release` runners (git fetch timeout /
+      # workspace contention). A plain re-run usually gets a clean checkout, so the
+      # fault is transient/environmental, not code. This fallback fires ONLY when
+      # the checkout above failed (step-level `if: failure()` — a LITERAL, never a
+      # continue-on-error expression, which Gitea would discard the whole workflow
+      # over) and re-materialises the workspace via a bounded 3-attempt git clone
+      # with backoff. It does NOT mask real failures: a genuinely bad ref makes all
+      # three attempts fail and the step exits 1 (loud). Independent step — no
+      # needs:+always() fan-in (which act_runner strands).
+      - name: "Checkout fallback (retry transient flake) (#1672)"
+        if: failure()
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          set -u
+          TOK="$(printf '%s' "$GITHUB_TOKEN" | tr -d '[:space:]')"; echo "::add-mask::$TOK"
+          SERVER="${GITHUB_SERVER_URL:-https://git.mokoconsulting.tech}"
+          CLONE_URL="https://x-access-token:${TOK}@${SERVER#https://}/${GITHUB_REPOSITORY}.git"
+          REF="${GITHUB_SHA:-${GITHUB_REF_NAME:-}}"
+          echo "Retrying checkout of ${GITHUB_REPOSITORY}@${REF:-<HEAD>} into ${GITHUB_WORKSPACE}"
+          ok=0
+          for attempt in 1 2 3; do
+            rm -rf "${GITHUB_WORKSPACE:?}/.git" 2>/dev/null || true
+            find "${GITHUB_WORKSPACE}" -mindepth 1 -maxdepth 1 -exec rm -rf {} + 2>/dev/null || true
+            if git clone --depth 1 "$CLONE_URL" "${GITHUB_WORKSPACE}" \
+               && { [ -z "$REF" ] || git -C "${GITHUB_WORKSPACE}" fetch --depth 1 origin "$REF" && git -C "${GITHUB_WORKSPACE}" checkout -f FETCH_HEAD; }; then
+              ok=1; echo "Fallback checkout succeeded on attempt ${attempt}."; break
+            fi
+            echo "::warning::Fallback checkout attempt ${attempt} failed; backing off $((attempt * 5))s"
+            sleep $((attempt * 5))
+          done
+          if [ "$ok" != "1" ]; then
+            echo "::error::Checkout failed after 3 retry attempts (#1672) — this is not a transient flake, failing loudly."
+            exit 1
+          fi
+
+      - name: "Require Makefile (auto-release gate)"
+        # RC promotion is part of auto-release; it must also refuse to run without
+        # a Makefile (see the release job for rationale). Post-checkout step because
+        # a job-level if: cannot inspect the workspace.
+        run: |
+          if [ ! -f Makefile ] && [ ! -f makefile ] && [ ! -f GNUmakefile ]; then
+            echo "::error::auto-release (RC promote) requires a Makefile at the repository root -- none found. Aborting."
+            echo "## RC promote blocked: no Makefile at repo root" >> "$GITHUB_STEP_SUMMARY"
+            exit 1
+          fi
+          echo "Makefile present -- RC promote may proceed."
+
+      - name: Setup MokoCLI tools
+        run: |
+          # Install mokocli FRESH from the MokoGIT Composer registry on every run
+          # (PRIMARY) so CI always uses the latest published version. /opt/mokocli is
+          # a FAILSAFE only — its refresh unit (mokocli-sync.service) is disabled, so
+          # the on-disk snapshot rots and must NOT be preferred. Registry path
+          # /api/packages/** is anon-allowlisted (no GITHUB_TOKEN); it serves a dist
+          # zip (no git clone). --no-install: mokocli self-bootstraps via bundled lib/
+          # + a fallback PSR-4 autoloader (native ext-curl), so no vendor/ is needed.
+          if ! command -v composer > /dev/null 2>&1; then
+            sudo apt-get update -qq && sudo apt-get install -y -qq php-cli php-mbstring php-xml php-zip php-curl composer > /dev/null 2>&1
+          fi
+          rm -rf /tmp/mokocli
+          REG='{"type":"composer","url":"https://git.mokoconsulting.tech/api/packages/MokoConsulting/composer"}'
+          if composer create-project --no-install --no-interaction --no-progress --quiet \
+               --repository="${REG}" mokoconsulting/mokocli /tmp/mokocli >/dev/null 2>&1 \
+             && [ -f /tmp/mokocli/cli/version_bump.php ]; then
+            echo "Installed mokocli fresh from the Composer registry (primary)"
+            # #1671: registry-publish LAG race. The registry install "succeeds" but can
+            # serve the PREVIOUS package for ~tens of seconds after a MokoCLI release
+            # (publish finishes AFTER the release run reports success). Meanwhile the
+            # /opt/mokocli deploy (pull-timer) may already carry the just-released,
+            # NEWER engine. So instead of blindly using the registry copy, compare the
+            # two on-disk versions and PREFER whichever is newer. The Makefile
+            # PROJECT_VERSION is the version source of truth and ships in both the
+            # composer dist and /opt/mokocli. Backward-compatible: with no /opt/mokocli
+            # (most consumer runners), the registry copy is used exactly as before.
+            mk_ver() { sed -n 's/^[[:space:]]*PROJECT_VERSION[[:space:]]*:*=[[:space:]]*//p' "$1" 2>/dev/null | head -n1 | tr -d '[:space:]'; }
+            ver_newer() { [ "$1" != "$2" ] && [ "$(printf '%s\n%s\n' "$1" "$2" | sort -V | tail -n1)" = "$1" ]; }
+            REG_VER="$(mk_ver /tmp/mokocli/Makefile)"
+            OPT_VER="$(mk_ver /opt/mokocli/Makefile)"
+            MOKO_ROOT=/tmp/mokocli
+            if [ -f /opt/mokocli/cli/version_bump.php ] && [ -n "$OPT_VER" ] && [ -n "$REG_VER" ] \
+               && ver_newer "$OPT_VER" "$REG_VER"; then
+              echo "::notice::/opt/mokocli (${OPT_VER}) is newer than the registry copy (${REG_VER}) — using /opt (#1671 publish-lag race)."
+              MOKO_ROOT=/opt/mokocli
+            else
+              echo "Using registry copy (${REG_VER:-unknown}); /opt/mokocli=${OPT_VER:-none}"
+            fi
+            echo "MOKO_CLI=${MOKO_ROOT}/cli" >> $GITHUB_ENV
+            # #650: make the chosen moko executable + FIRST on PATH so bare `moko`
+            # never resolves to a stale/non-executable copy (exit 126).
+            for d in bin cli; do
+              if [ -f "${MOKO_ROOT}/$d/moko" ]; then
+                # #1263 defense-in-depth: strip CR bytes so a CRLF-tainted registry
+                # dist or rotted /opt snapshot can't yield `/usr/bin/env: 'php\r'`
+                # (exit 127). tr interprets \r as a real CR (unlike portable sed).
+                # /opt may be root-owned — write via a temp file + sudo when needed.
+                if tr -d '\r' < "${MOKO_ROOT}/$d/moko" > "/tmp/moko.lf" 2>/dev/null; then
+                  if cp "/tmp/moko.lf" "${MOKO_ROOT}/$d/moko" 2>/dev/null; then :; \
+                  else sudo cp "/tmp/moko.lf" "${MOKO_ROOT}/$d/moko" 2>/dev/null || true; fi
+                  rm -f "/tmp/moko.lf"
+                fi
+                chmod +x "${MOKO_ROOT}/$d/moko" 2>/dev/null || sudo chmod +x "${MOKO_ROOT}/$d/moko" 2>/dev/null || true
+                echo "${MOKO_ROOT}/$d" >> "$GITHUB_PATH"
+              fi
+            done
+            sudo chmod +x /opt/mokocli/*/moko 2>/dev/null || true
+            # Opportunistically refresh the /opt failsafe from this fresh copy when it
+            # differs — keeps the disabled-sync snapshot current so the fallback is
+            # never far behind. Best-effort: needs sudo, gated on a diff to avoid
+            # fleet-wide churn, never fails the job. #1671: only refresh FORWARD — skip
+            # when /opt is the newer copy we just chose, so we never downgrade it.
+            if [ "$MOKO_ROOT" = /tmp/mokocli ] && command -v sudo >/dev/null 2>&1 && [ -d /opt/mokocli ] \
+               && ! cmp -s /tmp/mokocli/cli/version_reset_dev.php /opt/mokocli/cli/version_reset_dev.php 2>/dev/null; then
+              sudo cp -a /tmp/mokocli/. /opt/mokocli/ 2>/dev/null \
+                && echo "Refreshed /opt/mokocli failsafe from the fresh registry copy" \
+                || echo "  (/opt failsafe refresh skipped — no sudo/perms)"
+            fi
+          elif [ -f /opt/mokocli/cli/version_bump.php ]; then
+            echo "::warning::Registry install failed — using /opt/mokocli FAILSAFE (may be stale)"
+            echo "MOKO_CLI=/opt/mokocli/cli" >> $GITHUB_ENV
+          else
+            echo "::error::mokocli unavailable: registry install failed and no /opt/mokocli failsafe present"
+            exit 1
+          fi
+
+      - name: "Bump base version + promote changelog on dev (pre-promotion)"
+        env:
+          # Contents-API writes to protected dev need the admin-bypass token
+          # (github.token cannot bypass branch protection). Same token/primitive
+          # as version_reset_dev.php and the changelog persist below (#510).
+          GITHUB_TOKEN: ${{ github.token }}
+          # Pass the PR head ref via env — never interpolate ${{ }} into run:
+          # (a crafted branch name could inject shell). #1823
+          HEAD_REF: ${{ github.event.pull_request.head.ref }}
+        run: |
+          # "Bump on dev" (release-engineering inversion): move the base-version
+          # bump AND the CHANGELOG [Unreleased] promotion to dev BEFORE the
+          # promotion, so the rc cut (force-pushed from dev below) and the eventual
+          # main INHERIT the final version + promoted changelog. Nothing new is
+          # minted on main, so dev stays a clean superset and dev->main stops
+          # conflicting on Makefile/manifest/package.json/CHANGELOG.
+          #
+          # Only dev-headed promotions bump minor. fix/patch/hotfix/bugfix work is
+          # patch-bumped per-merge on dev by pre-release.yml (there is NO separate
+          # auto-bump.yml) — do NOT double-bump them (mirrors the release job's bump-level gate). Only runs
+          # for a real dev promotion (PR head == dev), never for a workflow_dispatch
+          # promote-rc (no PR head) — which is a manual re-cut of the current dev.
+          if [ "$HEAD_REF" != "dev" ]; then
+            echo "PR head '${HEAD_REF:-<none>}' is not dev — skipping dev pre-bump (fix/hotfix or manual re-cut)."
+            exit 0
+          fi
+          API_BASE="${MOKOGIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          # release_bump_dev.php: minor-bump the base on dev + promote CHANGELOG on
+          # dev, both via the Contents API. Idempotent + monotonic (never moves dev
+          # down), so a PR re-synchronize that re-runs this step is a safe no-op.
+          php ${MOKO_CLI}/release_bump_dev.php \
+            --path . --branch dev --bump minor \
+            --token "${GITHUB_TOKEN}" --api-base "${API_BASE}"
+
+      - name: "Resolve releases-enabled"
+        id: rel
+        run: |
+          # Releases on/off gate (.mokogit-private#73): the pre-promotion BUMP
+          # above runs on every repo; RC-PROMOTION (rename rc, deploy, publish)
+          # is gated on the repo's Releases unit so releases-off repos (Template-*)
+          # bump WITHOUT promoting/publishing. Replaces the old
+          # !startsWith(name,'Template-') name gate. Defaults ON unless the API
+          # explicitly returns has_releases=false (transient error never disables).
+          set +e
+          HR=$(curl -sf -H "Authorization: token ${{ github.token }}" "${MOKOGIT_URL}/api/v1/repos/${{ github.repository }}" | jq -r '.has_releases' 2>/dev/null)
+          if [ "$HR" = "false" ]; then EN=false; else EN=true; fi
+          # Electron: no CI release on ANY channel (local build + manual upload);
+          # opt back in with vars.ELECTRON_CI_BUILD=true. The dev bump above still runs.
+          if { [ -f electron-builder.yml ] || [ -f electron-builder.yaml ]; } && [ "${{ vars.ELECTRON_CI_BUILD }}" != "true" ]; then
+            EN=false
+            echo "::notice::electron repo — RC release disabled (local build + manual upload)"
+          fi
+          echo "enabled=${EN}" >> "$GITHUB_OUTPUT"
+          echo "RC-promotion gate: enabled=${EN} (has_releases=${HR:-unknown})"
+
+      - name: Rename branch to rc
+        if: steps.rel.outputs.enabled == 'true'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          HEAD_REF: ${{ github.event.pull_request.head.ref }}
+        run: |
+          PUSH_TOK="$(printf '%s' "$GITHUB_TOKEN" | tr -d '[:space:]')"; [ -z "$PUSH_TOK" ] && PUSH_TOK="${{ github.token }}"; echo "::add-mask::$PUSH_TOK"
+          API_BASE="${MOKOGIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          AUTH="Authorization: token ${{ github.token }}"
+          FROM="${HEAD_REF:-dev}"
+          PR="${{ github.event.pull_request.number }}"
+
+          # Resolve the source branch HEAD commit.
+          SRC_JSON=$(curl -sf -H "$AUTH" "${API_BASE}/branches/${FROM}") \
+            || { echo "::error::Source branch ${FROM} not found"; exit 1; }
+          SRC_SHA=$(printf '%s' "$SRC_JSON" | python3 -c "import sys, json; print(json.load(sys.stdin)['commit']['id'])" 2>/dev/null || true)
+          [ -n "$SRC_SHA" ] || { echo "::error::Could not resolve HEAD of ${FROM}"; exit 1; }
+
+          # Point rc at the source commit via git push. Git's git/refs PATCH API
+          # returns HTTP 405 on ANY protected branch (force or not, even for a user in
+          # the force-push allowlist), so it cannot move a protected rc. git push honors
+          # the push + force-push allowlists and creates rc if it is absent.
+          PUSH_URL="https://x-access-token:${PUSH_TOK}@${MOKOGIT_URL#https://}/${GIT_ORG}/${GIT_REPO}.git"
+          git config --global user.name "mokogit-actions[bot]"
+          git config --global user.email "actions@mokoconsulting.tech"
+          git fetch --no-tags "$PUSH_URL" "${FROM}"
+          git push --force "$PUSH_URL" "FETCH_HEAD:refs/heads/rc" \
+            || { echo "::error::Failed to point rc at ${FROM} (${SRC_SHA}) via git push"; exit 1; }
+          echo "rc set to ${FROM} (${SRC_SHA})"
+
+          # Repoint the PR at rc, then delete the old source branch (non-fatal).
+          if [ -n "$PR" ]; then
+            curl -s -X PATCH -H "$AUTH" -H "Content-Type: application/json" \
+              "${API_BASE}/pulls/${PR}" -d '{"head":"rc"}' >/dev/null || true
+          fi
+          # Never delete permanent branches (dev/main/rc/...); only ephemeral feature branches.
+          case "$FROM" in
+            dev|main|master|rc|stable|production|release|develop|staging|beta|alpha)
+              echo "Keeping permanent branch ${FROM} (not deleting)" ;;
+            *)
+              curl -s -X DELETE -H "$AUTH" "${API_BASE}/branches/${FROM}" >/dev/null || true ;;
+          esac
+          echo "Renamed ${FROM} -> rc"
+
+      # RC deploy is now INLINE (see "Deploy to RC" below, after the rc checkout).
+      # The former "Trigger RC deploy" step dispatched a non-existent deploy-rc.yml
+      # and always warn-failed; the standalone deploy.yml is deleted in #1427.
+
+      - name: Checkout rc and configure git
+        if: steps.rel.outputs.enabled == 'true'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          PUSH_TOK="$(printf '%s' "$GITHUB_TOKEN" | tr -d '[:space:]')"; [ -z "$PUSH_TOK" ] && PUSH_TOK="${{ github.token }}"; echo "::add-mask::$PUSH_TOK"
+          # Pin the BRANCH ref (refs/heads/rc): the channel-named branch model (#1294)
+          # lets an `rc` release TAG and the `rc` BRANCH coexist, so a bare
+          # `git fetch origin rc` / `git checkout rc` is ambiguous and could grab the tag.
+          git fetch origin "+refs/heads/rc:refs/remotes/origin/rc"
+          git checkout -B rc origin/rc
+          git config --local user.email "mokogit-actions[bot]@mokoconsulting.tech"
+          git config --local user.name "mokogit-actions[bot]"
+          git remote set-url origin "https://x-access-token:${PUSH_TOK}@git.mokoconsulting.tech/${{ github.repository }}.git"
+
+      # Build-time PHP dependency vendoring (universal, guarded — mirrors
+      # pre-release.yml 07.15.00). If a sub-package ships a composer.json, fetch its
+      # runtime deps into that package's CONFIGURED vendor dir (e.g. admin/vendor —
+      # mPDF) BEFORE `moko publish` zips the working tree. No-op without a
+      # sub-package composer.json. FAILS LOUD when vendoring fails for a package
+      # whose Joomla manifest ships <folder>vendor</folder>: shipping that zip
+      # without vendor/ makes JInstaller abort the whole package install on-site
+      # ("File does not exist .../admin/vendor" — MokonyxCRMDCM/MokonyxCRM), which
+      # is strictly worse than a red release run.
+      - name: Vendor PHP dependencies (build-time)
+        if: steps.rel.outputs.enabled == 'true'
+        run: |
+          set -uo pipefail
+          CJS="$(find source/packages src/packages -maxdepth 2 -name composer.json 2>/dev/null || true)"
+          if [ -z "$CJS" ]; then echo "No sub-package composer.json — nothing to vendor."; exit 0; fi
+          command -v composer >/dev/null 2>&1 || { sudo apt-get update -qq && sudo apt-get install -y -qq composer >/dev/null 2>&1 || true; }
+          # mPDF (and most PHP PDF/image libs) hard-require ext-gd; the runners'
+          # php-cli ships without it, which fails dependency RESOLUTION outright.
+          if ! php -m 2>/dev/null | grep -qi '^gd$'; then
+            PHPV="$(php -r 'echo PHP_MAJOR_VERSION.".".PHP_MINOR_VERSION;' 2>/dev/null || true)"
+            sudo apt-get update -qq || true
+            sudo apt-get install -y -qq "php${PHPV}-gd" || sudo apt-get install -y -qq php-gd || echo "::warning::php-gd install failed (php ${PHPV})"
+            php -m 2>/dev/null | grep -qi '^gd$' || echo "::warning::ext-gd STILL missing after install attempt — vendoring will fail for gd-requiring packages"
+          fi
+          rc=0
+          for cj in $CJS; do
+            dir="$(dirname "$cj")"
+            echo "::notice::composer install (no-dev) in ${dir}"
+            ok=true
+            composer install --no-dev --no-interaction --no-progress --optimize-autoloader --working-dir="$dir" || ok=false
+            vd="$(composer config vendor-dir --working-dir="$dir" 2>/dev/null || true)"; vd="${vd:-vendor}"
+            [ -f "${dir}/${vd}/autoload.php" ] || ok=false
+            if [ "$ok" = "true" ]; then
+              echo "vendored: ${dir}/${vd}"
+            elif grep -qs '<folder>vendor</folder>' "${dir}"/*.xml; then
+              echo "::error::vendoring FAILED in ${dir} but its Joomla manifest ships <folder>vendor</folder> — the built zip would abort the whole package install on JInstaller ('File does not exist .../vendor'). Failing the build instead of shipping a broken package."
+              rc=1
+            else
+              echo "::warning::composer install failed in ${dir} — manifest does not ship vendor/; packaging the existing tree"
+            fi
+          done
+          exit $rc
+
+      - name: Publish RC release
+        if: steps.rel.outputs.enabled == 'true'
+        continue-on-error: true
+        run: |
+          # PILOT: call the MokoCLI build agent's publish verb (generic git-release).
+          # Standards preserved -- `moko publish` maps to release_publish.php UNCHANGED
+          # for the generic platform; the stability/bump/token contract is identical
+          # to the former direct invocation. No --branch: release_publish auto-detects
+          # the branch (here rc, from the checkout above).
+          #
+          # --bump none (bump-on-dev): the base was already minor-bumped on dev by
+          # the pre-promotion step above, and rc was force-pushed FROM that dev, so
+          # rc already carries the final base. Bumping again here would double-bump
+          # (dev=+1, rc=+2). --no-commit: don't commit a version change back to rc
+          # (the rc tip must stay identical to the promoted dev). The RC release
+          # still stamps the -rc suffix on the inherited base in-tree.
+          moko publish \
+            --path . --stability rc --bump none --no-commit \
+            --token "${{ github.token }}"
+
+      - name: "Deploy to RC (inline — replaces standalone deploy.yml, #1427)"
+        if: steps.rel.outputs.enabled == 'true' && vars.RC_SSH_USERNAME != ''
+        env:
+          DEPLOY_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
+        run: |
+          # #1427: deploy is inlined into the release pipeline; the standalone
+          # deploy.yml is deleted. Gate = RC_SSH_USERNAME set (the same signal
+          # deploy.yml used) so only SSH-deploy-onboarded repos deploy; every
+          # other repo/platform skips green. Targets come from repo VARIABLES,
+          # never assumed. Deploy LOGIC stays server-side: mokocli deploy.php
+          # SSHes the restricted moko-deploy pattern, which builds+deploys+health-
+          # checks (with rollback) and, on RC, runs the clean-room RC_SEED + RC
+          # Build Tests. A failed RC deploy fails promote-rc — the stable gate.
+          set -euo pipefail
+          if [ -z "${DEPLOY_KEY:-}" ]; then
+            echo "::warning::RC_SSH_USERNAME set but DEPLOY_SSH_KEY secret missing — skipping RC deploy"; exit 0
+          fi
+          mkdir -p ~/.ssh
+          # DEPLOY_SSH_KEY is base64-encoded (single line) so act_runner masks it in logs
+          # and the multi-line key is never echoed. Decode when it base64-decodes to a
+          # private key; else treat as a legacy raw PEM (back-compat during rollout).
+          install -m600 /dev/null ~/.ssh/deploy_key   # 0600 before any bytes (no umask window)
+          trap 'rm -f ~/.ssh/deploy_key' EXIT         # never leave the key on a shared runner
+          if printf '%s' "$DEPLOY_KEY" | base64 -d 2>/dev/null | grep -q 'PRIVATE KEY'; then
+            printf '%s' "$DEPLOY_KEY" | base64 -d > ~/.ssh/deploy_key
+          else
+            echo "$DEPLOY_KEY" > ~/.ssh/deploy_key
+          fi
+          TAG="$(git describe --tags --always 2>/dev/null || git rev-parse --short HEAD)-rc"
+          echo "Deploying rc tag ${TAG} to ${{ vars.RC_SSH_USERNAME }}@${{ vars.RC_SSH_HOST }}"
+          php "${MOKO_CLI}/deploy.php" --tier rc --tag "$TAG" \
+            --ssh-host "${{ vars.RC_SSH_HOST }}" --ssh-port "${{ vars.RC_SSH_PORT }}" \
+            --ssh-user "${{ vars.RC_SSH_USERNAME }}" --ssh-key ~/.ssh/deploy_key
+
+      - name: Update RC release notes from CHANGELOG.md
+        if: steps.rel.outputs.enabled == 'true'
+        continue-on-error: true
+        run: |
+          API_BASE="${MOKOGIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          TOKEN="${{ github.token }}"
+
+          # Extract [Unreleased] section via the shared mokocli command (#364 centralization).
+          NOTES=""
+          if [ -f "release_notes.md" ] && [ -s "release_notes.md" ]; then
+            NOTES="$(cat release_notes.md)"
+          fi
+          # #71: fall back to CHANGELOG [Unreleased] when no curated release_notes.md
+          if [ -z "$NOTES" ] && [ -f "CHANGELOG.md" ]; then
+            NOTES=$(php ${MOKO_CLI}/release_notes.php --path . --version Unreleased 2>/dev/null || true)
+            # release_notes.php echoes "Release Unreleased" when the section is empty; normalize
+            # to empty so the platform fallback below applies.
+            [ "$NOTES" = "Release Unreleased" ] && NOTES=""
+          fi
+          [ -z "$NOTES" ] && NOTES="Release candidate"
+
+          # Find the RC release and update its body
+          RELEASE_ID=$(curl -sf -H "Authorization: token ${TOKEN}" \
+            "${API_BASE}/releases/tags/release-candidate" \
+            | python3 -c "import json,sys; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || true)
+
+          if [ -n "$RELEASE_ID" ]; then
+            python3 -c "
+          import json, urllib.request
+          body = open('/dev/stdin').read()
+          payload = json.dumps({'body': body}).encode()
+          req = urllib.request.Request(
+              '${API_BASE}/releases/${RELEASE_ID}',
+              data=payload, method='PATCH',
+              headers={
+                  'Authorization': 'token ${TOKEN}',
+                  'Content-Type': 'application/json'
+              })
+          urllib.request.urlopen(req)
+          " <<< "$NOTES"
+            echo "RC release notes updated from CHANGELOG.md"
+          fi
+
+      - name: Summary
+        if: always()
+        run: |
+          echo "## Promoted to Release Candidate" >> $GITHUB_STEP_SUMMARY
+          echo "Base bumped + changelog promoted on dev (pre-promotion); rc cut from dev; RC release built" >> $GITHUB_STEP_SUMMARY
+
+  # -- Merged PR -> Build & Release (or promote RC to stable) -------------------------
+  release:
+    name: Build & Release Pipeline
+    # LITERAL runner label — see #366/#134. Gitea does not resolve the
+    # `${{ vars.RELEASE_RUNNER_LABEL || 'release' }}` fallback for an unset var in
+    # `runs-on`, so the job aborts with no runner. The registered label is `release`.
+    runs-on: release
+    # Release-create (vNN tag + release entry), rc-tag move, push, npm-registry publish,
+    # and the post-release dispatch are all contents/packages/actions WRITES. Gitea's
+    # auto-token derives perms from the JOB-level permissions block ONLY (workflow-level
+    # `permissions:` is NOT inherited into a job's token); without this block the token
+    # falls to the org default (empty) and POST /releases 404s fleet-wide (#1712).
+    permissions:
+      contents: write
+      packages: write
+      actions: write
+    # Skip on template repos (Template-*) -- they scaffold other repos and do not release.
+    # Stable release fires on a merged PR into main (pull_request:closed + merged) OR a
+    # direct PUSH to main. The pull_request path is the reliable one -- a PR-merge does not
+    # always emit a base-branch push event to Actions, so relying on push alone silently
+    # skipped releases (a nightly scheduled safety-net used to be the band-aid; it and its
+    # cron have been removed -- the pull_request path is the durable fix). The release
+    # steps already read github.event.pull_request.head.ref, so they handle both events.
+    # Loop guard: skip a self-push that carries
+    # [skip ci]/[skip sync] (mokocli's build commit + the changelog-promote commit).
+    # #469: the non-code paths-ignore was REMOVED, so a docs/CI-only push now reaches
+    # this job and runs in no-bump update mode (gated by steps.srcgate below) instead
+    # of being dropped; the [skip ci]/[skip sync] re-checks here remain the loop guard.
+    # workflow_dispatch stays exempt (explicit human run).
+    # STABLE-RELEASE GATE (default_branch == 'main'): a stable release only fires when
+    # the repo's DEFAULT branch is main. main's mere existence no longer arms stable
+    # releases — so every repo can pre-create all channel branches (dev/rc/beta/alpha/main)
+    # and have them sit idle. A repo promotes itself to "stable-ready" by setting its
+    # default to main; new/in-development repos keep default 'dev' and never auto-release.
+    if: >-
+      !startsWith(github.event.repository.name, 'Template-') && github.event.repository.name != '.vault' &&
+      (github.event.repository.default_branch == 'main' || github.event.repository.default_branch == 'stable') &&
+      (
+        (
+          github.event_name == 'push' &&
+          !contains(github.event.head_commit.message, '[skip ci]') &&
+          !contains(github.event.head_commit.message, '[skip sync]')
+        ) ||
+        (
+          github.event_name == 'pull_request' &&
+          github.event.action == 'closed' &&
+          github.event.pull_request.merged == true &&
+          github.event.pull_request.base.ref == github.event.repository.default_branch &&
+          !contains(github.event.pull_request.title, '[skip ci]') &&
+          !contains(github.event.pull_request.title, '[skip sync]')
+        ) ||
+        (github.event_name == 'workflow_dispatch' && inputs.action != 'promote-rc')
+      )
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          token: ${{ github.token }}
+          fetch-depth: 0
+          submodules: false
+
+      # #1672: transient step-0 checkout aborts on the shared `release` runners make
+      # every stable release a dice-roll. This fallback fires ONLY when the checkout
+      # above failed (step-level `if: failure()` — a LITERAL, not a discarded
+      # continue-on-error expression) and re-materialises the workspace with a
+      # bounded 3-attempt git clone + backoff. fetch-depth: 0 is preserved with a
+      # FULL clone (no --depth) + tags, because the monotonic-guard and bump steps
+      # below need the parent commit and tag history. Fails loudly (exit 1) if all
+      # three attempts fail, so a real (non-transient) breakage is never masked.
+      # Independent step — no needs:+always() fan-in (act_runner would strand it).
+      - name: "Checkout fallback (retry transient flake) (#1672)"
+        if: failure()
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          set -u
+          TOK="$(printf '%s' "$GITHUB_TOKEN" | tr -d '[:space:]')"; echo "::add-mask::$TOK"
+          SERVER="${GITHUB_SERVER_URL:-https://git.mokoconsulting.tech}"
+          CLONE_URL="https://x-access-token:${TOK}@${SERVER#https://}/${GITHUB_REPOSITORY}.git"
+          REF="${GITHUB_SHA:-${GITHUB_REF_NAME:-}}"
+          echo "Retrying full-history checkout of ${GITHUB_REPOSITORY}@${REF:-<HEAD>} into ${GITHUB_WORKSPACE}"
+          ok=0
+          for attempt in 1 2 3; do
+            rm -rf "${GITHUB_WORKSPACE:?}/.git" 2>/dev/null || true
+            find "${GITHUB_WORKSPACE}" -mindepth 1 -maxdepth 1 -exec rm -rf {} + 2>/dev/null || true
+            if git clone "$CLONE_URL" "${GITHUB_WORKSPACE}" \
+               && git -C "${GITHUB_WORKSPACE}" fetch --tags origin \
+               && { [ -z "$REF" ] || git -C "${GITHUB_WORKSPACE}" checkout -f "$REF"; }; then
+              ok=1; echo "Fallback checkout succeeded on attempt ${attempt}."; break
+            fi
+            echo "::warning::Fallback checkout attempt ${attempt} failed; backing off $((attempt * 5))s"
+            sleep $((attempt * 5))
+          done
+          if [ "$ok" != "1" ]; then
+            echo "::error::Checkout failed after 3 retry attempts (#1672) — this is not a transient flake, failing loudly."
+            exit 1
+          fi
+
+      - name: "Detect Makefile (auto-release gate)"
+        id: gate
+        # auto-release drives its build/package targets through make, so a repo
+        # WITHOUT a root Makefile has nothing to release. This is not an error --
+        # many universal repos (deploy handlers, docs, config, e.g. .vault) sync
+        # this workflow but never release. Treat "no Makefile" as a clean SKIP:
+        # emit has_makefile=false and let every downstream build/release step
+        # no-op via its if:, so the job goes GREEN with "Release Skipped" instead
+        # of reding every main push on a non-release repo. Must be a post-checkout
+        # step (a job-level if: cannot inspect the workspace).
+        run: |
+          if [ -f Makefile ] || [ -f makefile ] || [ -f GNUmakefile ]; then
+            echo "has_makefile=true" >> "$GITHUB_OUTPUT"
+            echo "Makefile present -- auto-release may proceed."
+          else
+            echo "has_makefile=false" >> "$GITHUB_OUTPUT"
+            echo "## Release Skipped -- no Makefile" >> "$GITHUB_STEP_SUMMARY"
+            echo "No Makefile at the repository root -- this repo does not build a release. Skipping the release pipeline (not a failure)." >> "$GITHUB_STEP_SUMMARY"
+            echo "No Makefile at repo root -- skipping auto-release (not a release-bearing repo)."
+          fi
+
+      - name: "Detect electron project"
+        id: electron
+        if: steps.gate.outputs.has_makefile == 'true'
+        # ADDITIVE + GATED: electron repos are detected by an electron-builder
+        # config at the repo root (mokocli platform detection does not know
+        # 'electron' yet -- see MokoGIT #1201). Every electron step below no-ops
+        # via `steps.electron.outputs.is_electron` so non-electron repos are
+        # 100% unaffected. Post-checkout (a job-level if: cannot see the tree).
+        run: |
+          if [ -f electron-builder.yml ] || [ -f electron-builder.yaml ]; then
+            echo "is_electron=true" >> "$GITHUB_OUTPUT"
+            echo "electron-builder config present -- electron installer build enabled."
+          else
+            echo "is_electron=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Configure git for bot pushes
+        if: steps.gate.outputs.has_makefile == 'true'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          PUSH_TOK="$(printf '%s' "$GITHUB_TOKEN" | tr -d '[:space:]')"; [ -z "$PUSH_TOK" ] && PUSH_TOK="${{ github.token }}"; echo "::add-mask::$PUSH_TOK"
+          git config --local user.email "mokogit-actions[bot]@mokoconsulting.tech"
+          git config --local user.name "mokogit-actions[bot]"
+          git remote set-url origin "https://x-access-token:${PUSH_TOK}@git.mokoconsulting.tech/${{ github.repository }}.git"
+
+      - name: Check for merge conflict markers
+        if: steps.gate.outputs.has_makefile == 'true'
+        run: |
+          # Scan only git-tracked files so vendored/generated trees (e.g. phpcs'
+          # GitMergeConflictSniff fixtures under vendor/) and this workflow's own
+          # grep pattern can never be matched (back-port of Template-Joomla #177/#178).
+          FILES=$(git ls-files '*.php' '*.xml' '*.css' '*.js' '*.json' '*.md' '*.yml' '*.yaml' '*.ini' '*.txt')
+          CONFLICTS=$(printf '%s\n' "$FILES" | xargs -r grep -nE '^(<<<<<<< |>>>>>>> |=======$)' 2>/dev/null || true)
+          if [ -n "$CONFLICTS" ]; then
+            echo "::error::Merge conflict markers found -- aborting release"
+            echo "## Release Blocked: Conflict Markers" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+            echo "$CONFLICTS" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+            exit 1
+          fi
+          echo "No conflict markers found"
+
+      - name: Setup MokoCLI tools
+        if: steps.gate.outputs.has_makefile == 'true'
+        run: |
+          # Install mokocli FRESH from the MokoGIT Composer registry on every run
+          # (PRIMARY) so CI always uses the latest published version. /opt/mokocli is
+          # a FAILSAFE only — its refresh unit (mokocli-sync.service) is disabled, so
+          # the on-disk snapshot rots and must NOT be preferred. Registry path
+          # /api/packages/** is anon-allowlisted (no GITHUB_TOKEN); it serves a dist
+          # zip (no git clone). --no-install: mokocli self-bootstraps via bundled lib/
+          # + a fallback PSR-4 autoloader (native ext-curl), so no vendor/ is needed.
+          if ! command -v composer > /dev/null 2>&1; then
+            sudo apt-get update -qq && sudo apt-get install -y -qq php-cli php-mbstring php-xml php-zip php-curl composer > /dev/null 2>&1
+          fi
+          rm -rf /tmp/mokocli
+          REG='{"type":"composer","url":"https://git.mokoconsulting.tech/api/packages/MokoConsulting/composer"}'
+          if composer create-project --no-install --no-interaction --no-progress --quiet \
+               --repository="${REG}" mokoconsulting/mokocli /tmp/mokocli >/dev/null 2>&1 \
+             && [ -f /tmp/mokocli/cli/version_bump.php ]; then
+            echo "Installed mokocli fresh from the Composer registry (primary)"
+            # #1671: registry-publish LAG race. The registry install "succeeds" but can
+            # serve the PREVIOUS package for ~tens of seconds after a MokoCLI release
+            # (publish finishes AFTER the release run reports success). Meanwhile the
+            # /opt/mokocli deploy (pull-timer) may already carry the just-released,
+            # NEWER engine. So instead of blindly using the registry copy, compare the
+            # two on-disk versions and PREFER whichever is newer. The Makefile
+            # PROJECT_VERSION is the version source of truth and ships in both the
+            # composer dist and /opt/mokocli. Backward-compatible: with no /opt/mokocli
+            # (most consumer runners), the registry copy is used exactly as before.
+            mk_ver() { sed -n 's/^[[:space:]]*PROJECT_VERSION[[:space:]]*:*=[[:space:]]*//p' "$1" 2>/dev/null | head -n1 | tr -d '[:space:]'; }
+            ver_newer() { [ "$1" != "$2" ] && [ "$(printf '%s\n%s\n' "$1" "$2" | sort -V | tail -n1)" = "$1" ]; }
+            REG_VER="$(mk_ver /tmp/mokocli/Makefile)"
+            OPT_VER="$(mk_ver /opt/mokocli/Makefile)"
+            MOKO_ROOT=/tmp/mokocli
+            if [ -f /opt/mokocli/cli/version_bump.php ] && [ -n "$OPT_VER" ] && [ -n "$REG_VER" ] \
+               && ver_newer "$OPT_VER" "$REG_VER"; then
+              echo "::notice::/opt/mokocli (${OPT_VER}) is newer than the registry copy (${REG_VER}) — using /opt (#1671 publish-lag race)."
+              MOKO_ROOT=/opt/mokocli
+            else
+              echo "Using registry copy (${REG_VER:-unknown}); /opt/mokocli=${OPT_VER:-none}"
+            fi
+            echo "MOKO_CLI=${MOKO_ROOT}/cli" >> $GITHUB_ENV
+            # #650: make the chosen moko executable + FIRST on PATH so bare `moko`
+            # never resolves to a stale/non-executable copy (exit 126).
+            for d in bin cli; do
+              if [ -f "${MOKO_ROOT}/$d/moko" ]; then
+                # #1263 defense-in-depth: strip CR bytes so a CRLF-tainted registry
+                # dist or rotted /opt snapshot can't yield `/usr/bin/env: 'php\r'`
+                # (exit 127). tr interprets \r as a real CR (unlike portable sed).
+                # /opt may be root-owned — write via a temp file + sudo when needed.
+                if tr -d '\r' < "${MOKO_ROOT}/$d/moko" > "/tmp/moko.lf" 2>/dev/null; then
+                  if cp "/tmp/moko.lf" "${MOKO_ROOT}/$d/moko" 2>/dev/null; then :; \
+                  else sudo cp "/tmp/moko.lf" "${MOKO_ROOT}/$d/moko" 2>/dev/null || true; fi
+                  rm -f "/tmp/moko.lf"
+                fi
+                chmod +x "${MOKO_ROOT}/$d/moko" 2>/dev/null || sudo chmod +x "${MOKO_ROOT}/$d/moko" 2>/dev/null || true
+                echo "${MOKO_ROOT}/$d" >> "$GITHUB_PATH"
+              fi
+            done
+            sudo chmod +x /opt/mokocli/*/moko 2>/dev/null || true
+            # Opportunistically refresh the /opt failsafe from this fresh copy when it
+            # differs — keeps the disabled-sync snapshot current so the fallback is
+            # never far behind. Best-effort: needs sudo, gated on a diff to avoid
+            # fleet-wide churn, never fails the job. #1671: only refresh FORWARD — skip
+            # when /opt is the newer copy we just chose, so we never downgrade it.
+            if [ "$MOKO_ROOT" = /tmp/mokocli ] && command -v sudo >/dev/null 2>&1 && [ -d /opt/mokocli ] \
+               && ! cmp -s /tmp/mokocli/cli/version_reset_dev.php /opt/mokocli/cli/version_reset_dev.php 2>/dev/null; then
+              sudo cp -a /tmp/mokocli/. /opt/mokocli/ 2>/dev/null \
+                && echo "Refreshed /opt/mokocli failsafe from the fresh registry copy" \
+                || echo "  (/opt failsafe refresh skipped — no sudo/perms)"
+            fi
+          elif [ -f /opt/mokocli/cli/version_bump.php ]; then
+            echo "::warning::Registry install failed — using /opt/mokocli FAILSAFE (may be stale)"
+            echo "MOKO_CLI=/opt/mokocli/cli" >> $GITHUB_ENV
+          else
+            echo "::error::mokocli unavailable: registry install failed and no /opt/mokocli failsafe present"
+            exit 1
+          fi
+
+      - name: "Detect platform"
+        id: platform
+        if: steps.gate.outputs.has_makefile == 'true'
+        run: |
+          # PILOT: native-manifest platform detection only -- the metadata-registry
+          # write-back (platform_detect.php --update) is REMOVED. The MokoCLI build
+          # agent no longer reads or mutates the metadata API; the platform is
+          # resolved from the in-tree manifest solely to drive the tag/branch logic
+          # below (joomla -> tag=stable; generic -> tag=v${VERSION}).
+          # Non-fatal (|| true) so a detection hiccup never blocks a release.
+          php ${MOKO_CLI}/platform_detect.php --path . --github-output 2>/dev/null || true
+          php ${MOKO_CLI}/manifest_read.php --path . --github-output 2>/dev/null || true
+
+      - name: "Resolve SRC_DIR bump gate (#469)"
+        id: srcgate
+        if: steps.gate.outputs.has_makefile == 'true'
+        # #469: decide version-BUMP vs NO-BUMP (update-existing) from whether this
+        # push touched the Makefile source directory (SRC_DIR). This replaces the old
+        # non-code paths-ignore denylist on the push trigger: a docs/workflow/sample
+        # push no longer skips the pipeline — it runs in no-bump "update the current
+        # stable release in place" mode. SRC_DIR is read from the Makefile exactly as
+        # apidocs.yml does (the de-facto resolve-source-dir contract in this template).
+        #
+        # Gate logic (per the #469 "Resulting gate logic"):
+        #   1. ELECTRON / opt-out -> BYPASS: electron repos have NO source dir, so a
+        #      naive SRC_DIR test would classify every push as non-source and NEVER
+        #      bump (a release-breaking trap). Electron (file-detected) and an explicit
+        #      opt-out (vars.RELEASE_SRCDIR_GATE=off) keep the existing always-bump
+        #      behaviour. Do NOT infer the exclusion from an empty SRC_DIR.
+        #   2. Else SRC_DIR is REQUIRED: a non-excluded repo with no resolvable SRC_DIR
+        #      is a misconfig -> FAIL LOUD (::error:: + exit 1), never silently never-bump.
+        #   3. Else diff the push range (before..sha, with a HEAD^ / merge-base
+        #      fallback) intersected with ${SRC_DIR}/ : any source path -> should_bump
+        #      =true (existing bump+new-release path); none -> should_bump=false
+        #      (no-bump update-existing path). workflow_dispatch always bumps (an
+        #      explicit human re-cut), as does a run with no resolvable diff range.
+        run: |
+          set -uo pipefail
+          # 1. Electron / opt-out bypass -> always bump as today.
+          if [ "${{ steps.electron.outputs.is_electron }}" = "true" ] || [ "${{ vars.RELEASE_SRCDIR_GATE }}" = "off" ]; then
+            echo "should_bump=true" >> "$GITHUB_OUTPUT"
+            echo "::notice::SRC_DIR gate BYPASSED (electron repo or vars.RELEASE_SRCDIR_GATE=off) — keeping always-bump behaviour (#469)."
+            exit 0
+          fi
+          # A manual re-cut is always an intentional bump+release.
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "should_bump=true" >> "$GITHUB_OUTPUT"
+            echo "workflow_dispatch — always bump (explicit human re-cut) (#469)."
+            exit 0
+          fi
+          # Resolve the push diff range (shared by both gate modes below).
+          BEFORE="${{ github.event.before }}"
+          SHA="${GITHUB_SHA:-}"
+          RANGE=""
+          ZERO="0000000000000000000000000000000000000000"
+          if [ -n "$BEFORE" ] && [ "$BEFORE" != "$ZERO" ] && git cat-file -e "${BEFORE}^{commit}" 2>/dev/null; then
+            RANGE="${BEFORE}..${SHA}"
+          elif git rev-parse "${SHA}^1" >/dev/null 2>&1; then
+            # No usable before-sha (branch-create / forced / shallow): fall back to the
+            # first-parent diff of the pushed commit (the merged promotion's delta).
+            RANGE="${SHA}^1..${SHA}"
+          fi
+          if [ -z "$RANGE" ]; then
+            # No resolvable range (e.g. initial push): cannot prove a non-source push,
+            # so default to the safe existing behaviour — bump.
+            echo "should_bump=true" >> "$GITHUB_OUTPUT"
+            echo "::notice::#469 gate: no resolvable diff range (before=${BEFORE:-none}); defaulting to bump."
+            exit 0
+          fi
+          CHANGED="$(git diff --name-only "$RANGE" 2>/dev/null || true)"
+          if [ -z "$CHANGED" ]; then
+            echo "should_bump=true" >> "$GITHUB_OUTPUT"
+            echo "::notice::#469 gate: empty diff for ${RANGE}; defaulting to bump."
+            exit 0
+          fi
+          # 2. SRC_DIR INCLUSION mode — fleet standard is SRC_DIR=source. When the repo
+          #    declares a Makefile SRC_DIR, bump iff the push touched ${SRC_DIR}/.
+          #    Accept all three GNU make assignment forms: SRC_DIR=, SRC_DIR :=, SRC_DIR ?=.
+          # NOTE the trailing `|| true`: the step shell runs with `-e -o pipefail`,
+          # so on a repo with NO SRC_DIR the `grep` exits 1, pipefail propagates it,
+          # and the command-substitution assignment would abort the whole step under
+          # -e BEFORE the denylist fallback below. `|| true` keeps SRC_DIR empty and
+          # lets execution fall through to denylist mode. (#1831)
+          # #498 FIX: resolve SRC_DIR by asking `make` to EXPAND it. The fleet Makefile
+          # standard is `SRC_DIR := $(shell [ -d src ] && echo src || echo source)` — a
+          # GNU make function. A grep|sed read captures the LITERAL unexpanded
+          # "$(shell …)", an unmatchable directory that made INCLUSION mode classify
+          # EVERY push as non-source (should_bump=false forever: MokoCLI stuck
+          # re-publishing v10.20.00 while source changed). Ask make to evaluate it (runs
+          # the $(shell …) read-only); fall back to the grep|sed read only if make is
+          # unavailable, and NULL OUT a still-unexpanded $(...)/`...` value so it drops
+          # to the denylist mode below instead of self-trapping. (|| true keeps the step
+          # alive under -e -o pipefail — see #1831.)
+          SRC_DIR="$(make -s --no-print-directory --eval='__moko_srcdir__:; @printf "%s" "$(SRC_DIR)"' __moko_srcdir__ 2>/dev/null | tr -d '[:space:]' || true)"
+          if [ -z "$SRC_DIR" ]; then
+            SRC_DIR="$(grep -m1 -E '^SRC_DIR[[:space:]]*[:?]?=' Makefile 2>/dev/null | sed -E 's/.*[:?]?=[[:space:]]*//' | tr -d '[:space:]' || true)"
+          fi
+          case "$SRC_DIR" in *'$('*|*'`'*) SRC_DIR="" ;; esac
+          # A declared-but-NONEXISTENT SRC_DIR (e.g. expands to `source` on a repo whose
+          # code lives in cli/lib/bin) must NOT drive INCLUSION mode with an unmatchable
+          # prefix — fall through to the non-source denylist mode instead. (#498)
+          if [ -n "$SRC_DIR" ] && [ ! -d "$SRC_DIR" ]; then
+            echo "::notice::#469 gate: declared SRC_DIR='${SRC_DIR}' does not exist in the tree — using non-source denylist fallback (#498)."
+            SRC_DIR=""
+          fi
+          if [ -n "$SRC_DIR" ]; then
+            SRC_DIR="${SRC_DIR%/}"
+            SRC_HITS="$(printf '%s\n' "$CHANGED" | grep -E "^${SRC_DIR}/" || true)"
+            if [ -n "$SRC_HITS" ]; then
+              echo "should_bump=true" >> "$GITHUB_OUTPUT"
+              echo "#469 gate (SRC_DIR=${SRC_DIR}): push touched ${SRC_DIR}/ (range ${RANGE}) — BUMP + new release."
+            else
+              echo "should_bump=false" >> "$GITHUB_OUTPUT"
+              echo "::notice::#469 gate (SRC_DIR=${SRC_DIR}): push touched NO ${SRC_DIR}/ paths (range ${RANGE}) — NO bump; updating the current release in place."
+            fi
+            exit 0
+          fi
+          # 3. NON-SOURCE DENYLIST mode (#469/#1831) — repos with no single declarable
+          #    SRC_DIR (e.g. MokoGIT, a Gitea fork with root-level Go source). NEVER
+          #    hard-fail on a missing SRC_DIR: bump UNLESS the push touched ONLY
+          #    non-source files (docs, CI/workflows, dotfiles). Any other change bumps.
+          NOBUMP='(^\.|(^|/)docs?/|\.(md|markdown|rst|adoc)$|^(README|CHANGELOG|LICENSE|COPYING|NOTICE|AUTHORS|CONTRIBUTORS|CODE_OF_CONDUCT|CONTRIBUTING|SECURITY|SUPPORT|GOVERNANCE)[^/]*$|^renovate\.json$)'
+          SRC_HITS="$(printf '%s\n' "$CHANGED" | grep -vE "$NOBUMP" || true)"
+          if [ -n "$SRC_HITS" ]; then
+            echo "should_bump=true" >> "$GITHUB_OUTPUT"
+            echo "#469 gate (denylist mode, no SRC_DIR): push touched source/non-doc files (range ${RANGE}) — BUMP + new release."
+          else
+            echo "should_bump=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::#469 gate (denylist mode, no SRC_DIR): push touched ONLY non-source files (docs/CI/dotfiles) (range ${RANGE}) — NO bump; updating the current release in place."
+          fi
+
+      - name: "Determine version bump level"
+        id: bump
+        if: steps.gate.outputs.has_makefile == 'true'
+        env:
+          HEAD_REF: ${{ github.event.pull_request.head.ref }}
+        run: |
+          # Bump-on-dev: the base version is now bumped on DEV pre-promotion (the
+          # promote-rc job's release_bump_dev.php step), so main ALWAYS publishes
+          # the inherited version with NO bump. Historically a dev-headed promotion
+          # bumped minor here (on main) — that on-main bump is exactly the divergence
+          # this change removes. fix/patch/hotfix/bugfix were already 'none' (the
+          # per-merge patch bump happens on dev in pre-release.yml, not here). So
+          # every path is 'none' now.
+          HEAD_REF="${HEAD_REF:-dev}"
+          BUMP="none"
+          echo "level=${BUMP}" >> "$GITHUB_OUTPUT"
+          echo "Bump level: ${BUMP} (from branch: ${HEAD_REF}) — base bumped on dev pre-promotion"
+
+      - name: "Detect mokohub packaging platforms"
+        id: mokohub
+        if: steps.gate.outputs.has_makefile == 'true'
+        # ADDITIVE + GATED (Template-Generic#326): classify the mokohub-manifest /
+        # mokohub-recipes platforms from the detected platform key so their gated
+        # packaging steps below can fire. Purely additive — no existing platform
+        # (joomla/npm/mcp/client/generic/go/php/electron) reads these outputs, so
+        # their release path is 100% unchanged. Detection is read-only.
+        run: |
+          PLATFORM="${{ steps.platform.outputs.platform }}"
+          IS_MANIFEST=false
+          IS_RECIPES=false
+          case "$PLATFORM" in
+            mokohub-manifest*) IS_MANIFEST=true ;;
+            mokohub-recipes*)  IS_RECIPES=true ;;
+          esac
+          echo "is_manifest=${IS_MANIFEST}" >> "$GITHUB_OUTPUT"
+          echo "is_recipes=${IS_RECIPES}" >> "$GITHUB_OUTPUT"
+          [ "$IS_MANIFEST" = "true" ] && echo "mokohub-manifest platform — manifest.json packaging enabled."
+          [ "$IS_RECIPES" = "true" ] && echo "mokohub-recipes platform — catalog.zip packaging enabled."
+          true
+
+      - name: "Gate npm publish (PLATFORM=npm + package.json + Makefile PROJECT_VERSION)"
+        id: npmpub
+        if: steps.gate.outputs.has_makefile == 'true'
+        # A repo is npm-publishable ONLY when its Makefile PLATFORM is npm/nodejs --
+        # the canonical platform declaration, NOT file presence. Joomla/Go/other repos
+        # that merely ship a build-tooling package.json (e.g. a Joomla component with a
+        # frontend package.json) must never be treated as npm packages. On top of the
+        # platform gate we still require a package.json AND a Makefile PROJECT_VERSION
+        # (the mokocli source of truth the publish step reads) -- belt-and-suspenders,
+        # so a genuine npm repo missing PROJECT_VERSION does not fail the release.
+        run: |
+          PUB=false
+          PLATFORM="${{ steps.platform.outputs.platform }}"
+          # Electron repos build + publish their installers LOCALLY (manual upload),
+          # so they must NEVER npm-publish from CI even though they detect as nodejs
+          # (they ship a package.json). Mirror pre-release.yml's electron publish gate
+          # (Template-Generic #390): disable unless explicitly opted in with
+          # vars.ELECTRON_CI_BUILD=true. Non-electron repos are unaffected.
+          if [ "${{ steps.electron.outputs.is_electron }}" = "true" ] && [ "${{ vars.ELECTRON_CI_BUILD }}" != "true" ]; then
+            echo "publishable=false" >> "$GITHUB_OUTPUT"
+            echo "npm-publishable=false (electron repo -- CI npm publish disabled; local build + manual upload)"
+          else
+            case "$PLATFORM" in
+              npm*|nodejs*)
+                if [ -f package.json ] && grep -qE '^[[:space:]]*PROJECT_VERSION[[:space:]]*:?=' Makefile; then PUB=true; fi
+                ;;
+            esac
+            echo "publishable=${PUB}" >> "$GITHUB_OUTPUT"
+            echo "npm-publishable=${PUB} (needs PLATFORM npm/nodejs + package.json + Makefile PROJECT_VERSION; PLATFORM=${PLATFORM})"
+          fi
+
+      - name: "Sterilize SVG assets (strip editor/Inkscape metadata) (#312)"
+        if: steps.gate.outputs.has_makefile == 'true'
+        continue-on-error: true
+        run: |
+          set -uo pipefail
+          mapfile -t SVGS < <(find . -type f -name '*.svg' \
+            -not -path './.git/*' -not -path './node_modules/*' -not -path './vendor/*' 2>/dev/null || true)
+          if [ "${#SVGS[@]}" -eq 0 ]; then echo "no SVGs -- skipping (#312)"; exit 0; fi
+          echo "Sterilizing ${#SVGS[@]} SVG(s) -- stripping editor/Inkscape metadata..."
+          if pip install --quiet --disable-pip-version-check scour >/dev/null 2>&1 && command -v scour >/dev/null 2>&1; then
+            for fsvg in "${SVGS[@]}"; do
+              scour -i "$fsvg" -o "$fsvg.st" --remove-metadata --strip-xml-prolog --enable-comment-stripping >/dev/null 2>&1 \
+                && mv "$fsvg.st" "$fsvg" || rm -f "$fsvg.st"
+            done
+            echo "SVG sterilization complete (scour, metadata-only)."
+          else
+            echo "::notice::scour unavailable -- SVG sterilization skipped (non-fatal, #312)."
+          fi
+
+      - name: Optimize assets (artifact-time)
+        if: steps.gate.outputs.has_makefile == 'true'
+        continue-on-error: true
+        run: |
+          moko assets:optimize --path . 2>/dev/null || echo "::notice::moko assets:optimize unavailable or no assets — skipping"
+
+      # Build-time PHP dependency vendoring (universal, guarded — mirrors
+      # pre-release.yml 07.15.00). If a sub-package ships a composer.json, fetch its
+      # runtime deps into that package's CONFIGURED vendor dir (e.g. admin/vendor —
+      # mPDF) BEFORE `moko publish` (release_publish.php → release_package.php) zips
+      # the working tree. No-op without a sub-package composer.json. FAILS LOUD when
+      # vendoring fails for a package whose Joomla manifest ships
+      # <folder>vendor</folder>: shipping that zip without vendor/ makes JInstaller
+      # abort the whole package install on-site ("File does not exist
+      # .../admin/vendor" — MokonyxCRMDCM/MokonyxCRM), strictly worse than a red run.
+      - name: Vendor PHP dependencies (build-time)
+        if: steps.gate.outputs.has_makefile == 'true'
+        run: |
+          set -uo pipefail
+          CJS="$(find source/packages src/packages -maxdepth 2 -name composer.json 2>/dev/null || true)"
+          if [ -z "$CJS" ]; then echo "No sub-package composer.json — nothing to vendor."; exit 0; fi
+          command -v composer >/dev/null 2>&1 || { sudo apt-get update -qq && sudo apt-get install -y -qq composer >/dev/null 2>&1 || true; }
+          # mPDF (and most PHP PDF/image libs) hard-require ext-gd; the runners'
+          # php-cli ships without it, which fails dependency RESOLUTION outright.
+          if ! php -m 2>/dev/null | grep -qi '^gd$'; then
+            PHPV="$(php -r 'echo PHP_MAJOR_VERSION.".".PHP_MINOR_VERSION;' 2>/dev/null || true)"
+            sudo apt-get update -qq || true
+            sudo apt-get install -y -qq "php${PHPV}-gd" || sudo apt-get install -y -qq php-gd || echo "::warning::php-gd install failed (php ${PHPV})"
+            php -m 2>/dev/null | grep -qi '^gd$' || echo "::warning::ext-gd STILL missing after install attempt — vendoring will fail for gd-requiring packages"
+          fi
+          rc=0
+          for cj in $CJS; do
+            dir="$(dirname "$cj")"
+            echo "::notice::composer install (no-dev) in ${dir}"
+            ok=true
+            composer install --no-dev --no-interaction --no-progress --optimize-autoloader --working-dir="$dir" || ok=false
+            vd="$(composer config vendor-dir --working-dir="$dir" 2>/dev/null || true)"; vd="${vd:-vendor}"
+            [ -f "${dir}/${vd}/autoload.php" ] || ok=false
+            if [ "$ok" = "true" ]; then
+              echo "vendored: ${dir}/${vd}"
+            elif grep -qs '<folder>vendor</folder>' "${dir}"/*.xml; then
+              echo "::error::vendoring FAILED in ${dir} but its Joomla manifest ships <folder>vendor</folder> — the built zip would abort the whole package install on JInstaller ('File does not exist .../vendor'). Failing the build instead of shipping a broken package."
+              rc=1
+            else
+              echo "::warning::composer install failed in ${dir} — manifest does not ship vendor/; packaging the existing tree"
+            fi
+          done
+          exit $rc
+
+      - name: "Guarantee monotonic release version (fast-merge bump guard)"
+        id: monotonic
+        # #469: in no-bump mode (a non-source push updating the existing release in
+        # place) the version must stay PUT, so the self-healing minor bump must not
+        # run — skip this guard when steps.srcgate decided should_bump=false. On the
+        # bump path (should_bump=true, or electron/opt-out/dispatch where srcgate is
+        # bypassed/true) it runs exactly as before.
+        if: steps.gate.outputs.has_makefile == 'true' && steps.srcgate.outputs.should_bump != 'false'
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          # P1-b (.mokogit-private#73): the base is normally minor-bumped on dev by
+          # promote-rc pre-promotion. If the dev->stable PR is MERGED before
+          # promote-rc runs (a fast merge), that bump is skipped and this job would
+          # re-publish an ALREADY-RELEASED base (observed: stuck at 02.23.00). Enforce
+          # "strictly above the last release": a no-op on the normal path, a self-
+          # healing local bump when the inherited base did not advance.
+          CUR=$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null | sed 's/-\(dev\|alpha\|beta\|rc\)$//')
+          [ -z "$CUR" ] && { echo "no base version; skip guard"; exit 0; }
+          git fetch --tags --quiet origin 2>/dev/null || true
+          # #813: the "last released version" is the MAX of two sources, not tags alone.
+          # The rolling-release model publishes to a FIXED `stable` release whose NAME
+          # ("... (VERSION: NN.NN.NN)") is the true last-published version, while the
+          # immutable vNN.NN.NN tags can lag / fail to advance (#808/#386 stale-tag).
+          # Trusting tags alone made this guard blind, so a direct fix/*->stable merge
+          # RE-CUT an already-published base (observed 01.00.19 re-cut). Take the max of
+          # (a) the highest vNN.NN.NN tag and (b) the rolling `stable` release version.
+          TAG_LAST=$(git tag -l 'v[0-9][0-9].[0-9][0-9].[0-9][0-9]' | sed 's/^v//' | sort -V | tail -n1 || true)
+          # #1702 / .mokogit-private#76: resolve the CURRENT stable release by its
+          # CHANNEL POINTER, not by a fixed `tag_name=stable`. Under version-primary
+          # releases the release tag_name is the immutable vNN, so GET
+          # /releases/tags/stable no longer finds it; the channel endpoint
+          # (releases/channel/stable) resolves whichever release the `stable`
+          # channel currently points at via ReleaseStreamMap. Graceful fallback to
+          # the legacy tags/stable call for forges predating #1702 (pre-rollout the
+          # channel route 404s and the rolling `stable` tag still exists). The parsed
+          # input is identical: the release NAME carries "VERSION: NN.NN.NN".
+          RELEASE_JSON=$(curl -sf -H "Authorization: token ${GITHUB_TOKEN:-${{ github.token }}}" \
+            "${MOKOGIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}/releases/channel/stable" 2>/dev/null || true)
+          if [ -z "$RELEASE_JSON" ]; then
+            RELEASE_JSON=$(curl -sf -H "Authorization: token ${GITHUB_TOKEN:-${{ github.token }}}" \
+              "${MOKOGIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}/releases/tags/stable" 2>/dev/null || true)
+          fi
+          ROLLING_LAST=$(printf '%s' "${RELEASE_JSON:-}" \
+            | grep -oE 'VERSION: [0-9]{2}\.[0-9]{2}\.[0-9]{2}' | grep -oE '[0-9]{2}\.[0-9]{2}\.[0-9]{2}' | head -n1 || true)
+          LAST=$( { echo "$TAG_LAST"; echo "$ROLLING_LAST"; } | grep -E '^[0-9]{2}\.[0-9]{2}\.[0-9]{2}$' | sort -V | tail -n1 || true)
+          if [ -z "$LAST" ]; then echo "no prior release (no vNN.NN.NN tag, no rolling stable); skip guard"; exit 0; fi
+          echo "monotonic guard: CUR=${CUR} TAG_LAST=${TAG_LAST:-none} ROLLING_LAST=${ROLLING_LAST:-none} -> LAST=${LAST}"
+          # #498 FIX: the release IDENTITY is the MINOR (tag vMAJOR.MINOR.00). Dev's
+          # per-merge PATCH bumps advance CUR within the SAME minor (e.g. 10.20.00 ->
+          # 10.20.04), which satisfied the old full-version `CUR <= LAST` test and
+          # WRONGLY skipped the heal — so a fast dev->stable merge re-published the
+          # already-released vMAJOR.MINOR.00 forever (observed: MokoCLI stuck at
+          # v10.20.00 while dev reached 10.20.04), violating this guard's own "never
+          # re-publish an already-released base" intent. Compare the MINOR identity
+          # (MAJOR.MINOR): heal (minor-bump) whenever CUR's minor has NOT advanced past
+          # the last release's minor. The normal promote-rc path (dev already
+          # minor-bumped) still no-ops.
+          CUR_MI=$(printf '%s' "$CUR"  | awk -F. '{printf "%s.%s", $1, $2}')
+          LAST_MI=$(printf '%s' "$LAST" | awk -F. '{printf "%s.%s", $1, $2}')
+          GREATEST_MI=$( { echo "$CUR_MI"; echo "$LAST_MI"; } | sort -V | tail -n1 || true)
+          if [ "$CUR_MI" = "$LAST_MI" ] || [ "$GREATEST_MI" = "$LAST_MI" ]; then
+            echo "::warning::inherited minor ${CUR_MI} <= last release minor ${LAST_MI} (CUR=${CUR} LAST=${LAST}); minor-bump skipped -> self-healing"
+            if ! php ${MOKO_CLI}/version_bump.php --minor --min-version "$LAST" --path .; then
+              echo "::error::monotonic bump guard failed to advance the base"; exit 1
+            fi
+            NEW=$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null | sed 's/-\(dev\|alpha\|beta\|rc\)$//')
+            echo "healed ${CUR} -> ${NEW} (publishing fresh; carrying forward to dev)"
+            php ${MOKO_CLI}/release_bump_dev.php --path . --branch dev --bump minor \n              --repo "${{ github.repository }}" --token "${GITHUB_TOKEN:-${{ github.token }}}" \n              || echo "::warning::dev carry-forward failed (non-fatal; release still publishes the healed version)"
+          else
+            echo "base ${CUR} > last release ${LAST}: normal path, no heal"
+          fi
+
+      # -- Release integrity: refuse to publish a STALE (pre-merge) tree ---------
+      # #428 / MokoCLI #901: the release builds GITHUB_SHA (the triggering commit).
+      # If a concurrent merge advanced the branch AFTER this run's trigger, we would
+      # package a PRE-merge tree while stamping the new version -- a green release
+      # that silently ships old code (reproduced: built ef8c1a5d while the tip was
+      # the ladder-merge 2740342, missing only that merge's blobs). The mokocli
+      # engine asserts packaged-tree == GITHUB_SHA, but it CANNOT see that GITHUB_SHA
+      # itself trails the tip -- that is this guard's job. Fail-OPEN on any ambiguity
+      # (unresolved tip / replica lag) so a good release is never falsely blocked; a
+      # confident "built commit is an ancestor of the live tip" is a hard FAIL.
+      - name: "Release integrity: no stale (pre-merge) tree"
+        id: stale_guard
+        if: steps.gate.outputs.has_makefile == 'true' && (steps.electron.outputs.is_electron != 'true' || vars.ELECTRON_CI_BUILD == 'true')
+        run: |
+          set -uo pipefail
+          BUILT="${GITHUB_SHA:-}"
+          BRANCH="${GITHUB_REF_NAME:-}"
+          if [ -z "$BUILT" ] || [ -z "$BRANCH" ]; then
+            echo "::warning::stale-tree guard: no GITHUB_SHA/branch to check (event=${GITHUB_EVENT_NAME:-?}); skipping (fail-open)."; exit 0
+          fi
+          # Fetch the CURRENT branch tip into a private tracking ref. Pin refs/heads/
+          # explicitly: the channel-named-branch model lets a `stable` TAG and `stable`
+          # BRANCH coexist, so a bare `git fetch origin stable` is ambiguous. Retry for
+          # replica lag; a lagged read can only look EQUAL/behind -> never a false fail.
+          TIP=""
+          for i in 1 2 3 4; do
+            if git fetch --quiet origin "+refs/heads/${BRANCH}:refs/remotes/origin/${BRANCH}-tipcheck" 2>/dev/null; then
+              TIP="$(git rev-parse "refs/remotes/origin/${BRANCH}-tipcheck" 2>/dev/null || echo '')"
+              [ -n "$TIP" ] && break
+            fi
+            sleep $((i * 2))
+          done
+          if [ -z "$TIP" ]; then
+            echo "::warning::stale-tree guard: could not resolve tip of '${BRANCH}'; skipping (fail-open)."; exit 0
+          fi
+          if [ "$TIP" = "$BUILT" ]; then
+            echo "Release integrity OK: building the current ${BRANCH} tip ${BUILT}."; exit 0
+          fi
+          if git merge-base --is-ancestor "$BUILT" "$TIP" 2>/dev/null; then
+            # $BUILT is behind $TIP. Distinguish a genuine concurrent CODE merge
+            # from this run's (or a prior release run's) OWN version-stamp commit
+            # (#433). The "Publish stable release" step commits
+            # "chore(release): build NN.NN.NN [skip ci]" onto the branch, which
+            # advances the tip past $BUILT -- that is self-generated, NOT a
+            # concurrent merge, and must not block (otherwise a re-run / the next
+            # run false-fails forever and the release stalls: branch bumped, artifact
+            # never published, [skip ci] blocking self-heal). If EVERY commit in
+            # BUILT..TIP is such a release-stamp commit, proceed; if ANY other
+            # commit is present, a real merge landed -> hard fail as before.
+            FOREIGN=0
+            for c in $(git rev-list "${BUILT}..${TIP}" 2>/dev/null); do
+              SUBJ="$(git log -1 --format='%s' "$c" 2>/dev/null || echo '?')"
+              case "$SUBJ" in
+                "chore(release): build "*) : ;;   # our own [skip ci] version stamp
+                *) FOREIGN=1; break ;;
+              esac
+            done
+            if [ "$FOREIGN" = "0" ]; then
+              echo "::notice::stale-tree guard: '${BRANCH}' tip ${TIP} is ahead of ${BUILT} only by this run's own release-stamp commit(s) ('chore(release): build …'); not a concurrent merge -- proceeding (#433)."
+            else
+              echo "::error::Stale-tree guard: the triggering commit ${BUILT} is BEHIND the current '${BRANCH}' tip ${TIP} -- a concurrent merge landed during this run. Refusing to publish a pre-merge tree that would ship old code under the new version (#428 / MokoCLI #901). The newer commit gets its own release run; re-run this job against ${TIP} if a dedicated release for ${BUILT} is required."
+              {
+                echo "### ❌ Release blocked -- stale (pre-merge) tree"
+                echo ""
+                echo "Triggering commit \`${BUILT}\` is an **ancestor** of the current \`${BRANCH}\` tip \`${TIP}\`: a concurrent merge advanced the branch during this run. Publishing now would package code **missing that merge** while stamping the new version (the #901 bug). Blocked. See **#428 / MokoCLI #901**."
+              } >> "$GITHUB_STEP_SUMMARY"
+              exit 1
+            fi
+          fi
+          echo "::warning::stale-tree guard: built ${BUILT} != tip ${TIP} but is not its ancestor (diverged/unrelated); no pre-merge-tree risk detected -- proceeding."
+
+      - name: "Publish stable release"
+        id: publish
+        if: steps.gate.outputs.has_makefile == 'true' && (steps.electron.outputs.is_electron != 'true' || vars.ELECTRON_CI_BUILD == 'true')
+        run: |
+          # PILOT: call the MokoCLI build agent's publish verb (generic git-release).
+          # `moko publish` maps to release_publish.php UNCHANGED -- same
+          # stability/token contract, standards preserved. No --branch:
+          # release_publish auto-detects the branch (here main).
+          #
+          # Bump-on-dev: --bump none + --no-commit. The base was bumped on dev
+          # pre-promotion and inherited into main via the merge, so main neither
+          # bumps NOR commits a version change. release_publish still stamps the
+          # (unchanged) version in-tree so the built artifact is correct, but Step
+          # 2c's commit/push to main is suppressed -- this is what removes the
+          # main-only `chore(release): build` commit that diverged main from dev.
+          # GITHUB_TOKEN is no longer needed here (nothing is persisted to main).
+          # #469: this SAME --bump none --no-commit publish serves BOTH gate paths.
+          # On the BUMP path it publishes the newly-advanced inherited version; on the
+          # NO-BUMP path (steps.srcgate.should_bump=false — a non-source push) it
+          # re-stamps the UNCHANGED current version onto the existing stable channel
+          # release, re-issuing it in place with the refreshed (non-source) tree. The
+          # version does not advance and the self-heal bump + new vNN tag are skipped
+          # upstream, so no new version identity is minted — exactly the #469 contract.
+          if [ "${{ steps.srcgate.outputs.should_bump }}" = "false" ]; then
+            echo "::notice::#469 no-bump mode — re-issuing the existing stable release in place (same version, refreshed tree/assets/notes), no version advance, no new vNN tag."
+          fi
+          # #289: stamp <creationDate> (build date, UTC) + <author> (Makefile
+          # PROJECT_AUTHOR) into Joomla manifests before publish, so the released
+          # stable manifest carries them. release_publish (below) re-stamps <version>
+          # idempotently. No-op on non-Joomla and on an older MokoCLI lacking the args.
+          MG_BUILD_DATE="$(date -u +%Y-%m-%d)"
+          MG_AUTHOR="$(grep -m1 -E '^PROJECT_AUTHOR[[:space:]]*:?=' Makefile 2>/dev/null | sed -E 's/.*:?=[[:space:]]*//' | sed 's/[[:space:]]*$//' || true)"
+          MG_VER="$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null || echo '')"
+          [ -n "$MG_VER" ] && php ${MOKO_CLI}/version_set_platform.php \
+            --path . --version "$MG_VER" \
+            --date "$MG_BUILD_DATE" ${MG_AUTHOR:+--author "$MG_AUTHOR"} 2>/dev/null || true
+
+          moko publish \
+            --path . --stability stable --bump none --no-commit \
+            --token "${{ github.token }}"
+
+      - name: "Read published version"
+        id: version
+        if: steps.gate.outputs.has_makefile == 'true'
+        run: |
+          # #741: consume the version the build agent already published (steps.publish
+          # writes version=/base_version=/semver= to $GITHUB_OUTPUT via release_publish.php).
+          # Falling back to version_read.php only if that output is absent (older
+          # /opt/mokocli) keeps this backward-compatible while removing the second,
+          # divergent resolution that silently false-skipped the npm publish gate.
+          VERSION="${{ steps.publish.outputs.version }}"
+          [ -z "$VERSION" ] && VERSION=$(php ${MOKO_CLI}/version_read.php --path . 2>/dev/null || echo "")
+          VERSION=$(echo "$VERSION" | sed 's/-\(dev\|alpha\|beta\|rc\)$//')
+          [ -z "$VERSION" ] && VERSION="00.00.00" && echo "skip=true" >> "$GITHUB_OUTPUT"
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+          PLATFORM="${{ steps.platform.outputs.platform }}"
+          # Feed-tag selection: joomla AND electron need a STABLE, ROLLING tag so
+          # their update feed lives at a constant URL. electron (Template-Generic#333,
+          # coordinates MokoGIT#1342): electron-updater's latest.yml / latest-linux.yml /
+          # latest-mac.yml must sit at a fixed path so the MokoGIT electron-yml generator
+          # can poll a constant URL; a moving v${VERSION} tag would relocate the feed every
+          # release and break the updater. Everything else keeps the immutable v${VERSION} tag.
+          if [[ "$PLATFORM" == joomla* || "$PLATFORM" == electron* ]]; then
+            echo "tag=stable" >> "$GITHUB_OUTPUT"
+            echo "release_tag=stable" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=v${VERSION}" >> "$GITHUB_OUTPUT"
+            echo "release_tag=v${VERSION}" >> "$GITHUB_OUTPUT"
+          fi
+          echo "branch=main" >> "$GITHUB_OUTPUT"
+          echo "Published version: ${VERSION}"
+
+      - name: "Deploy to prod (inline — replaces standalone deploy.yml, #1427)"
+        if: steps.gate.outputs.has_makefile == 'true' && steps.version.outputs.skip != 'true' && vars.PROD_SSH_USERNAME != ''
+        env:
+          DEPLOY_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
+        run: |
+          # #1427: prod deploy inlined here (release job runs on push to stable).
+          # Gate = PROD_SSH_USERNAME set → only SSH-deploy repos deploy; others skip
+          # green. Targets from repo VARIABLES. mokocli deploy.php → restricted
+          # moko-deploy (build → push-guarded → recreate → health-check → rollback;
+          # advances the floating :stable tag only after a healthy deploy). Must be
+          # atomic with deleting deploy.yml — otherwise deploy.yml's push:[stable]
+          # trigger would double-deploy prod.
+          set -euo pipefail
+          if [ -z "${DEPLOY_KEY:-}" ]; then
+            echo "::warning::PROD_SSH_USERNAME set but DEPLOY_SSH_KEY secret missing — skipping prod deploy"; exit 0
+          fi
+          mkdir -p ~/.ssh
+          # DEPLOY_SSH_KEY is base64-encoded (single line) so act_runner masks it in logs
+          # and the multi-line key is never echoed. Decode when it base64-decodes to a
+          # private key; else treat as a legacy raw PEM (back-compat during rollout).
+          install -m600 /dev/null ~/.ssh/deploy_key   # 0600 before any bytes (no umask window)
+          trap 'rm -f ~/.ssh/deploy_key' EXIT         # never leave the key on a shared runner
+          if printf '%s' "$DEPLOY_KEY" | base64 -d 2>/dev/null | grep -q 'PRIVATE KEY'; then
+            printf '%s' "$DEPLOY_KEY" | base64 -d > ~/.ssh/deploy_key
+          else
+            echo "$DEPLOY_KEY" > ~/.ssh/deploy_key
+          fi
+          # #1637: deploy the IMMUTABLE pushed commit, not a git-describe of the
+          # runner's HEAD. release_publish's internal `checkout -B FETCH_HEAD` can
+          # re-poison HEAD with a replica-lagged commit by this step, so `git describe`
+          # / `git rev-parse HEAD` here can name an ANCESTOR — moko-deploy then built a
+          # stale image while the release reported success (the favicon incident).
+          # $GITHUB_SHA is the pushed stable commit (BUMP-ON-DEV: it already carries the
+          # released VERSION + code) and cannot be re-poisoned. moko-deploy checks out
+          # this exact 40-hex commit (falling back to the branch tip for non-SHA tags).
+          TAG="${GITHUB_SHA}"
+          echo "Deploying prod commit ${TAG} to ${{ vars.PROD_SSH_USERNAME }}@${{ vars.PROD_SSH_HOST }}"
+          php "${MOKO_CLI}/deploy.php" --tier prod --tag "$TAG" \
+            --ssh-host "${{ vars.PROD_SSH_HOST }}" --ssh-port "${{ vars.PROD_SSH_PORT }}" \
+            --ssh-user "${{ vars.PROD_SSH_USERNAME }}" --ssh-key ~/.ssh/deploy_key
+
+      # -- Electron: build installers (Windows via Wine + Linux) and attach ------
+      # No Windows/macOS runner: the `release` runner is Ubuntu, so we cross-build
+      # the Windows target with Wine and build Linux natively. macOS is skipped
+      # (cannot be cross-built off a Mac). All four steps no-op on non-electron repos.
+      - name: "Setup Node (electron)"
+        if: steps.gate.outputs.has_makefile == 'true' && steps.electron.outputs.is_electron == 'true' && steps.version.outputs.skip != 'true' && vars.ELECTRON_CI_BUILD == 'true'
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24.18.1
+
+      - name: "Setup pnpm (electron)"
+        if: steps.gate.outputs.has_makefile == 'true' && steps.electron.outputs.is_electron == 'true' && steps.version.outputs.skip != 'true' && vars.ELECTRON_CI_BUILD == 'true'
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11.20.0
+
+      - name: "Build electron installers (Windows via Wine + Linux)"
+        if: steps.gate.outputs.has_makefile == 'true' && steps.electron.outputs.is_electron == 'true' && steps.version.outputs.skip != 'true' && vars.ELECTRON_CI_BUILD == 'true'
+        env:
+          HUSKY: "0"
+        run: |
+          # electron-builder's NSIS target RUNS the built installer under Wine to
+          # generate + sign the uninstaller, which needs 32-bit Wine libs (the NSIS
+          # stub is a WoW64 exe) AND an X display. A bare `wine64` on an
+          # under-provisioned `release` runner aborts with "wine process failed 1
+          # ... ntdll.dll c0000135 / no driver could be loaded" (intermittent: only
+          # when a job lands on a runner without wine32/xvfb pre-seeded). Provision
+          # i386 Wine + Xvfb here so the Windows leg builds on ANY runner, and init
+          # the prefix once, headless, so electron-builder's first Wine call does
+          # not race prefix creation.
+          sudo dpkg --add-architecture i386 || true
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq xvfb >/dev/null 2>&1 || echo "::warning::xvfb install failed"
+          sudo apt-get install -y -qq wine64 wine32 >/dev/null 2>&1             || sudo apt-get install -y -qq wine >/dev/null 2>&1             || sudo apt-get install -y -qq wine64 >/dev/null 2>&1             || echo "::warning::wine install failed -- Windows target may be skipped"
+          export WINEDEBUG=-all
+          export WINEPREFIX="${WINEPREFIX:-$HOME/.wine}"
+          xvfb-run -a wineboot --init >/dev/null 2>&1 || true
+          pnpm install --frozen-lockfile
+          # Compile the app into electron-builder's app dir (directories.app, e.g. ./build)
+          # BEFORE packaging -- electron-builder validates the app dir up-front and aborts
+          # with "Application directory ./build doesn't exist" otherwise. Prefer an explicit
+          # repo script (compile:app); fall back to the esbuild entrypoint.
+          if pnpm run 2>/dev/null | grep -qiE '(^|[[:space:]])compile:app([[:space:]]|$)'; then
+            pnpm run compile:app
+          elif [ -f esbuild.mjs ]; then
+            npx --no-install preval-build-info-cli >/dev/null 2>&1 || true
+            node esbuild.mjs
+          else
+            echo "::warning::no compile step found (add a 'compile:app' package.json script or esbuild.mjs) -- electron-builder may fail if the app dir is not pre-built"
+          fi
+          # xvfb-run gives Wine a virtual X display for the installer-run pass that
+          # generates the NSIS uninstaller; without it Wine cannot create a window
+          # and the build fails ("no driver could be loaded / $DISPLAY").
+          xvfb-run -a npx --no-install electron-builder --win --linux --publish never             || xvfb-run -a npx electron-builder --win --linux --publish never
+
+      - name: "Attach electron installers to the release"
+        if: steps.gate.outputs.has_makefile == 'true' && steps.electron.outputs.is_electron == 'true' && steps.version.outputs.skip != 'true' && vars.ELECTRON_CI_BUILD == 'true'
+        continue-on-error: true
+        run: |
+          API_BASE="${MOKOGIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          TOKEN="${{ github.token }}"
+          TAG="${{ steps.version.outputs.tag }}"
+          RID=$(curl -sf -H "Authorization: token ${TOKEN}" "${API_BASE}/releases/tags/${TAG}" | python3 -c "import json,sys; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || true)
+          if [ -z "$RID" ]; then echo "::warning::release ${TAG} not found -- skipping electron asset upload"; else
+            n=0
+            for f in $(find out dist_electron dist -maxdepth 2 -type f \( -name '*.exe' -o -name '*.AppImage' -o -name '*.deb' -o -name 'latest*.yml' \) 2>/dev/null); do
+              name=$(basename "$f")
+              curl -sf -X POST -H "Authorization: token ${TOKEN}" "${API_BASE}/releases/${RID}/assets?name=${name}" -F "attachment=@${f}" >/dev/null && { echo "attached ${name}"; n=$((n+1)); } || echo "::warning::failed to upload ${name}"
+            done
+            echo "Electron installers attached to ${TAG}: ${n} file(s)"
+          fi
+
+      # -- mokohub-manifest: zip manifest.json -> attach to the stable release -----
+      # ADDITIVE + GATED (Template-Generic#326). Gated on is_manifest so every other
+      # platform is untouched. Best-effort attach (continue-on-error): the release is
+      # already published, so a packaging hiccup must not red the pipeline.
+      - name: "Package mokohub-manifest (zip manifest.json)"
+        if: >-
+          steps.gate.outputs.has_makefile == 'true' &&
+          steps.mokohub.outputs.is_manifest == 'true' &&
+          steps.version.outputs.skip != 'true'
+        continue-on-error: true
+        run: |
+          API_BASE="${MOKOGIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          TOKEN="${{ github.token }}"
+          TAG="${{ steps.version.outputs.tag }}"
+          VERSION="${{ steps.version.outputs.version }}"
+          if [ ! -f manifest.json ]; then
+            echo "::warning::mokohub-manifest: no manifest.json at repo root — nothing to package"
+            exit 0
+          fi
+          ZIP="${RUNNER_TEMP:-/tmp}/manifest-${VERSION}.zip"
+          ( cd "$(dirname manifest.json)" && zip -j "$ZIP" manifest.json ) \
+            || { echo "::warning::mokohub-manifest: zip failed"; exit 0; }
+          RID=$(curl -sf -H "Authorization: token ${TOKEN}" "${API_BASE}/releases/tags/${TAG}" | python3 -c "import json,sys; print(json.load(sys.stdin).get('id',''))" 2>/dev/null || true)
+          if [ -z "$RID" ]; then echo "::warning::release ${TAG} not found — skipping manifest asset upload"; exit 0; fi
+          name="$(basename "$ZIP")"
+          curl -sf -X POST -H "Authorization: token ${TOKEN}" "${API_BASE}/releases/${RID}/assets?name=${name}" -F "attachment=@${ZIP}" >/dev/null \
+            && echo "attached ${name} to ${TAG}" || echo "::warning::manifest asset upload failed (${name})"
+
+      # -- mokohub-recipes: build catalog.zip (via MokoCLI) -> release per stream --
+      # ADDITIVE + GATED (Template-Generic#326). Delegate the per-stream signed
+      # catalog.zip (all recipes + all.json) to the MokoCLI build agent (`moko
+      # package`, MokoCLI #684 / epic mokohub-recipes#1). Gated on is_recipes;
+      # best-effort so a not-yet-shipped MokoCLI verb can't red an already-published
+      # release and no existing platform is affected.
+      - name: "Package mokohub-recipes (catalog.zip via MokoCLI)"
+        if: >-
+          steps.gate.outputs.has_makefile == 'true' &&
+          steps.mokohub.outputs.is_recipes == 'true' &&
+          steps.version.outputs.skip != 'true'
+        continue-on-error: true
+        run: |
+          API_BASE="${MOKOGIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          VERSION="${{ steps.version.outputs.version }}"
+          TAG="${{ steps.version.outputs.tag }}"
+          # `moko package` for the mokohub-recipes platform builds the stable-stream
+          # catalog.zip and attaches it to the release. --stability stable matches the
+          # auto-release (stable) channel; the platform shim selects the catalog builder.
+          moko package \
+            --path . --version "$VERSION" --tag "$TAG" \
+            --token "${{ github.token }}" --api-base "$API_BASE" \
+            --repo "${GIT_REPO}" --out "${RUNNER_TEMP:-/tmp}" \
+            --stability stable \
+            || echo "::warning::mokohub-recipes: moko package (catalog.zip) failed or unavailable — non-fatal (MokoCLI #684)"
+
+      - name: "Create semver tag for non-Joomla repos"
+        id: semver
+        # #469: a NEW immutable vNN tag is a version-bump artifact — skip it in
+        # no-bump mode (should_bump=false). The version did not advance, so the
+        # existing vNN tag already points at the current release; minting a new one
+        # would imply a new version. On the bump path this is unchanged.
+        if: |
+          steps.gate.outputs.has_makefile == 'true' &&
+          steps.srcgate.outputs.should_bump != 'false' &&
+          steps.version.outputs.skip != 'true' &&
+          !startsWith(steps.platform.outputs.platform, 'joomla') &&
+          (steps.electron.outputs.is_electron != 'true' || vars.ELECTRON_CI_BUILD == 'true')
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          API_BASE="${MOKOGIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          TOKEN="${{ github.token }}"
+          SEMVER_TAG="v${VERSION}"
+          # #386: pin the semver tag to the actual built/published commit (the
+          # post-publish HEAD the release/channel-tag is pinned to), NOT the
+          # triggering commit -- the publish step commits the CHANGELOG entry, so
+          # GITHUB_SHA is one commit stale.
+          BUILT_SHA="$(git rev-parse HEAD 2>/dev/null || echo "${GITHUB_SHA}")"
+
+          echo "Creating semver tag: ${SEMVER_TAG}"
+
+          # Create the git tag via API
+          HTTP_CODE=$(curl -sf -o /dev/null -w "%{http_code}" \
+            -X POST -H "Authorization: token ${TOKEN}" \
+            -H "Content-Type: application/json" \
+            "${API_BASE}/tags" \
+            -d "{\"tag_name\":\"${SEMVER_TAG}\",\"target\":\"${BUILT_SHA}\",\"message\":\"Release ${VERSION}\"}" 2>/dev/null || echo "000")
+
+          if [ "$HTTP_CODE" = "201" ] || [ "$HTTP_CODE" = "200" ]; then
+            echo "Created semver tag: ${SEMVER_TAG}"
+          elif [ "$HTTP_CODE" = "409" ]; then
+            echo "Semver tag ${SEMVER_TAG} already exists (skipped)"
+          else
+            echo "::warning::Failed to create semver tag ${SEMVER_TAG} (HTTP ${HTTP_CODE})"
+          fi
+
+          echo "semver_tag=${SEMVER_TAG}" >> "$GITHUB_OUTPUT"
+
+      # -- "Advance rolling channel tag via git" REMOVED (#1621 Phase 6) ---------
+      # This step force-pushed refs/tags/stable to the built HEAD so the #386 gate
+      # below would pass. It is now REDUNDANT: the publish already pins the `stable`
+      # channel ref via release_create's forceTagRef() (#808), and #1621 has the
+      # forge attach/move the channel tag onto the dual-tagged release server-side
+      # (channel_tags[] on create -> AttachChannelTag -> moveGitTag at the release
+      # commit). The #386 gate still resolves `tags/stable` to the built commit, so
+      # it stays valid without this duplicate git force-push.
+
+      - name: "Release integrity gate: artifact commit == tag commit (#386)"
+        if: steps.gate.outputs.has_makefile == 'true' && steps.version.outputs.skip != 'true' && (steps.electron.outputs.is_electron != 'true' || vars.ELECTRON_CI_BUILD == 'true')
+        # #386: assert the published tag's commit == the commit we actually built &
+        # published, and FAIL on a definite mismatch (a tag pinned to a commit we did
+        # NOT build -- e.g. a LATER branch HEAD advanced by a concurrent merge). The
+        # publish step commits the CHANGELOG entry ("build NN.NN.NN [skip ci]") and
+        # mokocli pins the tag to that POST-PUBLISH HEAD, which is one commit past the
+        # triggering GITHUB_SHA -- so BUILT must be the current HEAD, not GITHUB_SHA
+        # (using GITHUB_SHA false-failed every cut whose CHANGELOG wasn't pre-seeded on
+        # dev). Fail-OPEN on any ambiguity (no tag / unresolvable) so a good release is
+        # never falsely blocked.
+        run: |
+          set -uo pipefail
+          BUILT="$(git rev-parse HEAD 2>/dev/null || echo "${GITHUB_SHA}")"
+          # #386: assert against the MOVED channel pointer (the rolling "stable"
+          # tag, force-pinned to the built commit by release_create forceTagRef),
+          # NOT the immutable vNN.NN.NN minor tag. The version-primary /
+          # minor-identity model (#1621/#76/#1725) deliberately never re-points
+          # vNN.NN.NN on an in-place (#469/#772) cut, so checking
+          # steps.version.outputs.tag (= v${VERSION} on generic/non-Joomla)
+          # false-failed every no-bump release. joomla/electron already feed-tag
+          # "stable", which is why they never hit this.
+          TAG="stable"
+          API_BASE="${MOKOGIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          if [ -z "$TAG" ] || [ -z "$BUILT" ]; then
+            echo "::notice::integrity gate: missing tag or built SHA - skipping (fail-open)."; exit 0
+          fi
+          TAG_SHA=$(curl -sf -H "Authorization: token ${{ github.token }}" "${API_BASE}/tags/${TAG}" \
+            | python3 -c "import sys,json; print((json.load(sys.stdin).get('commit') or {}).get('sha',''))" 2>/dev/null || true)
+          if [ -z "$TAG_SHA" ]; then
+            echo "::notice::integrity gate: cannot resolve tag ${TAG} to a commit - skipping (fail-open)."; exit 0
+          fi
+          if [ "$TAG_SHA" != "$BUILT" ]; then
+            echo "::error::Release integrity FAIL (#386): built commit ${BUILT} != tag ${TAG} commit ${TAG_SHA}. Published artifact may not match its tag (pre-merge/advanced-branch race). Failing so a stale release cannot ship silently."
+            exit 1
+          fi
+          echo "Release integrity OK: tag ${TAG} -> ${BUILT}"
+
+      - name: Update release notes and reconcile changelog
+        if: steps.gate.outputs.has_makefile == 'true' && (steps.electron.outputs.is_electron != 'true' || vars.ELECTRON_CI_BUILD == 'true')
+        env:
+          # Admin-bypass token for the idempotent Contents-API changelog reconcile
+          # below (#510) — needed only on the fix/hotfix->main path (see comment).
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          API_BASE="${MOKOGIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          TOKEN="${{ github.token }}"
+
+          # Get the stable release info (version and ID).
+          # #1702 / .mokogit-private#76: resolve the current stable release by its
+          # CHANNEL POINTER (releases/channel/stable -> ReleaseStreamMap), not by a
+          # fixed tag_name=stable. Version-primary releases carry tag_name=vNN, so
+          # GET /releases/tags/stable no longer resolves the current stable release.
+          # Graceful fallback to the legacy tags/stable call for forges predating
+          # #1702 (the channel route 404s pre-rollout). Both return the same release
+          # JSON shape (id + name "... (VERSION: NN.NN.NN)").
+          RELEASE_JSON=$(curl -sf -H "Authorization: token ${TOKEN}" \
+            "${API_BASE}/releases/channel/stable" 2>/dev/null || true)
+          [ -z "$RELEASE_JSON" ] && RELEASE_JSON=$(curl -sf -H "Authorization: token ${TOKEN}" \
+            "${API_BASE}/releases/tags/stable" 2>/dev/null || true)
+          [ -z "$RELEASE_JSON" ] && RELEASE_JSON='{}'
+          RELEASE_ID=$(python3 -c "import json,sys; print(json.load(sys.stdin).get('id',''))" <<< "$RELEASE_JSON" 2>/dev/null || true)
+          # Extract version from release name (e.g. "06.17.00" or "v06.17.00")
+          VERSION=$(python3 -c "
+          import json, sys, re
+          r = json.load(sys.stdin)
+          name = r.get('name', '')
+          m = re.search(r'(\d+\.\d+\.\d+)', name)
+          print(m.group(1) if m else '')
+          " <<< "$RELEASE_JSON" 2>/dev/null || true)
+
+          # Extract [Unreleased] section via the shared mokocli command (#364 centralization).
+          NOTES=""
+          if [ -f "release_notes.md" ] && [ -s "release_notes.md" ]; then
+            NOTES="$(cat release_notes.md)"
+          fi
+          # #71 / #1725: fall back to the MINOR section of CHANGELOG when no curated
+          # release_notes.md. A stable release is identified by its MINOR (the VERSION
+          # resolved above from the release name is NN.NN.00 — the minor is the unit of
+          # release identity), and within-minor patch notes are ACCUMULATED under that
+          # one ## [NN.NN.00] heading. So read $VERSION — NOT [Unreleased], which the
+          # accumulate step just emptied — to get the whole minor's stacked notes.
+          # --channel stable makes an empty section fall back to the "Stable release"
+          # label rather than a bare "Release NN.NN.00".
+          if [ -z "$NOTES" ] && [ -f "CHANGELOG.md" ]; then
+            NOTES=$(php ${MOKO_CLI}/release_notes.php --path . --version "${VERSION:-Unreleased}" --channel stable 2>/dev/null || true)
+          fi
+          [ -z "$NOTES" ] && NOTES="Stable release"
+
+          # Update release body via API
+          if [ -n "$RELEASE_ID" ]; then
+            python3 -c "
+          import json, urllib.request
+          body = open('/dev/stdin').read()
+          payload = json.dumps({'body': body}).encode()
+          req = urllib.request.Request(
+              '${API_BASE}/releases/${RELEASE_ID}',
+              data=payload, method='PATCH',
+              headers={
+                  'Authorization': 'token ${TOKEN}',
+                  'Content-Type': 'application/json'
+              })
+          urllib.request.urlopen(req)
+          " <<< "$NOTES"
+            echo "Release notes updated (release_notes.md if present, else CHANGELOG.md)"
+          fi
+
+          # Bump-on-dev: the CHANGELOG [Unreleased] -> [version] promotion now
+          # happens on DEV pre-promotion (promote-rc's release_bump_dev.php step),
+          # so main INHERITS the already-promoted changelog via the merge and this
+          # step normally has nothing to do. We keep an idempotent reconcile here as
+          # a safety-net for the fix/hotfix->main path (a fix/* PR merges straight to
+          # main WITHOUT going through dev/promote-rc, so its [Unreleased] section was
+          # never promoted). changelog_promote.php --branch is idempotent (won't
+          # re-promote an existing version) and merges/normalizes, so on the dev path
+          # it is a no-op; on the fix path it promotes. Non-fatal (`|| true`): the
+          # release is already published, and on the dev path there is nothing to do.
+          if [ -n "$VERSION" ] && [ -f "CHANGELOG.md" ]; then
+            php ${MOKO_CLI}/changelog_promote.php --path . --version "$VERSION" --accumulate \
+              --branch "${{ github.event.repository.default_branch }}" --token "${GITHUB_TOKEN}" --api-base "${API_BASE}" \
+              || echo "::notice::changelog reconcile on main was a no-op or non-fatal (already promoted on dev)"
+            echo "Changelog reconciled on main for [${VERSION}] (idempotent, accumulate)"
+          fi
+
+      # Publish the stable release notes to mokolive (#470 / .mokogit-private#85).
+      # INERT BY DEFAULT: skips unless BOTH the MOKOLIVE_ENDPOINT and
+      # MOKOLIVE_RELEASE_NOTES_CATEGORY_ID repo/org variables are set, so the
+      # step is a no-op on every repo until an owner opts in. BEST-EFFORT:
+      # continue-on-error + an ntfy alert on failure, so it never red-fails a
+      # release that already published. Delegates to the MokoCLI companion
+      # subcommand release_publish_notes.php (MokoCLI#951, built in parallel) —
+      # the step is dependency-safe: if the token is unset it exits 0, and if the
+      # subcommand is absent the php call simply fails into the best-effort ntfy.
+      - name: Publish release notes to mokolive
+        if: steps.gate.outputs.has_makefile == 'true' && steps.version.outputs.skip != 'true' &&
+            vars.MOKOLIVE_ENDPOINT != '' && vars.MOKOLIVE_RELEASE_NOTES_CATEGORY_ID != ''
+        continue-on-error: true
+        env:
+          MOKOLIVE_API_TOKEN: ${{ secrets.MOKOLIVE_API_TOKEN }}
+          NTFY_TOPIC: ${{ vars.MOKOLIVE_NTFY_TOPIC || vars.NTFY_TOPIC || 'git-releases' }}
+        run: |
+          if [ -z "${MOKOLIVE_API_TOKEN:-}" ]; then echo "::notice::mokolive token unset; skipping release-notes publish"; exit 0; fi
+          # Resolve the PREVIOUS stable version so the subcommand can compute the
+          # bump against --min-bump. There is no steps.*.outputs for the prior
+          # version (the monotonic guard computes it locally but does not export
+          # it), so resolve it the same channel-first way the rest of this file
+          # does: GET releases/channel/stable -> release NAME "VERSION: NN.NN.NN",
+          # with the legacy tags/stable fallback for forges predating #1702. The
+          # `stable` channel still points at the PRIOR release at this point —
+          # the new release's channel-tag move happens in the publish step above,
+          # but this lookup runs on a fresh curl so empty/unresolved is fine
+          # (subcommand treats empty --prev-version as first-release -> publishes).
+          PREV_VERSION=""
+          PREV_JSON=$(curl -sf -H "Authorization: token ${{ github.token }}" \
+            "${MOKOGIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}/releases/channel/stable" 2>/dev/null || true)
+          [ -z "$PREV_JSON" ] && PREV_JSON=$(curl -sf -H "Authorization: token ${{ github.token }}" \
+            "${MOKOGIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}/releases/tags/stable" 2>/dev/null || true)
+          PREV_VERSION=$(printf '%s' "${PREV_JSON:-}" \
+            | grep -oE 'VERSION: [0-9]{2}\.[0-9]{2}\.[0-9]{2}' | grep -oE '[0-9]{2}\.[0-9]{2}\.[0-9]{2}' | head -n1 || true)
+          php ${MOKO_CLI}/release_publish_notes.php --path . \
+            --version "${{ steps.version.outputs.version }}" \
+            --prev-version "${PREV_VERSION}" \
+            --min-bump "${{ vars.MOKOLIVE_PUBLISH_BUMP || 'patch' }}" \
+            --endpoint "${{ vars.MOKOLIVE_ENDPOINT }}" \
+            --category-id "${{ vars.MOKOLIVE_RELEASE_NOTES_CATEGORY_ID }}" \
+            --token "${MOKOLIVE_API_TOKEN}" \
+            --software-slug "${{ vars.MOKOLIVE_SOFTWARE_SLUG || github.event.repository.name }}" \
+            --release-url "${MOKOGIT_URL}/${GIT_ORG}/${GIT_REPO}/releases/tag/${{ steps.version.outputs.tag }}" \
+          || curl -sS -H "Title: mokolive release-notes publish failed: ${GIT_REPO} ${{ steps.version.outputs.version }}" \
+                  -H "Tags: warning" -H "Priority: high" \
+                  -d "release:publish-notes failed for ${GIT_REPO} ${{ steps.version.outputs.version }}" \
+                  "${NTFY_URL}/${NTFY_TOPIC}" || true
+
+      # -- npm stable publish: ABSORBED from Template-NPM's retired npm-publish.yml
+      # Replaces the former "Dispatch npm publish" fan-out to the standalone
+      # npm-publish.yml. Dual-registry, idempotent, gated on the npm platform so
+      # every non-npm platform is 100% unaffected. MokoGIT npm registry uses the
+      # per-run Actions token (packages:write, least-privilege, no shared secret);
+      # npmjs.org uses NPM_TOKEN (best-effort, skipped if absent). A version already
+      # present on a registry is a no-op. Version is the Makefile PROJECT_VERSION
+      # (single source of truth), stamped into package.json in-tree only.
+      - name: "Setup Node (npm publish)"
+        if: steps.gate.outputs.has_makefile == 'true' && steps.npmpub.outputs.publishable == 'true' && (startsWith(steps.platform.outputs.platform, 'npm') || startsWith(steps.platform.outputs.platform, 'nodejs'))
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - name: "npm: resolve version, stamp package.json, build"
+        if: steps.gate.outputs.has_makefile == 'true' && steps.npmpub.outputs.publishable == 'true' && (startsWith(steps.platform.outputs.platform, 'npm') || startsWith(steps.platform.outputs.platform, 'nodejs'))
+        run: |
+          set -euo pipefail
+          VERSION=$(grep -E '^[[:space:]]*PROJECT_VERSION[[:space:]]*:?=' Makefile | head -1 | sed 's/.*=[[:space:]]*//' | tr -d '[:space:]')
+          [ -z "$VERSION" ] && { echo "::error::No PROJECT_VERSION in Makefile - cannot determine npm publish version."; exit 1; }
+          # Makefile PROJECT_VERSION is zero-padded NN.NN.NN (e.g. 01.00.01); npm needs
+          # strict semver (no leading zeros), so normalize before stamping.
+          SEMVER=$(printf '%s' "$VERSION" | awk -F. '{printf "%d.%d.%d",$1,$2,$3}')
+          npm version "$SEMVER" --no-git-tag-version --allow-same-version
+          npm ci --no-audit --no-fund || npm install --no-audit --no-fund
+          npm run build --if-present
+          echo "Prepared npm publish for ${SEMVER} (source: Makefile PROJECT_VERSION ${VERSION})"
+      - name: "npm: publish to the MokoGIT registry (per-run Actions token)"
+        if: steps.gate.outputs.has_makefile == 'true' && steps.npmpub.outputs.publishable == 'true' && (startsWith(steps.platform.outputs.platform, 'npm') || startsWith(steps.platform.outputs.platform, 'nodejs'))
+        env:
+          NODE_AUTH_TOKEN: ${{ github.token }}
+        run: |
+          set -euo pipefail
+          HOST="${MOKOGIT_URL#https://}"; OWNER="${GIT_ORG}"
+          REG="https://${HOST}/api/packages/${OWNER}/npm/"
+          echo "//${HOST}/api/packages/${OWNER}/npm/:_authToken=${NODE_AUTH_TOKEN}" > .npmrc
+          set +e; out="$(npm publish --ignore-scripts --registry "${REG}" 2>&1)"; rc=$?; set -e
+          rm -f .npmrc; echo "$out"
+          if [ "$rc" -eq 0 ]; then echo "Published to the MokoGIT registry."
+          elif printf '%s' "$out" | grep -qiE 'already exists|cannot publish over|EPUBLISHCONFLICT|409 Conflict'; then echo "::notice::MokoGIT registry already has this version - no-op (idempotent)."
+          else echo "::error::MokoGIT-registry publish FAILED (npm exit ${rc}) - NOT 'already published'. See the npm error above."; exit "$rc"; fi
+      - name: "npm: publish to npmjs.org (NPM_TOKEN, best-effort)"
+        if: steps.gate.outputs.has_makefile == 'true' && steps.npmpub.outputs.publishable == 'true' && (startsWith(steps.platform.outputs.platform, 'npm') || startsWith(steps.platform.outputs.platform, 'nodejs'))
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          set -euo pipefail
+          if [ -z "${NPM_TOKEN:-}" ]; then echo "::notice::NPM_TOKEN not set - skipping the public npmjs.org publish (MokoGIT registry is primary)."; exit 0; fi
+          echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc
+          set +e; out="$(npm publish --ignore-scripts --registry https://registry.npmjs.org/ --access public 2>&1)"; rc=$?; set -e
+          rm -f .npmrc; echo "$out"
+          if [ "$rc" -eq 0 ]; then echo "Published to npmjs.org."
+          elif printf '%s' "$out" | grep -qiE 'already exists|cannot publish over|EPUBLISHCONFLICT|409 Conflict'; then echo "::notice::npmjs.org already has this version - no-op."
+          elif printf '%s' "$out" | grep -qiE 'not in this registry|ENEEDAUTH|EOTP|need auth|E401|E403|401 Unauthorized|403 Forbidden|404 Not Found|Forbidden'; then echo "::error::npmjs.org publish FAILED — authorization error (npm exit ${rc}). NPM_TOKEN lacks publish/create rights on the @mokoconsulting scope (new-scoped-name first publish, an unauthorized token, or a revoked/expired token). Failing loud so a broken publish token cannot hide behind a green release — a 404 PUT is how npm masks an unauthorized scoped write."; exit "$rc"
+          else echo "::warning::npmjs.org publish failed (npm exit ${rc}) — transient/5xx/network issue; npmjs is the secondary mirror (MokoGIT registry is primary), not failing the run."; fi
+
+      # GitHub mirroring (release assets + main branch) moved to an out-of-band
+      # OAuth push-mirror (Gitea repo setting) -- former Steps 9 & 10 removed.
+
+      - name: "Step 11: Delete rc branch (dev reset moved to cascade.yml)"
+        if: steps.gate.outputs.has_makefile == 'true' && steps.version.outputs.skip != 'true'
+        continue-on-error: true
+        run: |
+          API_BASE="${MOKOGIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          TOKEN="${{ github.token }}"
+
+          # Delete rc branch (ephemeral -- created by promote-rc)
+          curl -sf -X DELETE -H "Authorization: token ${TOKEN}" \
+            "${API_BASE}/branches/rc" 2>/dev/null \
+            && echo "Deleted rc branch" || echo "rc branch not found"
+
+          # dev is reset from main by the fleet cascade workflow (cascade.yml, which
+          # rolled up the retired cascade-dev.yml): a push to main cascades down the
+          # ladder, recreating/resetting dev from main after this release completes.
+          echo "rc cleaned; dev reset handled by cascade.yml" >> $GITHUB_STEP_SUMMARY
+
+      # -- Version identity: #1621 Phase 6 retired the per-version branches ------
+      # The old "Step 12: Create version branch from main" and "Step 13: Prune
+      # superseded-major version branches" are REMOVED. A release's permanent
+      # version identity is now a git TAG (v<version>) attached by the publish as a
+      # movable channel tag on the dual-tagged release (MokoCLI release_publish ->
+      # release_create channel_tags[]/update_stream; MokoGIT #1621), not a
+      # version/* branch. No version/* consumer exists, so nothing creates them any
+      # more. Pruning EXISTING version/* branches is a SEPARATE one-time manual
+      # reconcile (do not prune here) — e.g. stop protecting version/* in
+      # cleanup.yml and let the stale-branch sweep retire them, or a one-shot fleet
+      # delete. See issue #1621 Phase 6.
+
+      # -- Post-release: Reset dev version (safety-net) ----------------
+      - name: "Post-release: Reset dev version"
+        if: steps.gate.outputs.has_makefile == 'true' && steps.version.outputs.skip != 'true'
+        continue-on-error: true
+        run: |
+          API_BASE="${MOKOGIT_URL}/api/v1/repos/${GIT_ORG}/${GIT_REPO}"
+          # Post-release SAFETY-NET: advance dev ABOVE the just-released version so the
+          # dev update channel always leads stable (a dev build X.Y.Z-dev sorts BELOW
+          # stable X.Y.Z, so dev MUST be bumped past the release or dev-channel updates
+          # vanish). #309/#900: this was previously a SILENT swallow — a failed advance
+          # under continue-on-error left the run green while dev drifted below stable.
+          # Now the failure is LOUD (::error:: + job summary), and on success we also
+          # explicitly (re)publish the leading dev build, because the advance commit is
+          # `[skip ci]` and matches pre-release.yml's paths-ignore, so it never auto-fires.
+          if php ${MOKO_CLI}/version_reset_dev.php \
+               --token "${{ github.token }}" --api-base "${API_BASE}" \
+               --branch dev --path . 2>&1; then
+            # Advance landed → publish the leading dev build (best-effort; the release
+            # already succeeded, so a publish hiccup must not red the pipeline).
+            curl -sf -X POST \
+              -H "Authorization: token ${{ github.token }}" \
+              -H "Content-Type: application/json" \
+              "${API_BASE}/actions/workflows/pre-release.yml/dispatches" \
+              -d '{"ref":"dev","inputs":{"stability":"development","ref":"dev"}}' \
+              && echo "Triggered pre-release (development) to publish the leading dev build." \
+              || echo "::warning::Could not dispatch pre-release; the leading dev build will publish on the next real dev push."
+          else
+            # Do NOT silently swallow: a failed advance means the dev channel falls
+            # BEHIND stable and dev-channel updates vanish fleet-wide. Surface loudly
+            # (the stable release already published, so this stays green via
+            # continue-on-error — but it is now impossible to miss).
+            echo "::error::Post-release dev-advance FAILED — dev did not move above the released version; the dev update channel will trail stable until fixed. Most likely the CI Actions token lacks MERGE rights on protected 'dev' (org merge-whitelist). See MokoCLI #900 / Template-Joomla #309."
+            {
+              echo "### ⚠️ Dev-advance FAILED (dev-channel will trail stable)"
+              echo ""
+              echo "\`version_reset_dev.php\` could not advance \`dev\` above the released version, so the dev update channel falls behind stable and dev-channel sites stop seeing updates."
+              echo ""
+              echo "Likely cause: the CI Actions token lacks **MERGE** rights on protected \`dev\` (org merge-whitelist). See **MokoCLI #900** / **Template-Joomla #309**."
+            } >> "$GITHUB_STEP_SUMMARY"
+          fi
+
+      # -- Summary --------------------------------------------------------------
+      - name: Pipeline Summary
+        if: always()
+        run: |
+          VERSION="${{ steps.bump.outputs.version || steps.version.outputs.version }}"
+          PLATFORM="${{ steps.platform.outputs.platform }}"
+          if [ "${{ steps.gate.outputs.has_makefile }}" != "true" ]; then
+            echo "## Release Skipped -- no Makefile" >> $GITHUB_STEP_SUMMARY
+            echo "No Makefile at the repository root -- this repo does not build a release." >> $GITHUB_STEP_SUMMARY
+          elif [ "${{ steps.version.outputs.skip }}" = "true" ]; then
+            echo "## Release Skipped" >> $GITHUB_STEP_SUMMARY
+            echo "No VERSION in README.md" >> $GITHUB_STEP_SUMMARY
+          elif [ "${{ steps.check.outputs.already_released }}" = "true" ]; then
+            echo "## Already Released -- ${VERSION}" >> $GITHUB_STEP_SUMMARY
+          else
+            # #469: label the run bump vs no-bump (update-in-place) for clarity.
+            MODE="Build & Release Complete"
+            [ "${{ steps.srcgate.outputs.should_bump }}" = "false" ] && MODE="Release Updated In Place (no bump, #469)"
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "## ${MODE} (${PLATFORM})" >> $GITHUB_STEP_SUMMARY
+            if [ "${{ steps.srcgate.outputs.should_bump }}" = "false" ]; then
+              echo "" >> $GITHUB_STEP_SUMMARY
+              echo "Non-source push (no \`SRC_DIR/\` change): refreshed the existing stable release in place — version unchanged, no new \`vNN\` tag (#469)." >> $GITHUB_STEP_SUMMARY
+            fi
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "| Step | Result |" >> $GITHUB_STEP_SUMMARY
+            echo "|------|--------|" >> $GITHUB_STEP_SUMMARY
+            echo "| Platform | \`${PLATFORM}\` |" >> $GITHUB_STEP_SUMMARY
+            echo "| Version | \`${VERSION}\` |" >> $GITHUB_STEP_SUMMARY
+            echo "| Branch | \`${{ steps.version.outputs.branch }}\` |" >> $GITHUB_STEP_SUMMARY
+            echo "| Tag | \`${{ steps.version.outputs.tag }}\` |" >> $GITHUB_STEP_SUMMARY
+            echo "| Release | [View](${MOKOGIT_URL}/${GIT_ORG}/${GIT_REPO}/releases/tag/${{ steps.version.outputs.tag }}) |" >> $GITHUB_STEP_SUMMARY
+          fi