gowalk-cicd 1.0.0

package/action/action.yml

@@ -0,0 +1,973 @@
+# Note: this file is ~800 lines, above the project's 400-line composite-
+# action guideline. The size pre-dates the cert-caching feature; the
+# signing + commit-back step, the AI-metadata phases, and the
+# export / upload chunk are candidates for extraction into separate
+# scripts under ``scripts/`` (similar to how prepare_signing.py /
+# cert_factory.py / keychain.py / profile_io.py split the cert +
+# profile lifecycle). Refactor is a separate concern tracked outside
+# this file.
+# autoupdate test: 2026-05-06
+name: iOS native TestFlight deploy
+description: >
+  Build a native Swift/SwiftUI iOS app on a macOS runner and upload it to
+  TestFlight. Provisions an Apple Distribution cert + App Store provisioning
+  profiles at runtime via the App Store Connect API and persists them under
+  ``creds/`` so subsequent runs reuse the same identity (cert auto-renews at
+  T-30 days). Caller workflow MUST grant ``permissions: contents: write`` so
+  the action can commit the refreshed signing identity back to the default
+  branch on push events. Only secrets required are the ASC API key trio.
+
+inputs:
+  project:
+    description: "Path to the .xcodeproj (or omit if using workspace)"
+    required: false
+    default: ""
+  workspace:
+    description: "Path to the .xcworkspace (takes precedence over project)"
+    required: false
+    default: ""
+  scheme:
+    description: "Xcode scheme to archive"
+    required: false
+    default: ""
+  configuration:
+    description: "Xcode build configuration"
+    required: false
+    default: ""
+  bundle-id:
+    description: "Application bundle identifier (must already exist in ASC)"
+    required: false
+    default: ""
+  team-id:
+    description: "Apple developer team identifier (10-char)"
+    required: false
+    default: ""
+  app-store-apple-id:
+    description: "App Store Connect numeric app id (for build-number lookup)"
+    required: false
+    default: ""
+  profile-name:
+    description: >
+      DEPRECATED (ignored). Profile names are now derived per-target from
+      PRODUCT_BUNDLE_IDENTIFIER as `CI-<bundle_id>`. Kept for backward
+      compatibility — passing a value emits a notice.
+    required: false
+    default: ""
+  upload:
+    description: "Set to 'false' to stop after producing the IPA"
+    required: false
+    default: "true"
+  archive:
+    description: >
+      Set to 'false' to skip archive + export + upload entirely. Useful for
+      PR / branch runs that only need to build and test without code signing
+      secrets. When 'false', `upload` is ignored.
+    required: false
+    default: "true"
+  run-tests:
+    description: "Set to 'false' to skip the simulator test stage"
+    required: false
+    default: ""
+  test-command:
+    description: >
+      Shell command used for the simulator test stage. Defaults to running
+      `bash Scripts/run-tests.sh` when that file exists, otherwise
+      `xcodebuild test` against the chosen scheme on a booted simulator with
+      code-signing disabled. Override to run a custom runner.
+    required: false
+    default: ""
+  test-destination:
+    description: >
+      Destination passed to the default `xcodebuild test` invocation when
+      `test-command` is empty and no `Scripts/run-tests.sh` is present.
+    required: false
+    default: ""
+  uses-non-exempt-encryption:
+    description: >
+      Value to set for ITSAppUsesNonExemptEncryption in Info.plist
+      (default: false). Set to 'true' only if the app uses custom crypto
+      beyond Apple-standard; set to empty string to skip the write entirely.
+    required: false
+    default: ""
+  app-store-whats-new:
+    description: >
+      What's New text for the App Store version (appStoreVersionLocalizations.whatsNew).
+      Multi-line OK. Empty = skip. First-release versions (1.0 / 0.0) are skipped.
+    required: false
+    default: ""
+  app-store-locale:
+    description: "Locale for App Store whatsNew (default: en-US)"
+    required: false
+    default: ""
+  ai-metadata:
+    description: "Auto-fill empty ASC metadata fields via GitHub Models AI. 'false' to disable."
+    required: false
+    default: "true"
+  ai-metadata-model:
+    description: "GitHub Models model id for AI metadata generation."
+    required: false
+    default: "openai/gpt-4o"
+  # DESIGN DECISION: marketing-version-auto-bump trades unattended-CI
+  # smoothness against silent-semver-decisions visibility. Default
+  # 'rollover' lets CI keep the build moving when ASC's combined floor
+  # advances ahead of the project's MARKETING_VERSION (typical cause:
+  # a manual TestFlight upload at a higher version, or a prior
+  # release moving to READY_FOR_SALE between commits). 'rollover'
+  # bumps the patch component with carry: at .9 it rolls into the
+  # next minor (1.0.9 -> 1.1.0), and at minor=9 it cascades into the
+  # next major (1.9.9 -> 2.0.0). This produces the more natural
+  # human-readable progression most projects want -- patch numbers
+  # never grow past 9 silently. The bumped value is written into the
+  # project file and committed back via the existing bot-commit step,
+  # so the change is visible in repo history.
+  #
+  # Other policies:
+  #   'patch' -- legacy unbounded patch bump (1.0.9 -> 1.0.10).
+  #     Preserved unchanged for backward compat with consumers
+  #     pinning the historical default; existing 0.0.27 callers that
+  #     set `marketing-version-auto-bump: 'patch'` keep their current
+  #     behavior. New installs get 'rollover'.
+  #   'minor' -- bump minor, reset patch to 0 (major.(max(minor)+1).0).
+  #     For projects that ship every release as a minor.
+  #   'none' -- preserve the historical "fail the build, ask the
+  #     human to bump" behavior when explicit semver control is
+  #     required (e.g. release-train workflows).
+  marketing-version-auto-bump:
+    description: >
+      When the ASC combined floor exceeds the project's MARKETING_VERSION,
+      automatically bump and stage the project file instead of failing.
+      Values: 'rollover' (default — patch with carry: 1.0.9 -> 1.1.0,
+      1.9.9 -> 2.0.0; major has no upper limit), 'patch' (legacy
+      unbounded: 1.0.9 -> 1.0.10), 'minor' (bump minor, reset patch
+      to 0), 'none' (preserve existing fail behavior; requires human
+      bump). The bumped value is committed alongside cert and
+      autoupdate changes via the existing commit-back step.
+    required: false
+    default: "rollover"
+  # DESIGN DECISION: auto-update defaults to 'true' as the explicit feature.
+  # Trust model documented in scripts/autoupdate_check.sh DESIGN DECISION
+  # block. Consumers can pin via `with: { auto-update: 'false' }`.
+  auto-update:
+    description: >
+      Per-run check for a newer gowalk-cicd on npm. When 'true'
+      (default), the action queries npm on default-branch push runs and
+      re-vendors the package via `npx --yes` if the published version is
+      newer than the marker at .github/actions/swift-app/.daemux-version.
+      The refreshed action files (NOT deploy.yml, which GITHUB_TOKEN
+      cannot push) are committed alongside any cert refresh in a single
+      combined commit. Set to 'false' to pin the vendored copy.
+    required: false
+    default: "true"
+
+runs:
+  using: composite
+  steps:
+    - name: Resolve credentials + auto-detect Xcode project
+      shell: bash
+      env:
+        INPUT_PROJECT: ${{ inputs.project }}
+        INPUT_WORKSPACE: ${{ inputs.workspace }}
+        INPUT_SCHEME: ${{ inputs.scheme }}
+        INPUT_CONFIGURATION: ${{ inputs.configuration }}
+        INPUT_BUNDLE_ID: ${{ inputs.bundle-id }}
+        INPUT_TEAM_ID: ${{ inputs.team-id }}
+        INPUT_APP_STORE_APPLE_ID: ${{ inputs.app-store-apple-id }}
+        INPUT_PROFILE_NAME: ${{ inputs.profile-name }}
+        INPUT_USES_NON_EXEMPT: ${{ inputs.uses-non-exempt-encryption }}
+        INPUT_WHATS_NEW: ${{ inputs.app-store-whats-new }}
+        INPUT_LOCALE: ${{ inputs.app-store-locale }}
+        INPUT_RUN_TESTS: ${{ inputs.run-tests }}
+        INPUT_TEST_COMMAND: ${{ inputs.test-command }}
+        INPUT_TEST_DESTINATION: ${{ inputs.test-destination }}
+      run: |
+        # read_config.py runs FIRST (it derives every other value), so it must
+        # install its full dep set inline. All later steps reuse these.
+        # No YAML loader needed — there is no config file.
+        python3 -m pip install --quiet --break-system-packages PyJWT cryptography requests
+        # xcodegen: when project.yml is present but .xcodeproj is not committed
+        # (common xcodegen flow), auto_detect will shell out to `xcodegen
+        # generate`. Install it here so the command is available. Idempotent:
+        # no-op when already present (GitHub-hosted macOS runners preinstall it).
+        if [ -f project.yml ] && ! command -v xcodegen >/dev/null 2>&1; then
+          echo "Installing xcodegen (project.yml present, binary missing)…"
+          brew install xcodegen >/dev/null 2>&1 || HOMEBREW_NO_AUTO_UPDATE=1 brew install xcodegen
+        fi
+        python3 "${{ github.action_path }}/scripts/read_config.py"
+
+    - name: Select latest Xcode
+      shell: bash
+      run: |
+        XCODE_PATH=$(ls -d /Applications/Xcode_26*.app 2>/dev/null | sort -V | tail -1)
+        if [ -z "$XCODE_PATH" ]; then
+          XCODE_PATH=$(ls -d /Applications/Xcode*.app 2>/dev/null | sort -V | tail -1)
+        fi
+        echo "Selecting $XCODE_PATH"
+        sudo xcode-select -s "$XCODE_PATH"
+        xcodebuild -version
+
+    - name: Run simulator tests
+      if: ${{ (inputs.run-tests || env.CFG_RUN_TESTS) == 'true' }}
+      shell: bash
+      env:
+        PROJECT: ${{ inputs.project || env.CFG_PROJECT }}
+        WORKSPACE: ${{ inputs.workspace || env.CFG_WORKSPACE }}
+        SCHEME: ${{ inputs.scheme || env.CFG_SCHEME }}
+        CONFIGURATION: ${{ inputs.configuration || env.CFG_CONFIGURATION }}
+        TEST_COMMAND: ${{ inputs.test-command || env.CFG_TEST_COMMAND }}
+        TEST_DESTINATION: >-
+          ${{ inputs.test-destination || env.CFG_TEST_DESTINATION
+              || 'platform=iOS Simulator,name=iPhone 15' }}
+      run: |
+        set -o pipefail
+        if [ -n "$TEST_COMMAND" ]; then
+          echo "Running custom test command: $TEST_COMMAND"
+          bash -c "$TEST_COMMAND"
+        elif [ -f "Scripts/run-tests.sh" ]; then
+          echo "Running Scripts/run-tests.sh"
+          bash Scripts/run-tests.sh
+        else
+          if [ -n "$WORKSPACE" ]; then
+            PROJ_ARGS=(-workspace "$WORKSPACE")
+          else
+            PROJ_ARGS=(-project "$PROJECT")
+          fi
+          echo "Running xcodebuild test on $TEST_DESTINATION"
+          xcodebuild \
+            "${PROJ_ARGS[@]}" \
+            -scheme "$SCHEME" \
+            -configuration "$CONFIGURATION" \
+            -destination "$TEST_DESTINATION" \
+            CODE_SIGNING_ALLOWED=NO \
+            CODE_SIGNING_REQUIRED=NO \
+            CODE_SIGN_IDENTITY="" \
+            DEVELOPMENT_TEAM="" \
+            test
+        fi
+
+    - name: Stage ASC API key for xcrun / altool
+      if: ${{ inputs.archive == 'true' }}
+      shell: bash
+      run: |
+        # SECURITY: never consume the raw key through an env var — GH Actions
+        # prints env: blocks on step-group expansion, which leaks secrets.
+        # read_config.py already validated creds/AuthKey_<KEY_ID>_Issuer_<UUID>.p8
+        # exists and exported ASC_KEY_P8_PATH; we copy the file on disk and
+        # stage it where xcrun/altool expect it (~/.appstoreconnect/private_keys).
+        : "${ASC_KEY_ID:?ASC_KEY_ID env var is required}"
+        : "${ASC_ISSUER_ID:?ASC_ISSUER_ID env var is required}"
+        : "${ASC_KEY_P8_PATH:?ASC_KEY_P8_PATH env var is required (set by read_config.py)}"
+        if [ ! -f "$ASC_KEY_P8_PATH" ]; then
+          echo "::error::ASC_KEY_P8_PATH points to missing file: $ASC_KEY_P8_PATH"
+          exit 1
+        fi
+        mkdir -p "$RUNNER_TEMP/asc"
+        cp "$ASC_KEY_P8_PATH" "$RUNNER_TEMP/asc/AuthKey.p8"
+        chmod 600 "$RUNNER_TEMP/asc/AuthKey.p8"
+        mkdir -p ~/.appstoreconnect/private_keys
+        cp "$RUNNER_TEMP/asc/AuthKey.p8" \
+          ~/.appstoreconnect/private_keys/AuthKey_${ASC_KEY_ID}.p8
+        echo "ASC_KEY_PATH=$RUNNER_TEMP/asc/AuthKey.p8" >> "$GITHUB_ENV"
+
+    - name: Resolve marketing version (project source of truth)
+      if: ${{ inputs.archive == 'true' }}
+      shell: bash
+      env:
+        PROJECT: ${{ inputs.project || env.CFG_PROJECT }}
+        WORKSPACE: ${{ inputs.workspace || env.CFG_WORKSPACE }}
+        SCHEME: ${{ inputs.scheme || env.CFG_SCHEME }}
+        CONFIGURATION: ${{ inputs.configuration || env.CFG_CONFIGURATION }}
+      run: |
+        set -o pipefail
+        python3 "${{ github.action_path }}/scripts/resolve_marketing_version.py" \
+          | tee -a "$GITHUB_ENV"
+
+    - name: Resolve App Store version slot (REUSE or CREATE)
+      if: ${{ inputs.archive == 'true' }}
+      shell: bash
+      env:
+        APP_STORE_APPLE_ID: ${{ inputs.app-store-apple-id || env.CFG_APP_STORE_APPLE_ID }}
+        # When the ASC combined floor exceeds the project's MARKETING_VERSION,
+        # mmv auto-bumps the project file (pbxproj or Info.plist) per this
+        # policy and continues. 'none' preserves the historical fail-the-
+        # build behavior.
+        MARKETING_VERSION_AUTO_BUMP: ${{ inputs.marketing-version-auto-bump }}
+        # Auto-bump persistence-context inputs. mmv_floor_check refuses to
+        # auto-bump unless this run is push-to-default-branch -- the same
+        # gate the commit-back step uses. Without this gate,
+        # workflow_dispatch / pull_request / feature-branch runs would
+        # auto-bump in-tree, archive an IPA at the bumped version, and
+        # then drop the bump on the floor (commit-back is gated to
+        # default-branch push). The next run would re-bump or drift.
+        GITHUB_EVENT_NAME: ${{ github.event_name }}
+        GITHUB_REF: ${{ github.ref }}
+        GITHUB_DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+        PROJECT: ${{ inputs.project || env.CFG_PROJECT }}
+        WORKSPACE: ${{ inputs.workspace || env.CFG_WORKSPACE }}
+        SCHEME: ${{ inputs.scheme || env.CFG_SCHEME }}
+        CONFIGURATION: ${{ inputs.configuration || env.CFG_CONFIGURATION }}
+      run: |
+        set -o pipefail
+        BUILD_NUMBER=$(python3 "${{ github.action_path }}/scripts/next_build_number.py")
+        DECISION_JSON=$(python3 "${{ github.action_path }}/scripts/manage_marketing_version.py")
+        APP_STORE_VERSION_ID=$(python3 -c \
+          "import json,sys; d=json.loads(sys.argv[1]); print(d.get('appStoreVersionId',''))" \
+          "$DECISION_JSON")
+        # The decision's versionString is authoritative: it reflects any
+        # auto-bump that mmv applied to MARKETING_VERSION when the project
+        # was below the ASC combined floor. Re-export so subsequent steps
+        # (Stamp Info.plist, Archive) see the bumped value.
+        EFFECTIVE_MV=$(python3 -c \
+          "import json,sys; d=json.loads(sys.argv[1]); print(d.get('versionString',''))" \
+          "$DECISION_JSON")
+        if [ -n "$EFFECTIVE_MV" ] && [ "$EFFECTIVE_MV" != "$MARKETING_VERSION" ]; then
+          echo "::notice::auto-bump rewrote MARKETING_VERSION $MARKETING_VERSION -> $EFFECTIVE_MV"
+          echo "MARKETING_VERSION=$EFFECTIVE_MV" >> "$GITHUB_ENV"
+          MARKETING_VERSION="$EFFECTIVE_MV"
+        fi
+        echo "BUILD_NUMBER=$BUILD_NUMBER" >> "$GITHUB_ENV"
+        echo "APP_STORE_VERSION_ID=$APP_STORE_VERSION_ID" >> "$GITHUB_ENV"
+        echo "Using marketing version $MARKETING_VERSION build $BUILD_NUMBER (decision=$DECISION_JSON)"
+
+    - name: Notice on deprecated profile-name input
+      if: ${{ inputs.archive == 'true' && inputs.profile-name != '' }}
+      shell: bash
+      run: |
+        echo "::notice::The 'profile-name' input is deprecated and ignored." \
+             "Profile names are derived per-target as CI-<bundle_id>."
+
+    - name: Prepare signing (cert + keychain + per-target profiles + pbxproj)
+      if: ${{ inputs.archive == 'true' }}
+      shell: bash
+      env:
+        PROJECT: ${{ inputs.project || env.CFG_PROJECT }}
+        WORKSPACE: ${{ inputs.workspace || env.CFG_WORKSPACE }}
+        TEAM_ID: ${{ inputs.team-id || env.CFG_TEAM_ID }}
+        CREDS_DIR: ${{ github.workspace }}/creds
+      run: python3 "${{ github.action_path }}/scripts/prepare_signing.py"
+
+    # DESIGN DECISION (intentional, not a bug):
+    # The next four steps stage + commit-back the Apple Distribution
+    # code-signing identity (.p12 + provisioning profiles) AND any
+    # autoupdate of the vendored app-ci actions into the consumer
+    # repo's default branch. This is a deliberate trade-off chosen over
+    # GitHub Secrets-based storage:
+    #   - Consumer repos already commit the ASC API key (.p8) to creds/, so
+    #     the threat model already accepts repo-stored Apple credentials.
+    #   - Each app uses a different Apple Developer account / .p8, so
+    #     org-level GitHub Secrets do not amortize setup work.
+    #   - "Drop file in creds/" remains the consistent UX for new projects.
+    # Non-negotiable mitigations (see IOS_NATIVE_CI_SETUP.md):
+    #   - Repo MUST stay private (branch protection on visibility recommended).
+    #   - permissions: contents: write is required; expands attack surface
+    #     of any compromised step in the workflow — keep workflow minimal.
+    #   - .gitignore must NOT block the new creds/ files (see setup doc).
+    #
+    # Split into four steps so cert refresh and autoupdate can both fire
+    # in a single combined commit when they coincide, but either can fire
+    # alone without redundant retries: (1) copy bot scripts to RUNNER_TEMP
+    # so autoupdate's `npx` cannot mid-run swap script bytes under us,
+    # (2) stage cert files, (3) check for newer app-ci on npm and
+    # stage refreshed action files, (4) commit + push whatever is staged.
+
+    # Stage scripts to RUNNER_TEMP so the autoupdate step's `npx` (which
+    # overwrites .github/actions/swift-app/ — the same dir as ${action_path}
+    # for local-action consumers) cannot mid-run swap the script bytes
+    # under us. action.yml step definitions are already loaded by the
+    # runner at job start, but the shell scripts are read fresh per step,
+    # so without this stage we'd risk loading commit_bot_changes.sh from
+    # the post-`npx` (newer) tree while the surrounding step definitions
+    # came from the pre-`npx` (older) action.yml — a mid-run version mix.
+    - name: Stage bot-side scripts to runner temp
+      if: ${{ (inputs.archive == 'true' || inputs.auto-update == 'true')
+            && github.event_name == 'push'
+            && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
+      shell: bash
+      run: |
+        set -euo pipefail
+        mkdir -p "$RUNNER_TEMP/swift-app-bot-scripts"
+        cp "${{ github.action_path }}/scripts/autoupdate_check.sh" \
+          "$RUNNER_TEMP/swift-app-bot-scripts/"
+        cp "${{ github.action_path }}/scripts/commit_bot_changes.sh" \
+          "$RUNNER_TEMP/swift-app-bot-scripts/"
+        chmod +x "$RUNNER_TEMP/swift-app-bot-scripts/"*.sh
+        echo "BOT_SCRIPTS_DIR=$RUNNER_TEMP/swift-app-bot-scripts" >> "$GITHUB_ENV"
+
+    - name: Stage refreshed signing identity
+      # Only stage on push to the default branch — PR runs and feature
+      # branches must NOT mutate creds/ (they'd race the default branch
+      # commit and clutter PR diffs). The signing identity is a long-lived
+      # artifact owned by the canonical branch.
+      if: ${{ inputs.archive == 'true'
+            && github.event_name == 'push'
+            && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
+      shell: bash
+      working-directory: ${{ github.workspace }}
+      run: |
+        set -euo pipefail
+        # Default checkout is shallow (fetch-depth=1). Pushing back to the
+        # default branch needs a full ref so git can rebase on top of any
+        # commits that landed since checkout — promote to a full clone.
+        # Either form may fail on already-deep checkouts; ignore non-zero.
+        git fetch --unshallow 2>/dev/null \
+          || git fetch --depth=2147483647 2>/dev/null \
+          || true
+        git config user.name 'github-actions[bot]'
+        git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+        # Stage ONLY the specific files prepare_signing.py manages — never
+        # `creds/` wholesale. The user's ASC .p8 key is already tracked
+        # (committed separately at setup) so `git add` of new files leaves
+        # it alone, but `creds/` may also hold notes, build artifacts, or
+        # other unmanaged files we MUST NOT commit. Each `git add -f`
+        # bypasses any consumer .gitignore that hides creds/. Missing
+        # files (shouldn't happen given step ordering, but defensive)
+        # produce a non-zero exit which we swallow — the commit-step is
+        # the source of truth for "is there anything to commit".
+        git add -f -- creds/cert.p12 2>/dev/null || true
+        git add -f -- creds/cert.meta.json 2>/dev/null || true
+        git add -f -- creds/profiles.manifest.json 2>/dev/null || true
+        # The whole profiles/ directory is action-managed (one
+        # .mobileprovision per signable bundle, GC'd when bundles are
+        # removed); staging the directory picks up adds + removes in one
+        # shot. Force-flag overrides any creds/profiles/ ignore rule.
+        git add -f -- creds/profiles/ 2>/dev/null || true
+        # Marketing-version auto-bump: NOTHING TO DO HERE.
+        # version_utils.write_marketing_version() does an immediate
+        # `git add -f -- <path>` right after the write, which captures
+        # the post-bump, pre-prepare_signing state in the index.
+        # prepare_signing.py later mutates the working-tree pbxproj
+        # for manual-signing settings, but those edits land only in
+        # the working tree -- the index keeps the version bump alone.
+        # The marker at $RUNNER_TEMP/swift-app-mv-bumped is for log /
+        # diagnostics; we surface it here so CI logs show exactly
+        # which file mmv touched.
+        bump_marker="$RUNNER_TEMP/swift-app-mv-bumped"
+        if [ -f "$bump_marker" ]; then
+          echo "auto-bump: marker present; the following file(s) were"
+          echo "auto-bumped and pre-staged by version_utils:"
+          sed 's/^/  /' "$bump_marker"
+        fi
+
+    - name: Check for app-ci update
+      # Same gate as cert staging: default branch + push event only.
+      # `auto-update` is on by default; consumers can pin via `false`.
+      # Runs from $BOT_SCRIPTS_DIR (RUNNER_TEMP) so its own `npx`
+      # overwriting ${action_path} mid-run can't swap the script under us.
+      if: ${{ inputs.auto-update == 'true'
+            && github.event_name == 'push'
+            && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
+      shell: bash
+      working-directory: ${{ github.workspace }}
+      run: bash "$BOT_SCRIPTS_DIR/autoupdate_check.sh"
+
+    - name: Commit + push staged bot changes
+      # Fires when EITHER cert staging OR autoupdate could have produced
+      # diffs. The script itself is a no-op when nothing is staged, so a
+      # PR / feature-branch run that somehow reaches this step does no
+      # harm — but we still gate on default-branch push for clarity.
+      # Runs from $BOT_SCRIPTS_DIR (RUNNER_TEMP) — see step above for why
+      # we don't read directly from ${action_path} after autoupdate.
+      if: ${{ (inputs.archive == 'true' || inputs.auto-update == 'true')
+            && github.event_name == 'push'
+            && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
+      shell: bash
+      working-directory: ${{ github.workspace }}
+      env:
+        GITHUB_REF_NAME: ${{ github.ref_name }}
+      run: bash "$BOT_SCRIPTS_DIR/commit_bot_changes.sh"
+
+    - name: Stamp Info.plist versions (CFBundleVersion + CFBundleShortVersionString)
+      if: ${{ inputs.archive == 'true' }}
+      shell: bash
+      env:
+        PROJECT: ${{ inputs.project || env.CFG_PROJECT }}
+        WORKSPACE: ${{ inputs.workspace || env.CFG_WORKSPACE }}
+        SCHEME: ${{ inputs.scheme || env.CFG_SCHEME }}
+        CONFIGURATION: ${{ inputs.configuration || env.CFG_CONFIGURATION }}
+      run: |
+        set -o pipefail
+        # Some Xcode projects hardcode CFBundleVersion / CFBundleShortVersionString
+        # as literal values in Info.plist instead of using $(CURRENT_PROJECT_VERSION)
+        # and $(MARKETING_VERSION) substitution. When that's the case, passing
+        # CURRENT_PROJECT_VERSION=N on the xcodebuild CLI has no effect on the
+        # archived plist and altool rejects the upload with
+        # `previousBundleVersion`. Stamp the resolved source Info.plist directly
+        # so the archive ships with the computed values regardless of whether
+        # the plist uses substitutions or hardcoded literals.
+        if [ -n "$WORKSPACE" ]; then
+          PROJ_ARGS=(-workspace "$WORKSPACE")
+          PROJ_BASE=$(dirname "$WORKSPACE")
+        else
+          PROJ_ARGS=(-project "$PROJECT")
+          PROJ_BASE=$(dirname "$PROJECT")
+        fi
+        # Try agvtool first — it's Apple's official tool and handles projects
+        # using the generic versioning system. Harmless no-op on projects
+        # without VERSIONING_SYSTEM set. Run from the project directory.
+        # Marketing version is intentionally NOT stamped here: the project's
+        # MARKETING_VERSION build setting is the single source of truth and
+        # was already resolved into env earlier; CI must never mutate it.
+        (
+          cd "$PROJ_BASE" 2>/dev/null || exit 0
+          xcrun agvtool new-version -all "$BUILD_NUMBER" >/dev/null 2>&1 || true
+        )
+        # Now resolve the actual Info.plist path and stamp literal values.
+        # This is idempotent with agvtool and also covers projects where the
+        # plist has hardcoded numbers (the sample1 failure mode).
+        INFOPLIST=$(xcodebuild "${PROJ_ARGS[@]}" -scheme "$SCHEME" -configuration "${CONFIGURATION:-Release}" \
+                      -showBuildSettings 2>/dev/null \
+                    | awk -F' = ' '/^[[:space:]]*INFOPLIST_FILE/ {
+                        gsub(/^[[:space:]]+|[[:space:]]+$/,"",$2); print $2; exit
+                      }')
+        if [ -z "$INFOPLIST" ]; then
+          echo "::warning::INFOPLIST_FILE not set for scheme $SCHEME; skipping version stamping"
+          exit 0
+        fi
+        INFOPLIST_PATH="$PROJ_BASE/$INFOPLIST"
+        if [ ! -f "$INFOPLIST_PATH" ]; then
+          INFOPLIST_PATH="$INFOPLIST"
+        fi
+        if [ ! -f "$INFOPLIST_PATH" ]; then
+          echo "::warning::Info.plist not found at $INFOPLIST_PATH; skipping version stamping"
+          exit 0
+        fi
+        /usr/libexec/PlistBuddy -c "Set :CFBundleVersion $BUILD_NUMBER" "$INFOPLIST_PATH" 2>/dev/null \
+          || /usr/libexec/PlistBuddy -c "Add :CFBundleVersion string $BUILD_NUMBER" "$INFOPLIST_PATH"
+        /usr/libexec/PlistBuddy -c "Set :CFBundleShortVersionString $MARKETING_VERSION" "$INFOPLIST_PATH" 2>/dev/null \
+          || /usr/libexec/PlistBuddy -c "Add :CFBundleShortVersionString string $MARKETING_VERSION" "$INFOPLIST_PATH"
+        echo "Stamped CFBundleVersion=$BUILD_NUMBER CFBundleShortVersionString=$MARKETING_VERSION in $INFOPLIST_PATH"
+
+    - name: Declare ITSAppUsesNonExemptEncryption in Info.plist
+      if: ${{ inputs.archive == 'true' && (inputs.uses-non-exempt-encryption || env.CFG_USES_NON_EXEMPT) != '' }}
+      shell: bash
+      env:
+        PROJECT: ${{ inputs.project || env.CFG_PROJECT }}
+        WORKSPACE: ${{ inputs.workspace || env.CFG_WORKSPACE }}
+        SCHEME: ${{ inputs.scheme || env.CFG_SCHEME }}
+        CONFIGURATION: ${{ inputs.configuration || env.CFG_CONFIGURATION }}
+        VALUE: ${{ inputs.uses-non-exempt-encryption || env.CFG_USES_NON_EXEMPT }}
+      run: |
+        set -o pipefail
+        if [ -n "$WORKSPACE" ]; then
+          PROJ_ARGS=(-workspace "$WORKSPACE")
+          PROJ_BASE=$(dirname "$WORKSPACE")
+        else
+          PROJ_ARGS=(-project "$PROJECT")
+          PROJ_BASE=$(dirname "$PROJECT")
+        fi
+        INFOPLIST=$(xcodebuild "${PROJ_ARGS[@]}" -scheme "$SCHEME" -configuration "${CONFIGURATION:-Release}" \
+                      -showBuildSettings 2>/dev/null \
+                    | awk -F' = ' '/^[[:space:]]*INFOPLIST_FILE/ {
+                        gsub(/^[[:space:]]+|[[:space:]]+$/,"",$2); print $2; exit
+                      }')
+        if [ -z "$INFOPLIST" ]; then
+          echo "::warning::INFOPLIST_FILE not set for scheme $SCHEME; skipping ITSAppUsesNonExemptEncryption"
+          exit 0
+        fi
+        INFOPLIST_PATH="$PROJ_BASE/$INFOPLIST"
+        if [ ! -f "$INFOPLIST_PATH" ]; then
+          INFOPLIST_PATH="$INFOPLIST"
+        fi
+        if [ ! -f "$INFOPLIST_PATH" ]; then
+          echo "::warning::Info.plist not found at $INFOPLIST_PATH; skipping"
+          exit 0
+        fi
+        /usr/libexec/PlistBuddy -c "Set :ITSAppUsesNonExemptEncryption $VALUE" "$INFOPLIST_PATH" 2>/dev/null \
+          || /usr/libexec/PlistBuddy -c "Add :ITSAppUsesNonExemptEncryption bool $VALUE" "$INFOPLIST_PATH"
+        echo "Set ITSAppUsesNonExemptEncryption=$VALUE in $INFOPLIST_PATH"
+
+    - name: Archive
+      if: ${{ inputs.archive == 'true' }}
+      shell: bash
+      env:
+        PROJECT: ${{ inputs.project || env.CFG_PROJECT }}
+        WORKSPACE: ${{ inputs.workspace || env.CFG_WORKSPACE }}
+        SCHEME: ${{ inputs.scheme || env.CFG_SCHEME }}
+        CONFIGURATION: ${{ inputs.configuration || env.CFG_CONFIGURATION }}
+      run: |
+        set -o pipefail
+        if [ -n "$WORKSPACE" ]; then
+          PROJ_ARGS=(-workspace "$WORKSPACE")
+        else
+          PROJ_ARGS=(-project "$PROJECT")
+        fi
+        # Manual signing. prepare_signing.py patched each signable target's
+        # build settings in-place (CODE_SIGN_STYLE=Manual,
+        # PROVISIONING_PROFILE_SPECIFIER=CI-<bundle_id>, etc) so xcodebuild
+        # just honors what's in the pbxproj. SwiftPM / resource-bundle
+        # targets are untouched and keep their default (no-sign) config.
+        # Speed: the index store is IDE-only overhead, and SwiftPM plugin/macro
+        # validation prompts have no place on a throwaway CI runner.
+        xcodebuild \
+          "${PROJ_ARGS[@]}" \
+          -scheme "$SCHEME" \
+          -configuration "$CONFIGURATION" \
+          -destination "generic/platform=iOS" \
+          -archivePath "$RUNNER_TEMP/app.xcarchive" \
+          -skipPackagePluginValidation \
+          -skipMacroValidation \
+          CURRENT_PROJECT_VERSION="$BUILD_NUMBER" \
+          MARKETING_VERSION="$MARKETING_VERSION" \
+          COMPILER_INDEX_STORE_ENABLE=NO \
+          archive
+
+    - name: Export IPA
+      if: ${{ inputs.archive == 'true' }}
+      shell: bash
+      run: |
+        set -o pipefail
+        # Manual signing: re-sign every target against its CI-<bundle_id>
+        # profile. exportArchive requires a full provisioningProfiles map
+        # in ExportOptions.plist for any entitlement that triggers
+        # validation (Personal VPN, NetworkExtension, Widgets, etc).
+        # signing_map.json also carries the ASC API key's effective team,
+        # which is what the profiles were actually issued under.
+        python3 - <<'PY'
+        import json
+        import os
+        from pathlib import Path
+        runner_temp = os.environ["RUNNER_TEMP"]
+        data = json.loads(
+            Path(runner_temp, "signing_map.json").read_text()
+        )
+        team_id = data["team_id"]
+        mapping = data["profiles"]
+        profile_entries = "".join(
+            f"    <key>{bid}</key><string>{name}</string>\n"
+            for bid, name in mapping.items()
+        )
+        plist = f"""<?xml version="1.0" encoding="UTF-8"?>
+        <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+        <plist version="1.0">
+        <dict>
+          <key>method</key><string>app-store-connect</string>
+          <key>destination</key><string>export</string>
+          <key>teamID</key><string>{team_id}</string>
+          <key>signingStyle</key><string>manual</string>
+          <key>stripSwiftSymbols</key><true/>
+          <key>uploadSymbols</key><true/>
+          <key>provisioningProfiles</key>
+          <dict>
+        {profile_entries}  </dict>
+        </dict>
+        </plist>
+        """
+        Path(runner_temp, "ExportOptions.plist").write_text(plist)
+        print(plist)
+        PY
+        xcodebuild \
+          -exportArchive \
+          -archivePath "$RUNNER_TEMP/app.xcarchive" \
+          -exportOptionsPlist "$RUNNER_TEMP/ExportOptions.plist" \
+          -exportPath "$RUNNER_TEMP/export"
+        ls -la "$RUNNER_TEMP/export"
+
+    - name: Upload to TestFlight
+      if: ${{ inputs.archive == 'true' && inputs.upload == 'true' }}
+      shell: bash
+      run: |
+        IPA=$(ls "$RUNNER_TEMP"/export/*.ipa | head -1)
+        echo "Uploading $IPA"
+        LOG="$RUNNER_TEMP/altool.log"
+        set +e
+        xcrun altool --upload-app \
+          --type ios \
+          --file "$IPA" \
+          --apiKey "$ASC_KEY_ID" \
+          --apiIssuer "$ASC_ISSUER_ID" \
+          --output-format normal 2>&1 | tee "$LOG"
+        ALTOOL_RC=${PIPESTATUS[0]}
+        set -e
+        # altool occasionally exits 0 even on failure; verify the final outcome marker.
+        # Apple's altool prints transient "ERROR:" lines for retried network blips
+        # before emitting "UPLOAD SUCCEEDED" — don't false-positive on those.
+        if [ "$ALTOOL_RC" -ne 0 ] \
+            || grep -qE '^Failed to upload|ERROR ITMS-' "$LOG" \
+            || ! grep -qE 'UPLOAD SUCCEEDED|No errors uploading archive' "$LOG"; then
+          echo "altool reported an upload failure (rc=$ALTOOL_RC)"
+          exit 1
+        fi
+        echo "Upload succeeded"
+
+    - name: Detect empty ASC metadata fields
+      id: detect_metadata
+      if: ${{ inputs.archive == 'true' && inputs.upload == 'true' && inputs.ai-metadata != 'false' }}
+      shell: bash
+      env:
+        APP_STORE_APPLE_ID: ${{ inputs.app-store-apple-id || env.CFG_APP_STORE_APPLE_ID }}
+        APP_STORE_VERSION_ID: ${{ env.APP_STORE_VERSION_ID }}
+      run: |
+        set -o pipefail
+        python3 "${{ github.action_path }}/scripts/asc_metadata_detector.py" \
+          > "$RUNNER_TEMP/asc_empty_metadata.json" || {
+            echo "::warning::metadata detector failed; skipping AI step"
+            echo "has_empty=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          }
+        HAS_EMPTY=$(python3 -c \
+          "import json,sys; d=json.load(open(sys.argv[1])); print('true' if d.get('empty_fields') else 'false')" \
+          "$RUNNER_TEMP/asc_empty_metadata.json")
+        LOCALES=$(python3 -c \
+          "import json,sys; d=json.load(open(sys.argv[1])); print(','.join(sorted(d.get('locales',[]))))" \
+          "$RUNNER_TEMP/asc_empty_metadata.json")
+        echo "has_empty=$HAS_EMPTY" >> "$GITHUB_OUTPUT"
+        echo "locales=$LOCALES" >> "$GITHUB_OUTPUT"
+        echo "AI metadata detector: has_empty=$HAS_EMPTY locales=[$LOCALES]"
+
+    - name: Scan repo for AI prompt context
+      if: ${{ steps.detect_metadata.outputs.has_empty == 'true' }}
+      shell: bash
+      env:
+        BUNDLE_ID: ${{ inputs.bundle-id || env.CFG_BUNDLE_ID }}
+        SCHEME: ${{ inputs.scheme || env.CFG_SCHEME }}
+      run: |
+        python3 "${{ github.action_path }}/scripts/app_context_scanner.py" \
+          > "$RUNNER_TEMP/app_context.txt"
+        wc -c "$RUNNER_TEMP/app_context.txt"
+
+    - name: Split empty_fields into Phase-1 (description) and Phase-2 (dependents)
+      id: derive_phases
+      if: ${{ steps.detect_metadata.outputs.has_empty == 'true' }}
+      shell: bash
+      run: |
+        # description is authoritative context for the dependent fields, so it
+        # is generated first (Phase 1) and injected into the Phase-2 prompt.
+        set -euo pipefail
+        python3 -m pip install --quiet --break-system-packages PyYAML
+        python3 - <<'PY'
+        import json, os, pathlib
+        temp = pathlib.Path(os.environ['RUNNER_TEMP'])
+        state = json.loads((temp / 'asc_empty_metadata.json').read_text())
+        empty = state.get('empty_fields') or {}
+        locales_needing_desc = sorted(loc for loc, fields in empty.items() if 'description' in fields)
+        non_desc = {loc: [f for f in fields if f != 'description'] for loc, fields in empty.items()}
+        non_desc = {loc: fields for loc, fields in non_desc.items() if fields}
+        (temp / 'locales_needing_description.json').write_text(json.dumps(locales_needing_desc))
+        (temp / 'empty_fields_excl_desc.json').write_text(json.dumps(non_desc))
+        with open(os.environ['GITHUB_OUTPUT'], 'a') as fh:
+            fh.write(f"needs_phase1={'true' if locales_needing_desc else 'false'}\n")
+            fh.write(f"needs_phase2={'true' if non_desc else 'false'}\n")
+        print(f"Phase-1 locales needing description: {locales_needing_desc}")
+        print(f"Phase-2 non-description empty fields: {non_desc}")
+        PY
+
+    - name: "Phase 1: Render descriptions prompt"
+      if: ${{ steps.derive_phases.outputs.needs_phase1 == 'true' }}
+      shell: bash
+      env:
+        TEMPLATE_PATH: ${{ github.action_path }}/prompts/generate_descriptions.prompt.yml
+      run: |
+        # Pre-render via PyYAML so multi-line app_context stays a block scalar
+        # and doesn't break ai-inference@v1's naive string substitution.
+        set -euo pipefail
+        python3 - <<'PY'
+        import os, pathlib, yaml
+        tmpl = yaml.safe_load(pathlib.Path(os.environ['TEMPLATE_PATH']).read_text())
+        temp = pathlib.Path(os.environ['RUNNER_TEMP'])
+        app_context = (temp / 'app_context.txt').read_text()
+        locales_json = (temp / 'locales_needing_description.json').read_text().strip()
+        for msg in tmpl.get('messages', []):
+            c = msg.get('content')
+            if isinstance(c, str):
+                msg['content'] = (
+                    c.replace('{{app_context}}', app_context)
+                     .replace('{{locales_needing_description}}', locales_json)
+                )
+        out = temp / 'rendered_phase1.yml'
+        out.write_text(yaml.safe_dump(tmpl, sort_keys=False, allow_unicode=True, default_flow_style=False))
+        print(f"Phase-1 prompt rendered -> {out} ({out.stat().st_size} bytes)")
+        PY
+
+    - name: "Phase 1: Generate descriptions via AI"
+      id: ai_phase1
+      if: ${{ steps.derive_phases.outputs.needs_phase1 == 'true' }}
+      # AI metadata is best-effort: a model API error (413 request-too-large,
+      # rate limit, outage) must never fail a build whose TestFlight upload
+      # already succeeded. The apply step below tolerates an empty response.
+      continue-on-error: true
+      uses: actions/ai-inference@v1
+      with:
+        prompt-file: ${{ runner.temp }}/rendered_phase1.yml
+        model: ${{ inputs.ai-metadata-model }}
+        max-tokens: 16000
+
+    - name: "Phase 1: Apply AI-generated descriptions"
+      id: phase1_apply
+      if: ${{ steps.derive_phases.outputs.needs_phase1 == 'true' }}
+      shell: bash
+      env:
+        APP_STORE_APPLE_ID: ${{ inputs.app-store-apple-id || env.CFG_APP_STORE_APPLE_ID }}
+        APP_STORE_VERSION_ID: ${{ env.APP_STORE_VERSION_ID }}
+        AI_RESPONSE: ${{ steps.ai_phase1.outputs.response }}
+      run: |
+        # Fence-strip + validate + apply description only. On parse failure
+        # emit phase1_ok=false so Phase-2 skips (architect §7: never regress
+        # to empty description by running dependents without a seed).
+        set -o pipefail
+        RAW="$RUNNER_TEMP/ai_descriptions.raw"
+        OUT="$RUNNER_TEMP/ai_descriptions.json"
+        printf '%s' "$AI_RESPONSE" > "$RAW"
+        echo "--- Phase-1 AI response: $(wc -c < "$RAW") bytes; first 200 chars ---"
+        head -c 200 "$RAW"; echo
+        echo "--- end preview ---"
+        python3 - "$RAW" "$OUT" <<'PY'
+        import pathlib, re, sys
+        src, dst = sys.argv[1], sys.argv[2]
+        text = pathlib.Path(src).read_text(encoding="utf-8").strip()
+        m = re.match(r"^```(?:json|yaml)?\s*\n(.*?)\n```\s*$", text, re.DOTALL)
+        if m:
+            text = m.group(1).strip()
+        pathlib.Path(dst).write_text(text, encoding="utf-8")
+        PY
+        if ! python3 -c "import json,sys; json.load(open(sys.argv[1]))" "$OUT"; then
+          echo "::warning::Phase-1 AI output not valid JSON; skipping Phase-2 to avoid empty-description regression"
+          head -c 500 "$OUT" || true
+          echo
+          echo "phase1_ok=false" >> "$GITHUB_OUTPUT"
+          exit 0
+        fi
+        python3 "${{ github.action_path }}/scripts/asc_metadata_applier.py" \
+          --state "$RUNNER_TEMP/asc_empty_metadata.json" \
+          --response "$OUT" \
+          --fields-filter description
+        echo "phase1_ok=true" >> "$GITHUB_OUTPUT"
+
+    - name: "Phase 2: Render dependent-fields prompt"
+      if: ${{ steps.derive_phases.outputs.needs_phase2 == 'true'
+            && (steps.derive_phases.outputs.needs_phase1 != 'true'
+                || steps.phase1_apply.outputs.phase1_ok == 'true') }}
+      shell: bash
+      env:
+        TEMPLATE_PATH: ${{ github.action_path }}/prompts/generate_dependent_fields.prompt.yml
+      run: |
+        # Merge existing_fields.{locale}.description with Phase-1 outputs to
+        # produce authoritative per-locale description context, then render
+        # the Phase-2 prompt with empty_fields_excl_desc.
+        set -euo pipefail
+        python3 - <<'PY'
+        import json, os, pathlib, sys, yaml
+        temp = pathlib.Path(os.environ['RUNNER_TEMP'])
+        state = json.loads((temp / 'asc_empty_metadata.json').read_text())
+        descriptions = {
+            loc: (fields.get('description') or '')
+            for loc, fields in (state.get('existing_fields') or {}).items()
+        }
+        ai_path = temp / 'ai_descriptions.json'
+        if ai_path.exists():
+            try:
+                ai_data = json.loads(ai_path.read_text())
+                for loc, fields in (ai_data.get('localizations') or {}).items():
+                    desc = (fields or {}).get('description')
+                    if desc:
+                        descriptions[loc] = desc
+            except json.JSONDecodeError as e:
+                print(
+                    f"::warning::ignoring corrupt {ai_path.name}: {e}; "
+                    f"falling back to existing descriptions",
+                    file=sys.stderr,
+                )
+        descriptions = {loc: d for loc, d in descriptions.items() if d}
+        (temp / 'descriptions_by_locale.json').write_text(json.dumps(descriptions, ensure_ascii=False))
+        tmpl = yaml.safe_load(pathlib.Path(os.environ['TEMPLATE_PATH']).read_text())
+        app_context = (temp / 'app_context.txt').read_text()
+        empty_excl = (temp / 'empty_fields_excl_desc.json').read_text().strip()
+        descriptions_json = json.dumps(descriptions, ensure_ascii=False)
+        for msg in tmpl.get('messages', []):
+            c = msg.get('content')
+            if isinstance(c, str):
+                msg['content'] = (
+                    c.replace('{{app_context}}', app_context)
+                     .replace('{{descriptions_by_locale}}', descriptions_json)
+                     .replace('{{empty_fields}}', empty_excl)
+                )
+        out = temp / 'rendered_phase2.yml'
+        out.write_text(yaml.safe_dump(tmpl, sort_keys=False, allow_unicode=True, default_flow_style=False))
+        print(f"Phase-2 prompt rendered -> {out} ({out.stat().st_size} bytes) with {len(descriptions)} descriptions")
+        PY
+
+    - name: "Phase 2: Generate dependent fields via AI"
+      id: ai_phase2
+      if: ${{ steps.derive_phases.outputs.needs_phase2 == 'true'
+            && (steps.derive_phases.outputs.needs_phase1 != 'true'
+                || steps.phase1_apply.outputs.phase1_ok == 'true') }}
+      # Best-effort (see Phase 1): never fail the build on a model API error.
+      continue-on-error: true
+      uses: actions/ai-inference@v1
+      with:
+        prompt-file: ${{ runner.temp }}/rendered_phase2.yml
+        model: ${{ inputs.ai-metadata-model }}
+        max-tokens: 16000
+
+    - name: "Phase 2: Apply AI-generated dependent fields"
+      if: ${{ steps.derive_phases.outputs.needs_phase2 == 'true'
+            && (steps.derive_phases.outputs.needs_phase1 != 'true'
+                || steps.phase1_apply.outputs.phase1_ok == 'true') }}
+      shell: bash
+      env:
+        APP_STORE_APPLE_ID: ${{ inputs.app-store-apple-id || env.CFG_APP_STORE_APPLE_ID }}
+        APP_STORE_VERSION_ID: ${{ env.APP_STORE_VERSION_ID }}
+        AI_RESPONSE: ${{ steps.ai_phase2.outputs.response }}
+      run: |
+        # Fence-strip + validate + apply filtered to dependent fields only;
+        # description is never overwritten in Phase-2.
+        set -o pipefail
+        RAW="$RUNNER_TEMP/ai_dependent.raw"
+        OUT="$RUNNER_TEMP/ai_dependent.json"
+        printf '%s' "$AI_RESPONSE" > "$RAW"
+        echo "--- Phase-2 AI response: $(wc -c < "$RAW") bytes; first 200 chars ---"
+        head -c 200 "$RAW"; echo
+        echo "--- end preview ---"
+        python3 - "$RAW" "$OUT" <<'PY'
+        import pathlib, re, sys
+        src, dst = sys.argv[1], sys.argv[2]
+        text = pathlib.Path(src).read_text(encoding="utf-8").strip()
+        m = re.match(r"^```(?:json|yaml)?\s*\n(.*?)\n```\s*$", text, re.DOTALL)
+        if m:
+            text = m.group(1).strip()
+        pathlib.Path(dst).write_text(text, encoding="utf-8")
+        PY
+        if ! python3 -c "import json,sys; json.load(open(sys.argv[1]))" "$OUT"; then
+          echo "::warning::Phase-2 AI output not valid JSON after fence strip; applier will fail-open"
+          head -c 500 "$OUT" || true
+          echo
+        fi
+        python3 "${{ github.action_path }}/scripts/asc_metadata_applier.py" \
+          --state "$RUNNER_TEMP/asc_empty_metadata.json" \
+          --response "$OUT" \
+          --fields-filter name,subtitle,keywords,promotionalText,whatsNew
+
+    # Runs unconditionally after the AI-metadata phase as a whatsNew backstop.
+    # An empty "What's New" makes a version un-submittable (ASC: "This field
+    # is required" on every locale). Previously this step was skipped whenever
+    # metadata was empty, deferring entirely to the AI phase — so when the AI
+    # call failed (e.g. a 413 on an app with 35 locales) every locale shipped
+    # blank. Now it always runs: with an explicit `app-store-whats-new` input
+    # it overwrites all locales; otherwise it fills ONLY still-empty locales
+    # with the default (CFG_WHATS_NEW), preserving any AI-generated notes.
+    - name: Set App Store "What's New"
+      if: ${{ inputs.archive == 'true' && inputs.upload == 'true'
+            && (inputs.app-store-whats-new != '' || env.CFG_WHATS_NEW != '') }}
+      shell: bash
+      env:
+        # Pass the whatsNew path, not the content. GitHub Actions ${{ }} YAML
+        # substitution can mangle multi-line strings; a file path is a
+        # single-line string that survives interpolation untouched. When the
+        # action caller supplies `app-store-whats-new` directly, we write it
+        # to a temp file here (still inside the run: block, so no ${{ }}
+        # re-interpolation of the multi-line value).
+        INPUT_WHATS_NEW: ${{ inputs.app-store-whats-new }}
+        APP_STORE_WHATS_NEW_FILE: ${{ env.CFG_WHATS_NEW_FILE }}
+        APP_STORE_LOCALE: ${{ inputs.app-store-locale || env.CFG_LOCALE }}
+      run: |
+        set -o pipefail
+        # No explicit caller text -> backstop mode: only fill locales whose
+        # whatsNew is still blank (don't clobber AI output). An explicit
+        # app-store-whats-new input forces the text onto every locale.
+        WHATS_NEW_ONLY_IF_EMPTY=true
+        if [ -n "$INPUT_WHATS_NEW" ]; then
+          INPUT_FILE="$RUNNER_TEMP/whats_new_input.txt"
+          printf '%s' "$INPUT_WHATS_NEW" > "$INPUT_FILE"
+          APP_STORE_WHATS_NEW_FILE="$INPUT_FILE"
+          WHATS_NEW_ONLY_IF_EMPTY=false
+        fi
+        export APP_STORE_WHATS_NEW_FILE WHATS_NEW_ONLY_IF_EMPTY
+        python3 "${{ github.action_path }}/scripts/set_app_store_whats_new.py"