impl-generate.yml

name: "Impl: Generate"
run-name: "Generate: ${{ inputs.library || github.event.label.name }} for ${{ inputs.specification_id || 'issue' }}"

# Generates single library implementation
# Triggers:
# - generate:{library} label on spec-ready issue
# - workflow_dispatch with specification_id + library
# Adopt mode (workflow_dispatch with source_ref): the implementation file is
# taken from that ref of origin instead of being generated, then rendered,
# reviewed, repaired and merged like a forced regeneration. source_model
# names the model that wrote it, recorded as generated_by.

on:
  issues:
    types: [labeled]
  workflow_dispatch:
    inputs:
      specification_id:
        description: "Specification ID (e.g., scatter-basic)"
        required: true
        type: string
      library:
        description: "Library to generate"
        required: true
        type: choice
        options:
          - matplotlib
          - seaborn
          - plotly
          - bokeh
          - altair
          - plotnine
          - pygal
          - highcharts
          - letsplot
          - ggplot2
          - makie
          - chartjs
          - d3
          - echarts
          - muix
      issue_number:
        description: "Issue number (optional, for tracking)"
        required: false
        type: string
      model:
        description: "Generation model (also threaded into repair); auto = opus for the pair's first implementation, sonnet for a regeneration. Reviews always run on opus (impl-review.yml)."
        required: false
        type: choice
        default: 'auto'
        options:
          - auto
          - haiku
          - sonnet
          - opus
      change_request:
        description: "One-sentence cross-library divergence hint from daily-regen pre-flight similarity audit (empty = none)"
        required: false
        type: string
        default: ''
      regen_gate:
        description: "Regen gate: when the pair already has an implementation on main, one review decides keep vs replace (no repair). false = forced regen through the old fresh-generation path (repair loop, cascading thresholds), labelled regen:forced"
        required: false
        type: boolean
        default: true
      source_ref:
        description: "Adopt mode: take the implementation file from this branch, tag or commit SHA of origin (e.g. main, gemini/muix-9) instead of generating it with Claude. Always a forced regeneration (regen:forced); model still threads to repair. Empty = generate."
        required: false
        type: string
        default: ''
      source_model:
        description: "Adopt mode only: the model that wrote the adopted implementation (e.g. gemini-4-argon), recorded as generated_by. Only with source_ref; empty keeps generated_by: adopted:<ref>."
        required: false
        type: string
        default: ''

# Global concurrency: max 3 concurrent implementation workflows
concurrency:
  group: impl-generate-${{ inputs.specification_id || github.event.issue.number }}-${{ inputs.library || github.event.label.name }}
  cancel-in-progress: false

jobs:
  generate:
    # Run on label trigger OR workflow_dispatch
    if: >
      (github.event_name == 'workflow_dispatch') ||
      (github.event_name == 'issues' && startsWith(github.event.label.name, 'generate:'))
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      actions: write
      id-token: write

    outputs:
      success: ${{ steps.result.outputs.success }}
      pr_number: ${{ steps.pr.outputs.pr_number }}

    steps:
      # Claude credentials: the repository variable CLAUDE_AUTH picks one mode
      # per run, and every Claude step below reads this step's outputs, so a
      # new mode changes only this step. Unset or `subscription`:
      # CLAUDE_CODE_OAUTH_TOKEN, as before; `api`: ANTHROPIC_API_KEY; `oidc`:
      # workload identity federation with the four CLAUDE_WIF_* variables,
      # which needs `id-token: write` on the job. Each Claude step gets
      # exactly one credential. An unknown value, or a mode whose credential
      # is missing, stops the job here, never a silent fallback to the
      # subscription. Identical in every job that runs Claude
      # (tests/unit/workflows/test_claude_auth.py);
      # docs/workflows/overview.md#claude-credentials.
      # First step: a stop here precedes "Set final issue number", so "Handle
      # generation failure" never counts it against the pair's attempts.
      - name: Resolve Claude credentials
        id: claude_auth
        env:
          CLAUDE_AUTH: ${{ vars.CLAUDE_AUTH }}
          API_KEY_SET: ${{ secrets.ANTHROPIC_API_KEY != '' }}
          OAUTH_TOKEN_SET: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN != '' }}
          WIF_RULE_ID: ${{ vars.CLAUDE_WIF_RULE_ID }}
          WIF_ORG_ID: ${{ vars.CLAUDE_WIF_ORG_ID }}
          WIF_SERVICE_ACCOUNT_ID: ${{ vars.CLAUDE_WIF_SERVICE_ACCOUNT_ID }}
          WIF_WORKSPACE_ID: ${{ vars.CLAUDE_WIF_WORKSPACE_ID }}
          EVENT: ${{ github.event_name }}
          REF: ${{ github.ref }}
        run: |
          fail() { echo "::error::$1; not falling back to the subscription"; exit 1; }
          mode="${CLAUDE_AUTH,,}"
          case "$mode" in
            ''|subscription) mode=subscription ;;
            api) [ "$API_KEY_SET" = "true" ] || fail "CLAUDE_AUTH is 'api' but the ANTHROPIC_API_KEY secret is missing" ;;
            oidc)
              # The federation rule accepts only `…:ref:refs/heads/main`. A
              # pull-request event (`…:pull_request`), another ref, and a job
              # without id-token run on the subscription instead, by design
              # and logged, never on an error.
              if [[ "$EVENT" == pull_request* || "$REF" != "refs/heads/main" || -z "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ]]; then
                where="${EVENT}/${REF//[^A-Za-z0-9\/._-]/?}$([ -n "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ] || echo ' (no id-token)')"
                if [ "$OAUTH_TOKEN_SET" != "true" ]; then
                  echo "::error::oidc not available for ${where}, and the CLAUDE_CODE_OAUTH_TOKEN secret is missing"
                  exit 1
                fi
                echo "::notice::oidc not available for ${where}; using subscription"
                echo "- oidc not available for ${where}; using subscription" >> "$GITHUB_STEP_SUMMARY"
                mode=subscription
              else
                for name in WIF_RULE_ID WIF_ORG_ID WIF_SERVICE_ACCOUNT_ID WIF_WORKSPACE_ID; do
                  [[ "${!name}" =~ ^[A-Za-z0-9_-]+$ ]] || fail "CLAUDE_AUTH is 'oidc' but the variable CLAUDE_${name} is missing or not an ID"
                done
                {
                  echo "federation_rule_id=$WIF_RULE_ID"
                  echo "organization_id=$WIF_ORG_ID"
                  echo "service_account_id=$WIF_SERVICE_ACCOUNT_ID"
                  echo "workspace_id=$WIF_WORKSPACE_ID"
                } >> "$GITHUB_OUTPUT"
              fi ;;
            *) fail "CLAUDE_AUTH must be unset, 'subscription', 'api' or 'oidc', got '${CLAUDE_AUTH//[^A-Za-z0-9 ._-]/?}'" ;;
          esac
          echo "mode=$mode" >> "$GITHUB_OUTPUT"
          echo "Claude credentials: $mode"

      # ========================================================================
      # Setup: Extract inputs and validate
      # ========================================================================
      # Checkout comes first: "Extract inputs" resolves the model from
      # origin/main (first implementation vs. regeneration), and every model
      # consumer below reads that one resolved value.
      - name: Checkout repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
        with:
          fetch-depth: 0

      - name: Extract inputs
        id: inputs
        env:
          LABEL_NAME: ${{ github.event.label.name }}
          ISSUE_TITLE: ${{ github.event.issue.title }}
          # Same expression as "Check for existing implementation": only an
          # explicit dispatch with regen_gate=false, or one that adopts a file
          # from source_ref, forces a regeneration.
          REGEN_GATE: ${{ (github.event_name == 'workflow_dispatch' && (inputs.regen_gate == false || inputs.source_ref != '')) && 'false' || 'true' }}
          # Via env, never interpolated into the script: free text from a dispatch.
          SOURCE_REF_INPUT: ${{ inputs.source_ref }}
          SOURCE_MODEL_INPUT: ${{ inputs.source_model }}
        run: |
          if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
            # From workflow_dispatch
            SPEC_ID="${{ inputs.specification_id }}"
            LIBRARY="${{ inputs.library }}"
            ISSUE="${{ inputs.issue_number }}"
            MODEL="${{ inputs.model }}"
          else
            # From label trigger: generate:{library}
            LIBRARY=$(echo "$LABEL_NAME" | sed 's/^generate://')
            # Extract spec ID from issue title: [spec-id] ...
            SPEC_ID=$(echo "$ISSUE_TITLE" | sed -n 's/^\[\([a-z0-9-]*\)\].*/\1/p')
            ISSUE="${{ github.event.issue.number }}"
            MODEL=""
          fi

          if [ -z "$SPEC_ID" ]; then
            echo "::error::Could not determine specification ID"
            exit 1
          fi

          if [ -z "$LIBRARY" ]; then
            echo "::error::Could not determine library"
            exit 1
          fi

          # Adopt mode: the implementation comes from this ref of origin
          # ("Adopt implementation from source ref") instead of Claude.
          # `git fetch origin <ref>` names the ref as origin itself knows it,
          # so a leading "origin/" (this checkout's remote-tracking name) is
          # dropped. The value reaches git, the PR body and the metadata, so
          # only branch, tag and SHA characters pass. A non-empty input never
          # becomes an empty ref: the REGEN_GATE expressions read the raw
          # input, so it must always mean adopt mode. A rejected value is
          # never echoed: a newline in it would start a workflow command.
          SOURCE_REF="${SOURCE_REF_INPUT:-}"
          SOURCE_REF="${SOURCE_REF#origin/}"
          if [ -n "${SOURCE_REF_INPUT:-}" ]; then
            if ! [[ "$SOURCE_REF" =~ ^[A-Za-z0-9][A-Za-z0-9._/-]{0,79}$ ]] || [[ "$SOURCE_REF" == *..* ]]; then
              echo "::error::source_ref is not a branch, tag or commit SHA (letters, digits, . _ / -, at most 80 characters)"
              exit 1
            fi
          fi

          # The model that wrote the adopted file outside the pipeline, such
          # as gemini-4-argon. It becomes the metadata's generated_by and
          # reaches the PR body, so only model-name characters pass, checked
          # before anything echoes it, and a rejected value is not echoed at
          # all. Without source_ref nothing is adopted, so the value is
          # dropped with a warning instead of naming a model that never wrote
          # this run's code.
          SOURCE_MODEL="${SOURCE_MODEL_INPUT:-}"
          if [ -n "$SOURCE_MODEL" ]; then
            if ! [[ "$SOURCE_MODEL" =~ ^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$ ]]; then
              echo "::error::source_model is not a model name (letters, digits, . _ -, at most 40 characters)"
              exit 1
            fi
            if [ -z "$SOURCE_REF" ]; then
              echo "::warning::source_model '${SOURCE_MODEL}' ignored: it names the author of an adopted file and needs source_ref"
              SOURCE_MODEL=""
            fi
          fi

          # Derive LANGUAGE + EXT from LIBRARY. Mirrors core/constants.py LIBRARIES_METADATA;
          # new non-Python entries get listed here too.
          case "$LIBRARY" in
            ggplot2)
              LANGUAGE="r"
              EXT=".R"
              ;;
            makie)
              LANGUAGE="julia"
              EXT=".jl"
              ;;
            chartjs|d3|echarts|highcharts)
              LANGUAGE="javascript"
              EXT=".js"
              ;;
            muix)
              # MUI X — JavaScript with framework=react, authored as TSX and
              # bundled through the render harness's esbuild React branch.
              LANGUAGE="javascript"
              EXT=".tsx"
              ;;
            *)
              LANGUAGE="python"
              EXT=".py"
              ;;
          esac

          # Model routing. An explicit model always wins: any dispatch input
          # other than "auto", including the model a failed run forwards to its
          # own retry. Without one ("auto" from bulk-generate, daily-regen or
          # the watchdog; empty on the label trigger) a pair's first
          # implementation runs on opus and a regeneration on sonnet, except a
          # forced one (regen_gate=false, or adopt mode), which runs on opus.
          # In adopt mode no model generates; the value only runs repair. "First"
          # means no implementation file on origin/main yet. The resolved value
          # is threaded into repair and recorded in the PR body, so one PR
          # generates and repairs on one model. Reviews are not routed here:
          # impl-review.yml runs every review on opus (its review_model input).
          if [ -n "$MODEL" ] && [ "$MODEL" != "auto" ]; then
            MODEL_REASON="explicit input"
          else
            # Without origin/main every pair would look like a first run and
            # silently land on opus, so stop instead of guessing.
            if ! git rev-parse -q --verify origin/main >/dev/null \
               && ! git fetch -q origin +refs/heads/main:refs/remotes/origin/main; then
              echo "::error::origin/main unavailable — cannot route the model"
              exit 1
            fi
            if git cat-file -e "origin/main:plots/$SPEC_ID/implementations/$LANGUAGE/$LIBRARY$EXT" 2>/dev/null; then
              if [ "$REGEN_GATE" = "false" ]; then
                # A forced regeneration skips the regen gate and goes through
                # the fresh-generation path (repair loop, cascading
                # thresholds), so it runs on opus like a first implementation.
                MODEL="opus"
                MODEL_REASON="forced regeneration"
              else
                MODEL="sonnet"
                MODEL_REASON="regeneration"
              fi
            else
              MODEL="opus"
              MODEL_REASON="first implementation"
            fi
          fi

          echo "specification_id=$SPEC_ID" >> $GITHUB_OUTPUT
          echo "library=$LIBRARY" >> $GITHUB_OUTPUT
          echo "language=$LANGUAGE" >> $GITHUB_OUTPUT
          echo "ext=$EXT" >> $GITHUB_OUTPUT
          echo "issue_number=$ISSUE" >> $GITHUB_OUTPUT
          echo "model=$MODEL" >> $GITHUB_OUTPUT
          echo "model_reason=$MODEL_REASON" >> $GITHUB_OUTPUT
          echo "source_ref=$SOURCE_REF" >> $GITHUB_OUTPUT
          echo "source_model=$SOURCE_MODEL" >> $GITHUB_OUTPUT

          if [ -n "$SOURCE_REF" ]; then
            # No pipeline model writes the code (source_model, when given,
            # names the one that did); the resolved model still runs repair.
            {
              echo "**Generation:** adopted from \`${SOURCE_REF}\`${SOURCE_MODEL:+ by ${SOURCE_MODEL}}"
              echo ""
              echo "**Repair model:** ${MODEL} (${MODEL_REASON})"
            } >> "$GITHUB_STEP_SUMMARY"
            echo "::notice::Adopting $LANGUAGE/$LIBRARY for $SPEC_ID (issue: ${ISSUE:-none}, generation: adopted from ${SOURCE_REF}${SOURCE_MODEL:+ by ${SOURCE_MODEL}}, repair model: ${MODEL} (${MODEL_REASON}), ext: ${EXT})"
          else
            echo "**Model:** ${MODEL} (${MODEL_REASON})" >> "$GITHUB_STEP_SUMMARY"
            echo "::notice::Generating $LANGUAGE/$LIBRARY for $SPEC_ID (issue: ${ISSUE:-none}, model: ${MODEL} (${MODEL_REASON}), ext: ${EXT})"
          fi

      - name: Read issue number from specification.yaml (fallback)
        id: spec_issue
        if: steps.inputs.outputs.issue_number == ''
        env:
          SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
        run: |
          SPEC_YAML="plots/${SPEC_ID}/specification.yaml"
          if [ -f "$SPEC_YAML" ]; then
            # Extract issue number using yq for robust YAML parsing
            ISSUE=$(yq '.issue' "$SPEC_YAML" 2>/dev/null || echo "")
            if [ -n "$ISSUE" ] && [ "$ISSUE" != "null" ]; then
              echo "issue_number=$ISSUE" >> $GITHUB_OUTPUT
              echo "::notice::Found issue #$ISSUE from specification.yaml"
            else
              echo "issue_number=" >> $GITHUB_OUTPUT
              echo "::warning::No issue number in specification.yaml"
            fi
          else
            echo "issue_number=" >> $GITHUB_OUTPUT
            echo "::warning::specification.yaml not found"
          fi

      # Consolidate issue number from inputs or fallback
      - name: Set final issue number
        id: issue
        run: |
          ISSUE="${{ steps.inputs.outputs.issue_number || steps.spec_issue.outputs.issue_number }}"
          echo "number=$ISSUE" >> $GITHUB_OUTPUT
          if [ -n "$ISSUE" ]; then
            echo "::notice::Using issue #$ISSUE for tracking"
          else
            echo "::warning::No issue number available - PR will not have Parent Issue link"
          fi

      - name: Validate specification exists
        env:
          SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
        run: |
          if [ ! -f "plots/${SPEC_ID}/specification.md" ]; then
            echo "::error::Specification not found: plots/${SPEC_ID}/specification.md"
            exit 1
          fi

      - name: Reopen issue if closed
        if: steps.issue.outputs.number != ''
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          ISSUE: ${{ steps.issue.outputs.number }}
        run: |
          # Reopen issue so it's visible during implementation
          gh issue reopen "$ISSUE" 2>/dev/null || true

      - name: Add pending label
        if: steps.issue.outputs.number != ''
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          LIBRARY: ${{ steps.inputs.outputs.library }}
          ISSUE: ${{ steps.issue.outputs.number }}
        run: |
          gh issue edit "$ISSUE" --add-label "impl:${LIBRARY}:pending" 2>/dev/null || true

      # ========================================================================
      # Setup: Python and dependencies (always installed — needed for image
      # processing + metadata writing even for non-Python implementations).
      # ========================================================================
      - name: Set up Python
        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0  # v7.1.0
        with:
          python-version: '3.14'

      - name: Install uv
        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3

      - name: Install system dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y pngquant

      - name: Install Python plotting dependencies
        if: steps.inputs.outputs.language == 'python'
        env:
          LIBRARY: ${{ steps.inputs.outputs.library }}
        run: |
          # The lib-${LIBRARY} extra exactly as uv.lock pins it (`--frozen`: never
          # re-resolve), the way agents/renderer/Dockerfile and CI install. The
          # former `uv pip install -e ".[lib-X]"` resolved pyproject.toml's ranges
          # afresh, so Dependabot's lock bumps never reached the pipeline and the
          # recorded library_version drifted from the lock. The base set carries
          # pillow and pyyaml; `dev` carries ruff. Creates .venv.
          uv sync --frozen --extra "lib-${LIBRARY}" --extra dev

      - name: Install Python helper deps (for non-Python implementations)
        if: steps.inputs.outputs.language != 'python'
        run: |
          # ggplot2 / future non-Python libs render via their own runtime,
          # but the pipeline still uses Python for metadata + image post-processing.
          uv venv .venv
          source .venv/bin/activate
          uv pip install pillow pyyaml

      - name: Setup R + ggplot2
        if: steps.inputs.outputs.language == 'r'
        uses: ./.github/actions/setup-r

      - name: Setup Julia + Makie
        if: steps.inputs.outputs.language == 'julia'
        uses: ./.github/actions/setup-julia

      - name: Setup Node + browser render harness
        if: steps.inputs.outputs.language == 'javascript'
        uses: ./.github/actions/setup-node

      # ========================================================================
      # Generate: Create implementation branch and code
      # ========================================================================
      - name: Create implementation branch
        id: branch
        env:
          SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
          LIBRARY: ${{ steps.inputs.outputs.library }}
        run: |
          BRANCH="implementation/${SPEC_ID}/${LIBRARY}"
          echo "branch=$BRANCH" >> $GITHUB_OUTPUT

          # Delete branch if exists (regeneration)
          git push origin --delete "$BRANCH" 2>/dev/null || true

          # Create fresh branch from main
          git checkout -b "$BRANCH" origin/main
          echo "::notice::Created branch: $BRANCH"

      - name: Check for existing implementation (regeneration)
        id: existing
        env:
          SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
          LANGUAGE: ${{ steps.inputs.outputs.language }}
          LIBRARY: ${{ steps.inputs.outputs.library }}
          EXT: ${{ steps.inputs.outputs.ext }}
          # Label-triggered runs have no inputs: only an explicit dispatch with
          # regen_gate=false, or one that adopts from source_ref, opts out
          # (null == false is true in expressions, hence the event_name guard).
          REGEN_GATE: ${{ (github.event_name == 'workflow_dispatch' && (inputs.regen_gate == false || inputs.source_ref != '')) && 'false' || 'true' }}
          SOURCE_REF: ${{ steps.inputs.outputs.source_ref }}
        run: |
          METADATA_FILE="plots/${SPEC_ID}/metadata/${LANGUAGE}/${LIBRARY}.yaml"
          IMPL_FILE="plots/${SPEC_ID}/implementations/${LANGUAGE}/${LIBRARY}${EXT}"

          if [ -f "$METADATA_FILE" ] && [ -f "$IMPL_FILE" ]; then
            echo "is_regeneration=true" >> $GITHUB_OUTPUT
            echo "::notice::Regeneration detected - will read previous review feedback"
          else
            echo "is_regeneration=false" >> $GITHUB_OUTPUT
          fi

          # Regen gate marker. impl-review.yml decides "regen" on its own from
          # origin/main (implementation file present) — these labels are for
          # humans and the watchdog, except `regen:forced`, which opts the PR
          # out of the gate. Keyed on the implementation file alone, the same
          # test impl-review uses.
          if [ -f "$IMPL_FILE" ]; then
            if [ "$REGEN_GATE" = "false" ]; then
              echo "regen_label=regen:forced" >> $GITHUB_OUTPUT
              if [ -n "$SOURCE_REF" ]; then
                echo "::notice::Forced regeneration (adopted from ${SOURCE_REF}) — fresh-generation review path"
              else
                echo "::notice::Forced regeneration (regen_gate=false) — fresh-generation review path"
              fi
            else
              echo "regen_label=regen" >> $GITHUB_OUTPUT
              echo "::notice::Gated regeneration — one review decides keep vs replace"
            fi
          else
            echo "regen_label=" >> $GITHUB_OUTPUT
          fi

      - name: Extract previous review feedback (regeneration)
        id: prev_review
        if: steps.existing.outputs.is_regeneration == 'true'
        env:
          SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
          LANGUAGE: ${{ steps.inputs.outputs.language }}
          LIBRARY: ${{ steps.inputs.outputs.library }}
        run: |
          # Shared extractor (also used by impl-review.yml): writes
          # /tmp/anyplot-prev-review.md with stable weakness ids W1..Wn (each
          # tagged defect, suggestion or older review), the same ids the regen
          # review refers to in review_regen.json, and the spec's
          # characteristic bullets C1..Cn, so the generator can name the
          # bullet that makes a weakness obsolete.
          .venv/bin/python3 automation/scripts/regen_gate.py context \
            --metadata "plots/${SPEC_ID}/metadata/${LANGUAGE}/${LIBRARY}.yaml" \
            --spec-id "$SPEC_ID" --language "$LANGUAGE" --library "$LIBRARY" \
            --spec-file "plots/${SPEC_ID}/specification.md" \
            --out-md /tmp/anyplot-prev-review.md \
            --out-weaknesses /tmp/anyplot-prev-weaknesses.json
          echo "::notice::Extracted previous review to /tmp/anyplot-prev-review.md"

      - name: Ensure implementation directories exist
        env:
          SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
          LANGUAGE: ${{ steps.inputs.outputs.language }}
        run: |
          mkdir -p "plots/${SPEC_ID}/implementations/${LANGUAGE}"
          mkdir -p "plots/${SPEC_ID}/metadata/${LANGUAGE}"
          echo "::notice::Ensured implementation + metadata directories exist for language '${LANGUAGE}'"

      - name: Stage change_request hint (cross-library divergence)
        if: ${{ inputs.change_request != '' }}
        env:
          CHANGE_REQUEST: ${{ inputs.change_request }}
        run: |
          # Written to a file so the prompt template stays variable-free; impl-generate-claude.md
          # checks for the file's existence and reads it if present.
          printf '%s\n' "$CHANGE_REQUEST" > /tmp/anyplot-change-request.txt
          echo "::notice::Change request staged: ${CHANGE_REQUEST}"

      # When triggered from a non-main branch via workflow_dispatch (typical for
      # iterative prompt-change testing), overlay the trigger branch's prompts/
      # directory onto the implementation branch (which was just created from
      # main). Claude commits only the implementation file (see Step 7 of
      # impl-generate-claude.md → `git add plots/.../{LIBRARY}{EXT}`), so the
      # overlaid prompts/ never end up in the resulting PR. The later "Create
      # library metadata file" step re-checks out origin/$BRANCH, which discards
      # the overlay automatically. No-op on main + on label triggers.
      #
      # FETCH_HEAD is used instead of origin/<name> so the step also works for
      # tag and SHA refs (where origin/<name> isn't created). The existence
      # check for prompts/ guards refs without that tree. impl-generate-claude.md
      # is always restored from the implementation branch (= main) after the
      # overlay, so a branch can't override Claude's `git add plots/...` safety
      # contract by editing that one file. Adopt mode runs no Claude step, so
      # it skips the overlay and the PR never carries prompts/.
      - name: Overlay prompts/ from trigger ref (branch-level prompt iteration)
        if: github.ref_name != 'main' && github.event_name == 'workflow_dispatch' && steps.inputs.outputs.source_ref == ''
        env:
          TRIGGER_REF: ${{ github.ref_name }}
        run: |
          if ! git fetch origin "$TRIGGER_REF" 2>/dev/null; then
            echo "::notice::Trigger ref $TRIGGER_REF not found on origin — skipping overlay (workflow runs against main's prompts)"
            exit 0
          fi
          if ! git ls-tree FETCH_HEAD -- prompts/ 2>/dev/null | grep -q .; then
            echo "::notice::Trigger ref $TRIGGER_REF has no prompts/ tree — skipping overlay"
            exit 0
          fi
          git checkout FETCH_HEAD -- prompts/
          # Always restore impl-generate-claude.md from main: it tells Claude
          # `git add plots/.../{LIBRARY}{EXT}` (Step 7), which is what keeps
          # the overlaid prompts/ out of the resulting PR. Letting a feature
          # branch override that instruction defeats the safety contract above.
          git checkout HEAD -- prompts/workflow-prompts/impl-generate-claude.md
          echo "::notice::Overlaid prompts/ from $TRIGGER_REF (impl-generate-claude.md kept from main for safety)"

      # Adopt mode (source_ref set): the implementation comes from a ref of
      # origin, typically a `gemini/*` branch that migrated it, instead of
      # from Claude. The step does what the generator does in Steps 3, 3b and
      # 7 of impl-generate-claude.md: it takes exactly the file the generator
      # would write, renders it in both themes with the same commands, checks
      # the canvas with core.canvas, and commits and pushes that one file to
      # the implementation branch. Every later step runs as for a generated
      # file. Python and JavaScript only: R and Julia have no adopt render yet.
      # A failure of the source writes `cause` first (missing, render,
      # unsupported), so "Handle generation failure" knows that every retry
      # would read the same file and fail the same way. A failure of the
      # runner (origin unreachable, numpy not installable, the canvas check
      # crashing, the push) writes none and takes the ordinary retry path.
      - name: Adopt implementation from source ref
        id: adopt
        if: steps.inputs.outputs.source_ref != ''
        timeout-minutes: 20
        env:
          SOURCE_REF: ${{ steps.inputs.outputs.source_ref }}
          SOURCE_MODEL: ${{ steps.inputs.outputs.source_model }}
          SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
          LANGUAGE: ${{ steps.inputs.outputs.language }}
          LIBRARY: ${{ steps.inputs.outputs.library }}
          EXT: ${{ steps.inputs.outputs.ext }}
          BRANCH: ${{ steps.branch.outputs.branch }}
        run: |
          # This step runs the adopted, model-written code: it gets no way to
          # mint an OIDC token (the job has id-token for Claude and Google Cloud).
          unset ACTIONS_ID_TOKEN_REQUEST_URL ACTIONS_ID_TOKEN_REQUEST_TOKEN
          IMPL_DIR="plots/${SPEC_ID}/implementations/${LANGUAGE}"
          IMPL_FILE="${IMPL_DIR}/${LIBRARY}${EXT}"
          AUTHOR="${SOURCE_MODEL:+, written by ${SOURCE_MODEL}}"
          fail() {
            echo "cause=$1" >> "$GITHUB_OUTPUT"
            echo "::error::$2"
            exit 1
          }

          case "$LANGUAGE" in
            python|javascript) ;;
            *) fail unsupported "Adopt mode renders Python and JavaScript implementations only; ${LANGUAGE}/${LIBRARY} has no adopt render yet" ;;
          esac

          # FETCH_HEAD, not origin/<name>: works for branches, tags and SHAs
          # alike. A failed fetch is a missing ref only when origin answers
          # otherwise; an unreachable origin is the runner's failure.
          if ! git fetch --no-tags origin "$SOURCE_REF"; then
            if ! git ls-remote --heads origin main >/dev/null; then
              echo "::error::origin is unreachable; cannot fetch source_ref '${SOURCE_REF}'"
              exit 1
            fi
            fail missing "source_ref '${SOURCE_REF}' not found on origin (expected a branch, tag or full commit SHA)"
          fi
          SOURCE_SHA=$(git rev-parse FETCH_HEAD)
          echo "sha=${SOURCE_SHA}" >> "$GITHUB_OUTPUT"
          if ! git cat-file -e "FETCH_HEAD:${IMPL_FILE}" 2>/dev/null; then
            fail missing "${IMPL_FILE} does not exist on source_ref ${SOURCE_REF} (${SOURCE_SHA})"
          fi
          git checkout FETCH_HEAD -- "$IMPL_FILE"
          echo "::notice::Adopted ${IMPL_FILE} from ${SOURCE_REF} (${SOURCE_SHA})${AUTHOR}"

          # Step 3: both themes, from the implementation directory, with the
          # generator's commands. The JS harness writes plot-{theme}.png and
          # plot-{theme}.html itself and exits non-zero on a throw or an
          # empty #container.
          for f in plot-light.png plot-dark.png plot-light.html plot-dark.html plot.png plot.html; do
            rm -f "${IMPL_DIR}/${f}"
          done
          for theme in light dark; do
            if [ "$LANGUAGE" = "python" ]; then
              ( source .venv/bin/activate && cd "$IMPL_DIR" \
                && MPLBACKEND=Agg ANYPLOT_THEME="$theme" python -P "${LIBRARY}.py" ) \
                || fail render "${IMPL_FILE} failed to render the ${theme} theme"
            else
              ( cd "$IMPL_DIR" \
                && ANYPLOT_THEME="$theme" node "$GITHUB_WORKSPACE/automation/js-render/render.mjs" "${LIBRARY}${EXT}" ) \
                || fail render "${IMPL_FILE} failed to render the ${theme} theme"
            fi
            [ -s "${IMPL_DIR}/plot-${theme}.png" ] || fail render "${IMPL_FILE} rendered no plot-${theme}.png"
          done

          # Step 3b, with core.canvas on both themes. Drift only warns: the
          # canvas gate in impl-review turns it into a VQ-05 defect that
          # repair fixes, the path a generated file that drifted takes too.
          # core.canvas needs numpy, which the helper venv of the non-Python
          # languages lacks. Exit 1 is drift only when the check printed its
          # failing verdict: a crash (an import error, say) exits 1 as well,
          # and must never pass for a measured canvas.
          if ! .venv/bin/python -c "import numpy" 2>/dev/null; then
            uv pip install --python .venv/bin/python numpy \
              && .venv/bin/python -c "import numpy" \
              || { echo "::error::numpy could not be installed for the canvas check"; exit 1; }
          fi
          for theme in light dark; do
            rc=0
            verdict=$(.venv/bin/python -m core.canvas "${IMPL_DIR}/plot-${theme}.png" --library "$LIBRARY") || rc=$?
            printf '%s\n' "$verdict"
            if [ "$rc" = 1 ] && grep -q '^::notice::canvas_gate .* status=fail ' <<< "$verdict"; then
              echo "::warning::plot-${theme}.png is off the canvas target; impl-review's canvas gate sends it to repair"
            elif [ "$rc" = 2 ]; then
              fail render "plot-${theme}.png of ${IMPL_FILE} is not a readable PNG"
            elif [ "$rc" != 0 ]; then
              echo "::error::the canvas check crashed on plot-${theme}.png (exit ${rc})"
              exit 1
            fi
          done

          # Step 7: commit only the implementation file and push the branch.
          # --allow-empty keeps the adopt commit when the file equals main's
          # (source_ref=main), so the PR still records where the code came from.
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          if [ -n "$SOURCE_MODEL" ]; then
            ORIGIN_NOTE="Adopted from ${SOURCE_REF} (${SOURCE_SHA}), written by ${SOURCE_MODEL} outside the pipeline."
          else
            ORIGIN_NOTE="Adopted from ${SOURCE_REF} (${SOURCE_SHA}); no generation model."
          fi
          git commit --allow-empty -m "feat(${LIBRARY}): implement ${SPEC_ID}" -m "$ORIGIN_NOTE" -- "$IMPL_FILE"
          git push -u origin "$BRANCH"
          echo "**Adopted:** \`${IMPL_FILE}\` from \`${SOURCE_REF}\` (${SOURCE_SHA})${AUTHOR}" >> "$GITHUB_STEP_SUMMARY"

      - name: Run Claude Code to generate implementation
        id: claude
        if: steps.inputs.outputs.source_ref == ''
        continue-on-error: true
        timeout-minutes: 60
        uses: anthropics/claude-code-action@d70510b174a1244958df0b03166a54912811f3e6  # v1
        with:
          anthropic_api_key: ${{ steps.claude_auth.outputs.mode == 'api' && secrets.ANTHROPIC_API_KEY || '' }}
          claude_code_oauth_token: ${{ steps.claude_auth.outputs.mode == 'subscription' && secrets.CLAUDE_CODE_OAUTH_TOKEN || '' }}
          anthropic_federation_rule_id: ${{ steps.claude_auth.outputs.federation_rule_id }}
          anthropic_organization_id: ${{ steps.claude_auth.outputs.organization_id }}
          anthropic_service_account_id: ${{ steps.claude_auth.outputs.service_account_id }}
          anthropic_workspace_id: ${{ steps.claude_auth.outputs.workspace_id }}
          claude_args: "--model ${{ steps.inputs.outputs.model }} --settings ${{ github.workspace }}/.claude/settings.json"
          # bulk-generate dispatches us from the github-actions bot; explicitly allow it.
          allowed_bots: '*'
          prompt: |
            Read `prompts/workflow-prompts/impl-generate-claude.md` and follow those instructions.

            Variables for this run:
            - LANGUAGE: ${{ steps.inputs.outputs.language }}
            - LIBRARY: ${{ steps.inputs.outputs.library }}
            - EXT: ${{ steps.inputs.outputs.ext }}
            - SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
            - IS_REGENERATION: ${{ steps.existing.outputs.is_regeneration }}

      # The session's cost (Claude Code's own estimate at API list price),
      # model and credential mode, for the weekly regen review, and whether
      # Claude stopped it: a spend or usage limit, or refused credentials
      # (outputs stopped, stop_reason). Read right after the step: the retry
      # writes the same execution file. Never fatal.
      - name: Claude session summary
        id: claude_cost
        if: ${{ !cancelled() && (steps.claude.outcome == 'success' || steps.claude.outcome == 'failure') }}
        continue-on-error: true
        env:
          EXECUTION_FILE: ${{ steps.claude.outputs.execution_file }}
          CLAUDE_AUTH_MODE: ${{ steps.claude_auth.outputs.mode }}
          CLAUDE_STEP: impl-generate
          # Only the error fields of a session that failed, because its own
          # text may quote the same messages: the error result, Claude Code's
          # error messages and its API retries, with their HTTP status.
          SESSION_ERRORS: >-
            ([.[] | select(.type == "result")] | last) as $result
            | if $result != null and $result.is_error != true then empty else
            (.[] | select((.type == "result" and .is_error == true) or (.type == "assistant" and .error != null) or (.type == "system" and .subtype == "api_retry"))
            | (.result // ""), ((.errors // [])[] | tostring), (.error // "" | tostring), (if .type == "assistant" then ((.message.content // [])[] | .text? // "") else "" end), (if (.api_error_status // .error_status) then "api_error_status=\(.api_error_status // .error_status)" else "" end))
            end
          # A spend or usage limit, in every mode: the API's spend-limit,
          # spend-cap and credit messages, Claude Code's billing_error and
          # credit message, and its subscription usage-limit messages (the
          # SDK's USAGE_LIMIT_ERROR_PREFIXES).
          LIMIT_PATTERN: >-
            reached your (specified )?(workspace )?API usage limits|enforced_spend_limit_reached|credit balance (is )?too low|billing_error|usage limit reached|You.{1,3}ve (hit|reached) your|You.{1,3}re out of (usage credits|extra usage)|Your org is out of usage|Your seat type doesn.{1,3}t include|Your usage allocation has been disabled|Your group.{1,3}s usage limit is set to \$0|requires usage credits
          # Refused credentials, with api and oidc only (the subscription keeps
          # its handling): HTTP 401 or 403, the API's authentication_error and
          # permission_error, Claude Code's authentication_failed, a refused
          # federation exchange ("Authentication failed"), a bad API key.
          AUTH_PATTERN: >-
            authentication_error|authentication_failed|permission_error|Authentication failed|invalid x-api-key|account_on_hold|api_error_status=40[13]
        run: |
          cost=$(jq -r '[.[] | select(.type == "result")] | last | .total_cost_usd // empty' "$EXECUTION_FILE" 2>/dev/null || true)
          model=$(jq -r '[.[] | select(.type == "system" and .subtype == "init")] | first | .model // empty' "$EXECUTION_FILE" 2>/dev/null || true)
          line="claude-cost step=${CLAUDE_STEP} auth=${CLAUDE_AUTH_MODE} model=${model:-n/a} total_cost_usd=${cost:-n/a}"
          echo "$line"
          echo "- \`${line}\`" >> "$GITHUB_STEP_SUMMARY"
          errors=$(jq -r "$SESSION_ERRORS" "$EXECUTION_FILE" 2>/dev/null || true)
          reason=""
          if grep -qiE "$LIMIT_PATTERN" <<< "$errors"; then
            reason=limit
            what="Claude spend/usage limit reached"
          elif [[ "$CLAUDE_AUTH_MODE" =~ ^(api|oidc)$ ]] && grep -qiE "$AUTH_PATTERN" <<< "$errors"; then
            reason=auth
            what="Claude credentials refused"
          fi
          if [ -n "$reason" ]; then
            echo "::error::${what} (auth=${CLAUDE_AUTH_MODE}) in ${CLAUDE_STEP}: no retry until it is resolved"
            echo "- **${what} (auth=${CLAUDE_AUTH_MODE})** in \`${CLAUDE_STEP}\`" >> "$GITHUB_STEP_SUMMARY"
            echo "stopped=true" >> "$GITHUB_OUTPUT"
          else
            echo "stopped=false" >> "$GITHUB_OUTPUT"
          fi
          echo "stop_reason=${reason}" >> "$GITHUB_OUTPUT"

      # Not after Claude stopped the session (a limit or refused credentials):
      # the retry would be refused the same way.
      - name: Retry Claude (on failure)
        if: steps.claude.outcome == 'failure' && steps.inputs.outputs.source_ref == '' && steps.claude_cost.outputs.stopped != 'true'
        id: claude_retry
        timeout-minutes: 60
        uses: anthropics/claude-code-action@d70510b174a1244958df0b03166a54912811f3e6  # v1
        with:
          anthropic_api_key: ${{ steps.claude_auth.outputs.mode == 'api' && secrets.ANTHROPIC_API_KEY || '' }}
          claude_code_oauth_token: ${{ steps.claude_auth.outputs.mode == 'subscription' && secrets.CLAUDE_CODE_OAUTH_TOKEN || '' }}
          anthropic_federation_rule_id: ${{ steps.claude_auth.outputs.federation_rule_id }}
          anthropic_organization_id: ${{ steps.claude_auth.outputs.organization_id }}
          anthropic_service_account_id: ${{ steps.claude_auth.outputs.service_account_id }}
          anthropic_workspace_id: ${{ steps.claude_auth.outputs.workspace_id }}
          claude_args: "--model ${{ steps.inputs.outputs.model }} --settings ${{ github.workspace }}/.claude/settings.json"
          # bulk-generate dispatches us from the github-actions bot; explicitly allow it.
          allowed_bots: '*'
          prompt: |
            Read `prompts/workflow-prompts/impl-generate-claude.md` and follow those instructions.

            Variables for this run:
            - LANGUAGE: ${{ steps.inputs.outputs.language }}
            - LIBRARY: ${{ steps.inputs.outputs.library }}
            - EXT: ${{ steps.inputs.outputs.ext }}
            - SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
            - IS_REGENERATION: ${{ steps.existing.outputs.is_regeneration }}

      - name: Claude session summary (retry)
        id: claude_retry_cost
        if: ${{ !cancelled() && (steps.claude_retry.outcome == 'success' || steps.claude_retry.outcome == 'failure') }}
        continue-on-error: true
        env:
          EXECUTION_FILE: ${{ steps.claude_retry.outputs.execution_file }}
          CLAUDE_AUTH_MODE: ${{ steps.claude_auth.outputs.mode }}
          CLAUDE_STEP: impl-generate/retry
          # Only the error fields of a session that failed, because its own
          # text may quote the same messages: the error result, Claude Code's
          # error messages and its API retries, with their HTTP status.
          SESSION_ERRORS: >-
            ([.[] | select(.type == "result")] | last) as $result
            | if $result != null and $result.is_error != true then empty else
            (.[] | select((.type == "result" and .is_error == true) or (.type == "assistant" and .error != null) or (.type == "system" and .subtype == "api_retry"))
            | (.result // ""), ((.errors // [])[] | tostring), (.error // "" | tostring), (if .type == "assistant" then ((.message.content // [])[] | .text? // "") else "" end), (if (.api_error_status // .error_status) then "api_error_status=\(.api_error_status // .error_status)" else "" end))
            end
          # A spend or usage limit, in every mode: the API's spend-limit,
          # spend-cap and credit messages, Claude Code's billing_error and
          # credit message, and its subscription usage-limit messages (the
          # SDK's USAGE_LIMIT_ERROR_PREFIXES).
          LIMIT_PATTERN: >-
            reached your (specified )?(workspace )?API usage limits|enforced_spend_limit_reached|credit balance (is )?too low|billing_error|usage limit reached|You.{1,3}ve (hit|reached) your|You.{1,3}re out of (usage credits|extra usage)|Your org is out of usage|Your seat type doesn.{1,3}t include|Your usage allocation has been disabled|Your group.{1,3}s usage limit is set to \$0|requires usage credits
          # Refused credentials, with api and oidc only (the subscription keeps
          # its handling): HTTP 401 or 403, the API's authentication_error and
          # permission_error, Claude Code's authentication_failed, a refused
          # federation exchange ("Authentication failed"), a bad API key.
          AUTH_PATTERN: >-
            authentication_error|authentication_failed|permission_error|Authentication failed|invalid x-api-key|account_on_hold|api_error_status=40[13]
        run: |
          cost=$(jq -r '[.[] | select(.type == "result")] | last | .total_cost_usd // empty' "$EXECUTION_FILE" 2>/dev/null || true)
          model=$(jq -r '[.[] | select(.type == "system" and .subtype == "init")] | first | .model // empty' "$EXECUTION_FILE" 2>/dev/null || true)
          line="claude-cost step=${CLAUDE_STEP} auth=${CLAUDE_AUTH_MODE} model=${model:-n/a} total_cost_usd=${cost:-n/a}"
          echo "$line"
          echo "- \`${line}\`" >> "$GITHUB_STEP_SUMMARY"
          errors=$(jq -r "$SESSION_ERRORS" "$EXECUTION_FILE" 2>/dev/null || true)
          reason=""
          if grep -qiE "$LIMIT_PATTERN" <<< "$errors"; then
            reason=limit
            what="Claude spend/usage limit reached"
          elif [[ "$CLAUDE_AUTH_MODE" =~ ^(api|oidc)$ ]] && grep -qiE "$AUTH_PATTERN" <<< "$errors"; then
            reason=auth
            what="Claude credentials refused"
          fi
          if [ -n "$reason" ]; then
            echo "::error::${what} (auth=${CLAUDE_AUTH_MODE}) in ${CLAUDE_STEP}: no retry until it is resolved"
            echo "- **${what} (auth=${CLAUDE_AUTH_MODE})** in \`${CLAUDE_STEP}\`" >> "$GITHUB_STEP_SUMMARY"
            echo "stopped=true" >> "$GITHUB_OUTPUT"
          else
            echo "stopped=false" >> "$GITHUB_OUTPUT"
          fi
          echo "stop_reason=${reason}" >> "$GITHUB_OUTPUT"

      # Claude stopped the first session (a limit or refused credentials) and
      # its retry was skipped: fail here, so "Handle generation failure" parks
      # the pair instead of the steps below running without an implementation.
      - name: Stop when Claude stopped the session
        if: steps.claude_cost.outputs.stopped == 'true'
        run: |
          echo "::error::Claude stopped the session (${{ steps.claude_cost.outputs.stop_reason }}); the retry is skipped"
          exit 1

      # ========================================================================
      # Create metadata file (before PR)
      # ========================================================================
      - name: Create library metadata file
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
          LANGUAGE: ${{ steps.inputs.outputs.language }}
          LIBRARY: ${{ steps.inputs.outputs.library }}
          EXT: ${{ steps.inputs.outputs.ext }}
          ISSUE: ${{ steps.issue.outputs.number }}
          BRANCH: ${{ steps.branch.outputs.branch }}
          MODEL: ${{ steps.inputs.outputs.model }}
          # SOURCE_REF and SOURCE_MODEL are validated in "Extract inputs" (ref
          # and model-name characters only). SOURCE_SHA is the commit "Adopt
          # implementation from source ref" took the file from.
          SOURCE_REF: ${{ steps.inputs.outputs.source_ref }}
          SOURCE_MODEL: ${{ steps.inputs.outputs.source_model }}
          SOURCE_SHA: ${{ steps.adopt.outputs.sha }}
        run: |
          IMPL_DIR="plots/${SPEC_ID}/implementations/${LANGUAGE}"

          # Save plot files before git operations (they are not committed and would be lost).
          # Phase C emits plot-light.png + plot-dark.png (+ plot-light.html + plot-dark.html
          # for interactive libs); legacy plot.png/plot.html is preserved during the transition.
          mkdir -p /tmp/anyplot-plot-cache
          rm -rf /tmp/anyplot-plot-cache/*
          for f in plot-light.png plot-dark.png plot-light.html plot-dark.html plot.png plot.html; do
            cp "${IMPL_DIR}/${f}" "/tmp/anyplot-plot-cache/${f}" 2>/dev/null || true
          done

          # Configure git auth (Claude's action configured it, but it's gone now)
          git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${{ github.repository }}.git"

          # Sync with remote (Claude already pushed the code)
          git fetch origin

          # Check if remote branch exists before checkout (fixes branch-not-found error)
          if git ls-remote --exit-code --heads origin "$BRANCH" >/dev/null 2>&1; then
            git checkout -B "$BRANCH" "origin/$BRANCH"
          else
            # Branch doesn't exist on remote - create fresh from main
            echo "::warning::Remote branch $BRANCH not found, creating fresh from main"
            git checkout -B "$BRANCH" origin/main
          fi

          # An implementation PR never changes dependency files, and impl-merge.yml
          # refuses one that does. #9398 (qrcode-basic, makie) committed the
          # Manifest.toml that a `Pkg.add` had re-resolved, which moved Makie from
          # 0.22.10 to 0.21.9 for every Julia implementation. A spec that needs a
          # new package needs a dependency PR first.
          # The diff runs on its own line so a git failure stops the step
          # instead of reading as "no changes". `--no-renames` lists both sides
          # of a rename, so Manifest.toml -> Manifest.toml.bak is caught too.
          CHANGED=$(git diff --no-renames --name-only origin/main...HEAD)
          DEP_CHANGES=$(echo "$CHANGED" \
            | grep -E '(^|/)(pyproject\.toml|uv\.lock|package\.json|package-lock\.json|Project\.toml|Manifest\.toml|\.python-version)$' || true)
          if [ -n "$DEP_CHANGES" ]; then
            echo "::error::The implementation commit changes dependency files: $(echo "$DEP_CHANGES" | tr '\n' ' '). Implementations use only the installed packages; a new package needs its own dependency PR first."
            exit 1
          fi

          # Restore plot files after git operations
          mkdir -p "${IMPL_DIR}"
          for f in plot-light.png plot-dark.png plot-light.html plot-dark.html plot.png plot.html; do
            cp "/tmp/anyplot-plot-cache/${f}" "${IMPL_DIR}/${f}" 2>/dev/null || true
          done

          # Now create metadata file
          METADATA_DIR="plots/${SPEC_ID}/metadata/${LANGUAGE}"
          mkdir -p "${METADATA_DIR}"
          METADATA_FILE="${METADATA_DIR}/${LIBRARY}.yaml"
          TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

          mkdir -p "$METADATA_DIR"

          # python_version = the Python interpreter that ran THIS pipeline (3.14 today).
          # language_version = the implementation's own runtime — same as python_version for
          # Python libs, the R version for ggplot2. The frontend renders language_version with
          # the right language label, so we never mislabel R as "Python".
          PYTHON_VERSION=$(python3 --version 2>&1 | awk '{print $2}')
          # R/Python versions are always dot-separated digits. Anything else
          # captured from Rscript (renv leaks, error fragments, status messages)
          # would poison metadata and break the downstream Python heredoc, so
          # we reject and let the existing "unknown" fallback take over.
          is_version() {
            [[ "$1" =~ ^[0-9]+(\.[0-9]+)*$ ]]
          }

          if [ "$LANGUAGE" = "r" ]; then
            # renv's "out-of-sync" notice prints on stdout from .Rprofile, so 2>/dev/null
            # leaves it in the captured value. RENV_CONFIG_STARTUP_QUIET silences renv;
            # tail -n1 + is_version reject anything else that might leak in or land if
            # Rscript exits non-zero after partial stdout.
            LANGUAGE_VERSION=$(RENV_CONFIG_STARTUP_QUIET=TRUE Rscript -e 'cat(as.character(getRversion()))' 2>/dev/null | tail -n1)
            is_version "$LANGUAGE_VERSION" || LANGUAGE_VERSION="unknown"
          elif [ "$LANGUAGE" = "julia" ]; then
            # `julia -e 'print(VERSION)'` prints `1.11.2` (or similar) on stdout.
            # tail -n1 + is_version reject anything else that might leak in or land
            # if julia exits non-zero after partial stdout.
            LANGUAGE_VERSION=$(julia -e 'print(VERSION)' 2>/dev/null | tail -n1)
            is_version "$LANGUAGE_VERSION" || LANGUAGE_VERSION="unknown"
          elif [ "$LANGUAGE" = "javascript" ]; then
            # `node --version` prints `v22.x.y`; strip the leading `v`.
            LANGUAGE_VERSION=$(node --version 2>/dev/null | sed 's/^v//' | tail -n1)
            is_version "$LANGUAGE_VERSION" || LANGUAGE_VERSION="unknown"
          else
            LANGUAGE_VERSION="$PYTHON_VERSION"
          fi

          # Get library version. Python libs read via `pip show`; R libs via
          # packageVersion() inside Rscript; Julia libs via Pkg API.
          # Names that differ between catalogue id and registry id are mapped
          # explicitly.
          get_pip_version() {
            .venv/bin/pip show "$1" 2>/dev/null | grep -i "^Version:" | awk '{print $2}'
          }
          get_r_version() {
            local v
            # `|| true` on the read + if/fi (not `&&`) on the check: neither may
            # propagate a non-zero exit, or it aborts under `set -e`/`-o pipefail`.
            v=$(RENV_CONFIG_STARTUP_QUIET=TRUE Rscript -e "cat(as.character(packageVersion('$1')))" 2>/dev/null | tail -n1) || true
            if is_version "$v"; then printf '%s' "$v"; fi
          }
          get_julia_version() {
            # Pkg.dependencies() returns a Dict{UUID, PackageInfo}; locate the
            # entry by name and print its `.version`. Any version-parse failure
            # gets rejected by the is_version check downstream.
            local v
            v=$(julia --project=. -e "
              using Pkg
              for (_, info) in Pkg.dependencies()
                if info.name == \"$1\"
                  print(info.version)
                  break
                end
              end
            " 2>/dev/null | tail -n1) || true
            # `|| true` on the read + if/fi (not `&&`) on the check: neither may
            # propagate a non-zero exit, or it aborts under `set -e`/`-o pipefail`.
            if is_version "$v"; then printf '%s' "$v"; fi
          }
          get_npm_version() {
            # Read the installed version straight out of the package's own
            # package.json (restored by `npm ci` from the committed lockfile).
            # NB: read the file via fs, NOT `require('<pkg>/package.json')`:
            # packages with an `exports` map (d3, chart.js) block that subpath
            # with ERR_PACKAGE_PATH_NOT_EXPORTED, while echarts happens to allow
            # it — reading node_modules/<pkg>/package.json directly is uniform.
            local v
            # `|| true` on the read + if/fi (not `&&`) on the check guard BOTH
            # abort points: otherwise `LIBRARY_VERSION=$(get_npm_version …)`
            # inherits a non-zero exit and dies under `set -e`/`-o pipefail`
            # before the `"unknown"` fallback can run.
            v=$(node -p "JSON.parse(require('fs').readFileSync('node_modules/$1/package.json','utf8')).version" 2>/dev/null | tail -n1) || true
            if is_version "$v"; then printf '%s' "$v"; fi
          }

          if [ "$LANGUAGE" = "r" ]; then
            LIBRARY_VERSION=$(get_r_version "$LIBRARY")
          elif [ "$LANGUAGE" = "julia" ]; then
            # Catalogue id `makie` maps to the Julia package `Makie` (CairoMakie
            # bundles the same version; we report the user-facing Makie version).
            case "$LIBRARY" in
              makie)
                LIBRARY_VERSION=$(get_julia_version "Makie")
                ;;
              *)
                LIBRARY_VERSION=$(get_julia_version "$LIBRARY")
                ;;
            esac
          elif [ "$LANGUAGE" = "javascript" ]; then
            # Catalogue id `chartjs` maps to the npm package `chart.js` and
            # `muix` to the scoped community package `@mui/x-charts`; `d3` and
            # `echarts` match their npm names directly.
            case "$LIBRARY" in
              chartjs)
                LIBRARY_VERSION=$(get_npm_version "chart.js")
                ;;
              muix)
                LIBRARY_VERSION=$(get_npm_version "@mui/x-charts")
                ;;
              *)
                LIBRARY_VERSION=$(get_npm_version "$LIBRARY")
                ;;
            esac
          else
            case "$LIBRARY" in
              letsplot)
                LIBRARY_VERSION=$(get_pip_version "lets-plot")
                ;;
              *)
                LIBRARY_VERSION=$(get_pip_version "$LIBRARY")
                ;;
            esac

            # Fallback if version is empty
            if [ -z "$LIBRARY_VERSION" ]; then
              echo "::warning::Could not get version for $LIBRARY, trying alternative method"
              # Map library names to Python module names
              case "$LIBRARY" in
                letsplot) PYTHON_MODULE="lets_plot" ;;
                plotnine) PYTHON_MODULE="plotnine" ;;
                *) PYTHON_MODULE="$LIBRARY" ;;
              esac
              LIBRARY_VERSION=$(.venv/bin/python -c "import $PYTHON_MODULE; print(getattr($PYTHON_MODULE, '__version__', 'unknown'))" 2>/dev/null || echo "unknown")
            fi
          fi

          if [ -z "$LIBRARY_VERSION" ]; then
            LIBRARY_VERSION="unknown"
          fi
          echo "::notice::Library version: $LIBRARY = $LIBRARY_VERSION ($LANGUAGE runtime $LANGUAGE_VERSION, pipeline python $PYTHON_VERSION)"

          # Interactive libraries additionally produce HTML previews (one per theme).
          # Python interactive libs are listed explicitly. JavaScript libs are
          # interactive too (the browser render harness emits standalone
          # plot-{light,dark}.html) — but gate on the files actually existing, so a
          # lib/render that produced no HTML never points preview_html at a 404.
          HAS_HTML="false"
          case "$LIBRARY" in
            plotly|bokeh|altair|pygal|letsplot) HAS_HTML="true" ;;
          esac
          if [ "$LANGUAGE" = "javascript" ] && [ -f "$IMPL_DIR/plot-light.html" ] && [ -f "$IMPL_DIR/plot-dark.html" ]; then
            HAS_HTML="true"
          fi

          # Write metadata file using Python for proper YAML formatting
          # Pass all variables inline to avoid export/env issues
          .venv/bin/python3 -c "
          import os, yaml
          lib = '$LIBRARY'
          spec = '$SPEC_ID'
          language = '$LANGUAGE'
          ts = '$TIMESTAMP'
          run_id = ${{ github.run_id }}
          issue = int('$ISSUE' or '0')
          lang_ver = '$LANGUAGE_VERSION'
          lib_ver = '$LIBRARY_VERSION'
          has_html = '$HAS_HTML' == 'true'
          metadata_file = '$METADATA_FILE'
          model = '$MODEL'
          source_ref = '$SOURCE_REF'
          source_model = '$SOURCE_MODEL'
          source_sha = '$SOURCE_SHA'
          base_url = f'https://storage.googleapis.com/anyplot-images/plots/{spec}/{language}/{lib}'

          # Preserve the original 'created' timestamp on regenerations.
          # 'created' is the first-generation date — it must never be overwritten.
          # Only 'updated' moves forward on every regen.
          created_ts = ts
          if os.path.exists(metadata_file):
              try:
                  with open(metadata_file) as f:
                      existing = yaml.safe_load(f) or {}
                  if existing.get('created'):
                      created_ts = existing['created']
              except Exception:
                  pass

          data = {
              'library': lib,
              'language': language,
              'specification_id': spec,
              'created': created_ts,
              'updated': ts,
              # Reflects what claude_args='--model {model}' actually runs: whatever
              # Claude Code's current alias for the chosen model resolves to.
              # Use the family name instead of a frozen version string so the
              # metadata doesn't go stale every model release. An adopted file
              # was written outside this run: it names the model that wrote it
              # (source_model) or, without one, its source ref.
              'generated_by': (source_model or f'adopted:{source_ref}') if source_ref else f'claude-{model}',
              'workflow_run': run_id,
              'issue': issue,
              # language_version is the runtime of the implementation's own language
              # (Python for matplotlib/seaborn/..., R for ggplot2). The pipeline's own
              # Python interpreter is no longer written here — workflow_run is enough
              # for audit, and python_version on an R artifact was misleading.
              'language_version': lang_ver,
              'library_version': lib_ver,
              # Theme-aware preview URLs (Phase C). Both PNG variants are always emitted.
              'preview_url_light': f'{base_url}/plot-light.png',
              'preview_url_dark':  f'{base_url}/plot-dark.png',
              'preview_html_light': f'{base_url}/plot-light.html' if has_html else None,
              'preview_html_dark':  f'{base_url}/plot-dark.html'  if has_html else None,
              'quality_score': None,
              'review': {'strengths': [], 'weaknesses': []}
          }
          # Adopt mode: the ref and the commit the file came from, right after
          # generated_by. Outside the literal above, which review_retest.py
          # mirrors as the key set of a fresh generation.
          if source_ref:
              items = list(data.items())
              at = [key for key, _ in items].index('generated_by') + 1
              items.insert(at, ('adopted_from', f'{source_ref} ({source_sha})' if source_sha else source_ref))
              data = dict(items)
          with open(metadata_file, 'w') as f:
              f.write(f'# Per-library metadata for {lib} implementation of {spec}\n')
              f.write('# Auto-generated by impl-generate.yml\n\n')
              yaml.dump(data, f, default_flow_style=False, sort_keys=False, allow_unicode=True)
          "

          # Commit and push metadata (implementation already committed by Claude)
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

          IMPL_FILE="plots/${SPEC_ID}/implementations/${LANGUAGE}/${LIBRARY}${EXT}"

          # Verify implementation file exists in the repository (Claude should have committed it)
          if ! git ls-files --error-unmatch "$IMPL_FILE" >/dev/null 2>&1; then
            echo "::error::Implementation file not found in repository - cannot commit"
            echo "::error::Expected implementation at: $IMPL_FILE"
            echo "::error::This indicates Claude failed to create the implementation file"
            exit 1
          fi

          # M3: a regeneration edits the live file, so its header still says
          # `Quality: N/100` — the predecessor's stored score, in plain sight
          # of the review that scores this version blind. Reset it to
          # `Quality: pending`, the state a fresh file starts in; impl-review
          # writes the new score after the review. The helper comes from this
          # workflow's own ref (the branch was cut from main, which may not
          # carry --pending yet). Never fatal: a failure only leaves the
          # header as the generator wrote it.
          if git show "${GITHUB_SHA}:automation/scripts/regen_gate.py" > "$RUNNER_TEMP/regen_gate_header.py" 2>/dev/null \
             && python3 "$RUNNER_TEMP/regen_gate_header.py" sanitize-source --pending \
                  --source "$IMPL_FILE" --out "$IMPL_FILE"; then
            git add "$IMPL_FILE"
          else
            echo "::warning::could not reset the Quality header of ${IMPL_FILE} to pending"
          fi

          # Add metadata file
          git add "$METADATA_FILE"

          # Verify metadata file is staged
          if ! git diff --cached --name-only | grep -q "$(basename "$METADATA_FILE")"; then
            echo "::error::Metadata file not staged - cannot commit"
            echo "::error::This indicates the metadata file was not added correctly"
            exit 1
          fi

          git commit -m "chore(${LIBRARY}): add metadata for ${SPEC_ID}"

          # Retry git push — transient races against Claude's earlier push were
          # the dominant "Create metadata file" failure mode (6x in 24h on
          # 2026-05-06). On a non-fast-forward, fetch + rebase before retrying;
          # if the rebase itself fails (conflicts), abort fast — leaving a
          # half-rebased repo in place would just hide the real error.
          push_ok=0
          for attempt in 1 2 3; do
            if git push origin "$BRANCH"; then
              push_ok=1
              break
            fi
            echo "::warning::git push failed (attempt ${attempt}/3) — fetching + rebasing then retrying"
            if ! git fetch origin "$BRANCH"; then
              echo "::error::git fetch origin ${BRANCH} failed during retry"
              exit 1
            fi
            if ! git pull --rebase origin "$BRANCH"; then
              echo "::error::git rebase against origin/${BRANCH} failed (conflicts) — aborting"
              git rebase --abort 2>/dev/null || true
              exit 1
            fi
            if [ "$attempt" -lt 3 ]; then
              sleep $((attempt * 5))
            fi
          done
          if [ "$push_ok" != "1" ]; then
            echo "::error::git push failed after 3 attempts on branch ${BRANCH}"
            exit 1
          fi

          echo "::notice::Created metadata file: $METADATA_FILE (py${PYTHON_VERSION}, ${LIBRARY}==${LIBRARY_VERSION})"
          echo "::notice::Implementation verified present, metadata committed"

      # ========================================================================
      # Adaptability smoke run (record-only, Python only)
      # ========================================================================
      # docs/concepts/adaptable-code.md, "Perturbation smoke run" and "The adapt
      # route": the new source runs on perturbed tables (core/smoke_run.py run);
      # on a regeneration the predecessor from origin/main is rendered in this
      # same runner next to a fresh render of the new source (pair: both
      # themes, `python -P {library}.py` with the theme env, as the generator's
      # Step 3 renders), so impl-review's gate can measure render identity on
      # raw renders from one environment, before "Process plot images"
      # quantizes anything. Results land in $RUNNER_TEMP/adapt and "Upload to
      # GCS Staging" stages them privately under adapt/. Record-only: no exit
      # code gates, continue-on-error keeps a crash or a timeout from failing
      # the job, and a missing artifact reads as `missing` in impl-review (no
      # repair trigger, design "No repair trigger"). The other languages have
      # no runner yet (design "Rollout" step 6), so the step skips them.
      - name: Adaptability smoke run (record-only)
        id: adapt_smoke
        if: steps.inputs.outputs.language == 'python'
        continue-on-error: true
        timeout-minutes: 20
        env:
          SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
          LIBRARY: ${{ steps.inputs.outputs.library }}
        run: |
          # This step runs model-written code: it gets no way to mint an OIDC
          # token (the job has id-token for Claude and Google Cloud).
          unset ACTIONS_ID_TOKEN_REQUEST_URL ACTIONS_ID_TOKEN_REQUEST_TOKEN
          OUT="$RUNNER_TEMP/adapt"; TOOLS="$RUNNER_TEMP/adapt-tools"
          rm -rf "$OUT" "$TOOLS"; mkdir -p "$OUT/prev-src" "$TOOLS"
          # The runner comes from this workflow's ref, never from the branch the
          # generator wrote (the pattern of the regen_gate_header copy in "Create
          # library metadata file"). Without it nothing runs and nothing is staged.
          if ! git archive "$GITHUB_SHA" core | tar -x -C "$TOOLS" || [ ! -f "$TOOLS/core/smoke_run.py" ]; then
            echo "::warning::adapt_smoke could not copy core/ from ${GITHUB_SHA}; no adaptability record is staged"
            rm -rf "$OUT"
            exit 0
          fi
          RUN=(env PYTHONPATH="$TOOLS" .venv/bin/python -P -m core.smoke_run)
          IMPL="plots/${SPEC_ID}/implementations/python/${LIBRARY}.py"
          SPEC="plots/${SPEC_ID}/specification.md"
          "${RUN[@]}" run "$IMPL" --spec "$SPEC" --spec-id "$SPEC_ID" --library "$LIBRARY" \
            --out "$OUT/new-smoke.json" || true
          # A regeneration is the implementation file on origin/main, the test
          # impl-review uses. The predecessor is written under its library's file
          # name, so the runner applies that library's setup calls.
          if git cat-file -e "origin/main:${IMPL}" 2>/dev/null; then
            git show "origin/main:${IMPL}" > "$OUT/prev-src/${LIBRARY}.py"
            # New first, then the predecessor: the generated code has exited
            # before the predecessor's PNGs exist.
            "${RUN[@]}" pair --new "$IMPL" --prev "$OUT/prev-src/${LIBRARY}.py" --library "$LIBRARY" \
              --out-dir "$OUT" --out "$OUT/pair.json" || true
            "${RUN[@]}" run "$OUT/prev-src/${LIBRARY}.py" --spec "$SPEC" --spec-id "$SPEC_ID" --library "$LIBRARY" \
              --skip-if-static-fails --out "$OUT/prev-smoke.json" || true
          fi
          # The generator's Step 3c attempt log, when it ran the self-check.
          if [ -f /tmp/anyplot-selfcheck.jsonl ]; then
            cp /tmp/anyplot-selfcheck.jsonl "$OUT/selfcheck.jsonl"
          fi
          rm -rf "$OUT/prev-src"
          echo "::notice::adapt_smoke spec=${SPEC_ID} lib=${LIBRARY} staged=$(cd "$OUT" && find . -type f | sed 's|^\./||' | sort | tr '\n' ' ')"

      # ========================================================================
      # Process images: optimize + thumbnail
      # ========================================================================
      - name: Process plot images (light + dark)
        env:
          SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
          LANGUAGE: ${{ steps.inputs.outputs.language }}
        run: |
          IMPL_DIR="plots/${SPEC_ID}/implementations/${LANGUAGE}"

          if [ ! -f "$IMPL_DIR/plot-light.png" ] || [ ! -f "$IMPL_DIR/plot-dark.png" ]; then
            echo "::error::Missing plot-{light,dark}.png — implementation failed to produce both theme renders"
            echo "::error::Expected both ${IMPL_DIR}/plot-light.png and ${IMPL_DIR}/plot-dark.png"
            ls -la "$IMPL_DIR/" || true
            exit 1
          fi

          source .venv/bin/activate

          # Optimize each theme PNG in place, then generate responsive variants
          # (400/800/1200 x png/webp + full webp) named plot-{theme}_*.{png,webp}.
          for theme in light dark; do
            python -m core.images process \
              "$IMPL_DIR/plot-${theme}.png" \
              "$IMPL_DIR/plot-${theme}.png"
            python -m core.images responsive \
              "$IMPL_DIR/plot-${theme}.png" \
              "$IMPL_DIR/"
          done

          echo "::notice::Processed both themes: plot-light + plot-dark (optimized + responsive variants)"
          ls -la "$IMPL_DIR/"

      # ========================================================================
      # Create PR
      # ========================================================================
      - name: Create Pull Request
        id: pr
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # Recorded in the body: rescues that re-dispatch review or repair
          # without a model read it back, so an explicit pin survives them
          # and is threaded into repair (the review itself runs on opus).
          MODEL: ${{ steps.inputs.outputs.model }}
          SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
          LANGUAGE: ${{ steps.inputs.outputs.language }}
          LIBRARY: ${{ steps.inputs.outputs.library }}
          EXT: ${{ steps.inputs.outputs.ext }}
          ISSUE: ${{ steps.issue.outputs.number }}
          BRANCH: ${{ steps.branch.outputs.branch }}
          REGEN_LABEL: ${{ steps.existing.outputs.regen_label }}
          PREV_STORED: ${{ steps.prev_review.outputs.prev_stored || 'n/a' }}
          # Via env, never interpolated into the script: the hint is free text.
          CHANGE_REQUEST: ${{ inputs.change_request }}
          SOURCE_REF: ${{ steps.inputs.outputs.source_ref }}
          SOURCE_MODEL: ${{ steps.inputs.outputs.source_model }}
          SOURCE_SHA: ${{ steps.adopt.outputs.sha }}
        run: |
          # Label one name per call, retried: the regen label is added after
          # creation (not via --label, which fails the whole create when the
          # label is missing). A lost `regen` label only costs the watchdog
          # its hint; a lost `regen:forced` makes impl-review gate the PR
          # (fail-safe: the live implementation stays).
          add_regen_label() {
            local pr="$1" attempt
            [ -n "$REGEN_LABEL" ] || return 0
            gh label create "$REGEN_LABEL" --color "c5def5" \
              --description "Regeneration of an implementation that is live on main" 2>/dev/null || true
            for attempt in 1 2 3; do
              if gh pr edit "$pr" --add-label "$REGEN_LABEL" 2> /tmp/label.err; then
                return 0
              fi
              echo "::warning::adding ${REGEN_LABEL} to PR #${pr} failed (attempt ${attempt}/3): $(head -c 300 /tmp/label.err | tr '\n' ' ')"
              [ "$attempt" -lt 3 ] && sleep $((attempt * 5))
            done
            echo "::error::could not label PR #${pr} ${REGEN_LABEL}"
          }

          # Check if PR already exists
          EXISTING_PR=$(gh pr list --head "$BRANCH" --base main --json number -q '.[0].number' 2>/dev/null || echo "")

          if [ -n "$EXISTING_PR" ]; then
            echo "pr_number=$EXISTING_PR" >> $GITHUB_OUTPUT
            echo "pr_exists=true" >> $GITHUB_OUTPUT
            echo "::notice::Using existing PR #$EXISTING_PR"
            add_regen_label "$EXISTING_PR"
            exit 0
          fi

          # Create PR body. In adopt mode no pipeline model wrote the code: the
          # body says where it came from and, with source_model, which model
          # wrote it, and the **Model:** line stays as the model repair runs
          # on, because the rescues of impl-review and impl-repair read it back
          # from exactly that line.
          BODY="## Implementation: \`${SPEC_ID}\` - ${LANGUAGE}/${LIBRARY}

          Implements the **${LANGUAGE}/${LIBRARY}** version of \`${SPEC_ID}\`.

          **File:** \`plots/${SPEC_ID}/implementations/${LANGUAGE}/${LIBRARY}${EXT}\`"

          if [ -n "$SOURCE_REF" ]; then
            if [ -n "$SOURCE_MODEL" ]; then
              AUTHOR=" by ${SOURCE_MODEL}"
            else
              AUTHOR=", no generation model"
            fi
            BODY="${BODY}

          **Generation:** adopted from \`${SOURCE_REF}\`${SOURCE_SHA:+ (${SOURCE_SHA})}${AUTHOR}; the model below runs repair"
          fi

          BODY="${BODY}

          **Model:** ${MODEL}"

          if [ -n "$ISSUE" ]; then
            BODY="${BODY}

          **Parent Issue:** #${ISSUE}"
          fi

          # Regen context. impl-merge reads the "previous quality" line for
          # its issue comment, impl-review reads the change request for the
          # regen gate. One line each: newlines in the hint are flattened.
          if [ -n "$REGEN_LABEL" ]; then
            BODY="${BODY}

          **Regeneration:** previous quality ${PREV_STORED}"
            if [ "$REGEN_LABEL" = "regen:forced" ] && [ -n "$SOURCE_REF" ]; then
              BODY="${BODY} (forced: adopted from ${SOURCE_REF}, fresh-generation review path)"
            elif [ "$REGEN_LABEL" = "regen:forced" ]; then
              BODY="${BODY} (forced: regen_gate=false, fresh-generation review path)"
            else
              BODY="${BODY} (gated: one review decides keep vs replace)"
            fi
            if [ -n "$CHANGE_REQUEST" ]; then
              CR_LINE=$(printf '%s' "$CHANGE_REQUEST" | tr '\r\n' '  ')
              BODY="${BODY}
          **Change request:** ${CR_LINE}"
            fi
          fi

          BODY="${BODY}

          ---
          :robot: *[impl-generate workflow](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*"

          # Create PR
          PR_URL=$(gh pr create --base main --head "$BRANCH" \
            --title "feat(${LIBRARY}): implement ${SPEC_ID}" \
            --body "$BODY")

          PR_NUMBER=$(echo "$PR_URL" | grep -oE '[0-9]+$')
          echo "pr_number=$PR_NUMBER" >> $GITHUB_OUTPUT
          echo "pr_exists=true" >> $GITHUB_OUTPUT
          echo "::notice::Created PR #$PR_NUMBER"
          add_regen_label "$PR_NUMBER"

      # ========================================================================
      # Upload to GCS Staging
      # ========================================================================
      - name: Authenticate to GCP
        id: gcp_auth
        if: steps.pr.outputs.pr_exists == 'true'
        uses: google-github-actions/auth@7c6bc770dae815cd3e89ee6cdf493a5fab2cc093  # v3
        with:
          project_id: anyplot
          workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}

      - name: Set up Cloud SDK
        id: gcloud
        if: steps.pr.outputs.pr_exists == 'true'
        uses: google-github-actions/setup-gcloud@aa5489c8933f4cc7a4f7d45035b3b1440c9c10db  # v3

      - name: Upload to GCS Staging
        id: gcs
        if: steps.pr.outputs.pr_exists == 'true'
        env:
          SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
          LANGUAGE: ${{ steps.inputs.outputs.language }}
          LIBRARY: ${{ steps.inputs.outputs.library }}
        run: |
          IMPL_DIR="plots/${SPEC_ID}/implementations/${LANGUAGE}"
          STAGING_PATH="gs://anyplot-images/staging/${SPEC_ID}/${LANGUAGE}/${LIBRARY}"
          PUBLIC_URL="https://storage.googleapis.com/anyplot-images/staging/${SPEC_ID}/${LANGUAGE}/${LIBRARY}"

          # Adaptability artifacts from "Adaptability smoke run (record-only)".
          # An earlier run of this pair is cleared first, unconditionally, so a
          # kept regeneration's prev-* and pair.json never outlive it. They stay
          # private (no AllUsers ACL) and impl-merge never promotes them.
          # rsync, not `cp -r dir/*`: copying a directory into a destination
          # subdirectory that does not exist yet drops the directory's name
          # (gsutil's naming rule), so new/plot-light.png and
          # prev/plot-light.png could both land as adapt/plot-light.png.
          # rsync names every object by its path under $ADAPT.
          gsutil -m rm -r "${STAGING_PATH}/adapt" 2>/dev/null || true
          ADAPT="$RUNNER_TEMP/adapt"
          rm -rf "$ADAPT/prev-src"  # left behind only when the smoke step was cut off
          if [ -d "$ADAPT" ] && [ -n "$(ls -A "$ADAPT")" ]; then
            gsutil -m -h "Cache-Control:no-store" rsync -r "$ADAPT" "${STAGING_PATH}/adapt" \
              || echo "::warning::adapt artifacts not staged; impl-review records them as missing"
          fi

          # Require both theme renders
          if [ ! -f "$IMPL_DIR/plot-light.png" ] || [ ! -f "$IMPL_DIR/plot-dark.png" ]; then
            echo "::error::Missing plot-light.png and/or plot-dark.png — cannot upload"
            ls -la "$IMPL_DIR/" || true
            exit 1
          fi

          # Upload all plot images for both themes (originals + responsive variants)
          gsutil -m -h "Cache-Control:public, max-age=604800" cp \
            "$IMPL_DIR"/plot-light*.png "$IMPL_DIR"/plot-light*.webp \
            "$IMPL_DIR"/plot-dark*.png  "$IMPL_DIR"/plot-dark*.webp \
            "${STAGING_PATH}/"
          gsutil -m acl ch -u AllUsers:R "${STAGING_PATH}/plot-light*" "${STAGING_PATH}/plot-dark*" 2>/dev/null || true
          echo "png_url_light=${PUBLIC_URL}/plot-light.png" >> $GITHUB_OUTPUT
          echo "png_url_dark=${PUBLIC_URL}/plot-dark.png"   >> $GITHUB_OUTPUT
          echo "uploaded=true" >> $GITHUB_OUTPUT
          echo "::notice::Uploaded plot-light + plot-dark (+responsive variants)"

          # Upload HTML for interactive libraries (one per theme)
          for theme in light dark; do
            if [ -f "$IMPL_DIR/plot-${theme}.html" ]; then
              gsutil -h "Cache-Control:public, max-age=604800" cp "$IMPL_DIR/plot-${theme}.html" "${STAGING_PATH}/plot-${theme}.html"
              gsutil acl ch -u AllUsers:R "${STAGING_PATH}/plot-${theme}.html" 2>/dev/null || true
              echo "html_url_${theme}=${PUBLIC_URL}/plot-${theme}.html" >> $GITHUB_OUTPUT
            fi
          done

          rm -f /tmp/gcs-key.json

      # ========================================================================
      # Post preview and trigger review
      # ========================================================================
      - name: Post preview to issue
        if: steps.issue.outputs.number != '' && steps.gcs.outputs.uploaded == 'true'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
          LANGUAGE: ${{ steps.inputs.outputs.language }}
          LIBRARY: ${{ steps.inputs.outputs.library }}
          ISSUE: ${{ steps.issue.outputs.number }}
          PR_NUMBER: ${{ steps.pr.outputs.pr_number }}
          MODEL: ${{ steps.inputs.outputs.model }}
          MODEL_REASON: ${{ steps.inputs.outputs.model_reason }}
          SOURCE_REF: ${{ steps.inputs.outputs.source_ref }}
          SOURCE_MODEL: ${{ steps.inputs.outputs.source_model }}
        run: |
          # Use staging URLs (available immediately after upload) — show both themes side by side.
          BASE="https://storage.googleapis.com/anyplot-images/staging/${SPEC_ID}/${LANGUAGE}/${LIBRARY}"
          PNG_LIGHT="${BASE}/plot-light.png"
          PNG_DARK="${BASE}/plot-dark.png"

          HTML_LIGHT=""
          HTML_DARK=""
          case "$LIBRARY" in
            plotly|bokeh|altair|pygal|letsplot)
              HTML_LIGHT="${BASE}/plot-light.html"
              HTML_DARK="${BASE}/plot-dark.html"
              ;;
          esac
          # JS libs are interactive too — link the HTML only when the render
          # produced it (mirrors the existence gate used for preview_html).
          IMPL_DIR="plots/${SPEC_ID}/implementations/${LANGUAGE}"
          if [ "$LANGUAGE" = "javascript" ] && [ -f "$IMPL_DIR/plot-light.html" ] && [ -f "$IMPL_DIR/plot-dark.html" ]; then
            HTML_LIGHT="${BASE}/plot-light.html"
            HTML_DARK="${BASE}/plot-dark.html"
          fi

          BODY="## :art: ${LANGUAGE}/${LIBRARY} Preview

          | Light | Dark |
          |-------|------|
          | ![${LIBRARY} light](${PNG_LIGHT}) | ![${LIBRARY} dark](${PNG_DARK}) |

          **PR:** #${PR_NUMBER}"

          if [ -n "$SOURCE_REF" ]; then
            BODY="${BODY}
          **Generation:** adopted from \`${SOURCE_REF}\`${SOURCE_MODEL:+ by ${SOURCE_MODEL}}
          **Repair model:** ${MODEL} (${MODEL_REASON})"
          else
            BODY="${BODY}
          **Model:** ${MODEL} (${MODEL_REASON})"
          fi

          if [ -n "$HTML_LIGHT" ]; then
            BODY="${BODY}
          **Interactive:** [light](${HTML_LIGHT}) · [dark](${HTML_DARK})"
          fi

          BODY="${BODY}

          ---
          :robot: *[impl-generate](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*"

          gh issue comment "$ISSUE" --body "$BODY"

      - name: Trigger review workflow
        id: review_dispatch
        if: steps.pr.outputs.pr_exists == 'true'
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ steps.pr.outputs.pr_number }}
          MODEL: ${{ steps.inputs.outputs.model }}
          TRIGGER_REF: ${{ github.ref_name }}
          EVENT_NAME: ${{ github.event_name }}
        run: |
          # Pre-merge test hook: a dispatch from a feature branch reviews with
          # that branch's impl-review.yml (repository_dispatch always runs the
          # default branch's copy), so workflow + prompt changes can be smoke-
          # tested before they reach main.
          if [ "$EVENT_NAME" = "workflow_dispatch" ] && [ "$TRIGGER_REF" != "main" ]; then
            gh workflow run impl-review.yml --ref "$TRIGGER_REF" \
              -f pr_number="$PR_NUMBER" \
              -f model="$MODEL"
            echo "::notice::Triggered impl-review.yml on ref ${TRIGGER_REF} for PR #$PR_NUMBER (generation model=$MODEL; the review runs on opus)"
            exit 0
          fi
          # Use repository_dispatch as workaround for workflow_dispatch caching issue
          gh api repos/${{ github.repository }}/dispatches \
            -f event_type=review-pr \
            -f "client_payload[pr_number]=$PR_NUMBER" \
            -f "client_payload[model]=$MODEL"
          echo "::notice::Triggered impl-review.yml via repository_dispatch for PR #$PR_NUMBER (generation model=$MODEL; the review runs on opus)"

      - name: Determine result
        id: result
        run: |
          if [ "${{ steps.pr.outputs.pr_exists }}" == "true" ]; then
            echo "success=true" >> $GITHUB_OUTPUT
          else
            echo "success=false" >> $GITHUB_OUTPUT
          fi

      # ========================================================================
      # Failure handling: Track failures via comments and auto-retry
      # ========================================================================
      - name: Handle generation failure
        if: failure() && steps.issue.outputs.number != ''
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SPEC_ID: ${{ steps.inputs.outputs.specification_id }}
          LIBRARY: ${{ steps.inputs.outputs.library }}
          ISSUE: ${{ steps.issue.outputs.number }}
          MODEL: ${{ steps.inputs.outputs.model }}
          # Pass via env (not template-interpolated into the script) so hints
          # containing quotes / $ / backticks can't break shell parsing.
          CHANGE_REQUEST: ${{ inputs.change_request }}
          # How far back a failure marker still counts toward the 3-attempt cap.
          # Covers a whole campaign (a generate→review→repair→merge cycle runs
          # well under an hour) with room for a stalled tail, without letting
          # last month's failures veto today's retries.
          CAMPAIGN_WINDOW_H: '12'
          # Step outcomes, to tell an infrastructure failure (provider incident,
          # cloud auth, GitHub API) from the agent's own — only the latter counts
          # toward the 3-attempt cap. Only the retry step is inspected: it runs
          # solely when the first Claude step failed, so its failure means both
          # runs died (the first step has continue-on-error and never fails the
          # job by itself).
          CLAUDE_RETRY_OUTCOME: ${{ steps.claude_retry.outcome }}
          CLAUDE_EXEC_FILE: ${{ steps.claude_retry.outputs.execution_file }}
          # Claude stopped either session ("Claude session summary" reads it:
          # a spend or usage limit, or refused credentials with api/oidc):
          # parked below, never retried, never counted.
          CLAUDE_STOPPED: ${{ steps.claude_cost.outputs.stopped == 'true' || steps.claude_retry_cost.outputs.stopped == 'true' }}
          STOP_REASON: ${{ steps.claude_cost.outputs.stop_reason || steps.claude_retry_cost.outputs.stop_reason }}
          CLAUDE_MODE: ${{ steps.claude_auth.outputs.mode }}
          GCP_AUTH_OUTCOME: ${{ steps.gcp_auth.outcome }}
          GCLOUD_OUTCOME: ${{ steps.gcloud.outcome }}
          GCS_OUTCOME: ${{ steps.gcs.outcome }}
          PR_OUTCOME: ${{ steps.pr.outcome }}
          REVIEW_DISPATCH_OUTCOME: ${{ steps.review_dispatch.outcome }}
          # Infrastructure failures are retried without spending the pair's
          # budget, but not forever: after this many in the window the pair is
          # parked WITHOUT `impl:<lib>:failed` (it is not a capability verdict)
          # and left for the next dispatch.
          INFRA_WINDOW_CAP: '5'
          # Non-empty when the "Check for existing implementation" step ran and
          # found the pair on main (`regen` or `regen:forced`). A failure in an
          # earlier setup step leaves it empty, so the handler re-detects from
          # origin/main itself below.
          REGEN_LABEL: ${{ steps.existing.outputs.regen_label }}
          LANGUAGE: ${{ steps.inputs.outputs.language }}
          EXT: ${{ steps.inputs.outputs.ext }}
          REGEN_GATE: ${{ (github.event_name == 'workflow_dispatch' && (inputs.regen_gate == false || inputs.source_ref != '')) && 'false' || 'true' }}
          # Adopt mode: the ref the file came from and the model that wrote it
          # (both forwarded by every retry), and the cause "Adopt
          # implementation from source ref" wrote before it failed (missing,
          # render, unsupported). Empty when that step did not fail.
          SOURCE_REF: ${{ steps.inputs.outputs.source_ref }}
          SOURCE_MODEL: ${{ steps.inputs.outputs.source_model }}
          ADOPT_CAUSE: ${{ steps.adopt.outputs.cause }}
          # The ref this run was dispatched on: the auto-retry runs there too,
          # so a branch smoke retries on its branch instead of on main
          # (runs 36400546243/36402058602 retried on main and opened
          # #11969–#11971). `main` for every label-triggered run.
          TRIGGER_REF: ${{ github.ref_name }}
          RUN_URL: https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}
        run: |
          echo "::notice::Handling generation failure for $LIBRARY/$SPEC_ID"

          # Is the pair's implementation live on main? Then this failure must
          # never mark it `impl:<lib>:failed` (the implementation still
          # serves; the label would also send watchdog Section B after a pair
          # that is fine), on EVERY failure path — including setup steps that
          # fail before "Check for existing implementation" ran. Detected from
          # origin/main like impl-review does. When the repository itself is
          # unavailable (checkout failed) the answer is unknown, and unknown
          # never writes the terminal :failed label.
          IS_LIVE=false
          if [ -n "$REGEN_LABEL" ]; then
            IS_LIVE=true
          elif git rev-parse --git-dir >/dev/null 2>&1; then
            git fetch -q origin main 2>/dev/null || true
            if git cat-file -e "origin/main:plots/$SPEC_ID/implementations/$LANGUAGE/$LIBRARY$EXT" 2>/dev/null; then
              IS_LIVE=true
            fi
          else
            IS_LIVE=true
            echo "::warning::No repository checkout — cannot tell whether ${LIBRARY}/${SPEC_ID} is live on main; not marking it failed"
          fi
          echo "::notice::Implementation live on main: ${IS_LIVE}"

          # Regen only: the pair is back to "done" (its live implementation),
          # so the issue may be complete again.
          close_issue_if_complete() {
            local libs
            libs=$(python3 -c "from core.constants import SUPPORTED_LIBRARIES; print(' '.join(sorted(SUPPORTED_LIBRARIES)))" 2>/dev/null || echo "")
            if [ -z "$libs" ] || [ ! -f automation/scripts/close_issue_if_complete.py ]; then
              echo "::warning::close_issue_if_complete unavailable — issue #${ISSUE} left open"
              return 0
            fi
            python3 automation/scripts/close_issue_if_complete.py --issue "$ISSUE" --spec-id "$SPEC_ID" \
              --libraries "$libs" --run-url "$RUN_URL" --source impl-generate || true
          }

          # Adopt mode, source failure: the file is missing on source_ref, it
          # did not render, or its language has no adopt render. Every retry
          # would read the same file from the same ref and fail the same way,
          # so nothing is retried, no attempt is counted (the comment carries
          # its own marker, never the impl-fail one) and the pair is never
          # marked failed. A failure after the adopt step (push, metadata,
          # upload, PR) takes the ordinary path below, whose retry keeps
          # source_ref.
          if [ -n "${ADOPT_CAUSE}" ]; then
            echo "::warning::Adopting ${LIBRARY}/${SPEC_ID} from ${SOURCE_REF} failed (${ADOPT_CAUSE}) — no auto-retry, no attempt counted, not marked failed"
            for stale in "generate:${LIBRARY}" "impl:${LIBRARY}:pending"; do
              gh issue edit "$ISSUE" --remove-label "$stale" 2>/dev/null || true
            done
            if [ "$IS_LIVE" = "true" ]; then
              gh issue edit "$ISSUE" --add-label "impl:${LIBRARY}:done" 2>/dev/null || true
              ADOPT_LIVE="The implementation on main is unchanged and stays live."
            else
              ADOPT_LIVE="The pair has no implementation on main yet."
            fi
            case "${ADOPT_CAUSE}" in
              missing) ADOPT_WHY="The file does not exist on that ref, or the ref does not exist on origin." ;;
              render) ADOPT_WHY="The file did not render both themes with the pipeline's render command." ;;
              *) ADOPT_WHY="Adopt mode has no render for ${LANGUAGE} implementations yet." ;;
            esac
            gh issue comment "$ISSUE" --body "<!-- impl-adopt-fail:${SPEC_ID}:${LIBRARY} -->
          ## :inbox_tray: ${LIBRARY} Adoption Failed (${ADOPT_CAUSE})

          Adopting \`plots/${SPEC_ID}/implementations/${LANGUAGE}/${LIBRARY}${EXT}\` from \`${SOURCE_REF}\` failed. ${ADOPT_WHY} ${ADOPT_LIVE}

          Not retried and not counted toward the 3-attempt cap, because a retry would read the same file. Fix the file on \`${SOURCE_REF}\`, then run:
          \`\`\`
          gh workflow run impl-generate.yml -f specification_id=${SPEC_ID} -f library=${LIBRARY} -f issue_number=${ISSUE} -f source_ref=${SOURCE_REF}${SOURCE_MODEL:+ -f source_model=${SOURCE_MODEL}}
          \`\`\`

          ---
          :robot: *[impl-generate](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*"
            if [ "$IS_LIVE" = "true" ]; then
              close_issue_if_complete
            fi
            exit 0
          fi

          # Claude stopped the session: a spend or usage limit (the API's
          # spend limit or credit balance, the subscription's usage limit) or,
          # with api/oidc, refused credentials. An infrastructure stop that a
          # retry cannot get past until it is resolved, so the pair is parked
          # at once — for a first implementation too. No auto-retry, no
          # attempt counted (the comment carries its own marker, never the
          # impl-fail one, so neither the 3-attempt cap nor daily-regen's
          # attempt window sees it), never `impl:<lib>:failed`. The pair stays
          # in daily-regen's queue.
          if [ "${CLAUDE_STOPPED}" = "true" ]; then
            if [ "${STOP_REASON}" = "auth" ]; then
              WHY="Claude credentials refused"
              WHEN="Once the credentials are fixed"
            else
              WHY="Claude spend/usage limit reached"
              WHEN="Once the limit resets or is raised"
            fi
            echo "::error::${WHY} (auth=${CLAUDE_MODE}) — ${LIBRARY}/${SPEC_ID} parked: no auto-retry, no attempt counted, not marked failed"
            for stale in "generate:${LIBRARY}" "impl:${LIBRARY}:pending"; do
              gh issue edit "$ISSUE" --remove-label "$stale" 2>/dev/null || true
            done
            if [ "$IS_LIVE" = "true" ]; then
              gh issue edit "$ISSUE" --add-label "impl:${LIBRARY}:done" 2>/dev/null || true
            fi
            gh issue comment "$ISSUE" --body "<!-- impl-paused-claude:${SPEC_ID}:${LIBRARY} -->
          ## :pause_button: ${LIBRARY} Paused (${WHY})

          Claude stopped the **${LIBRARY}** generation for \`${SPEC_ID}\`: ${WHY} (auth=\`${CLAUDE_MODE}\`). This is **not** a capability verdict: nothing was retried, no attempt was counted, and the pair is not marked failed.

          ${WHEN}, run:
          \`\`\`
          gh workflow run impl-generate.yml -f specification_id=${SPEC_ID} -f library=${LIBRARY} -f issue_number=${ISSUE} -f model=${MODEL}
          \`\`\`

          ---
          :robot: *[impl-generate](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*"
            if [ "$IS_LIVE" = "true" ]; then
              close_issue_if_complete
            fi
            exit 0
          fi

          # Classify the failure. The retry cap exists to stop re-running a pair
          # the model cannot solve; a provider incident, a cloud token refresh
          # or a GitHub 5xx says nothing about the pair. During the Claude
          # outage of 2026-09-02 (03:15–03:45 UTC) every run failed with
          # `is_error:true` + "Internal error", 27 pairs burned all three
          # attempts in twenty minutes, and for the next twelve hours each
          # re-dispatch ran without any auto-retry because the markers counted.
          #
          # Infrastructure = both Claude runs ended in the action's own error
          # path with a provider-side signature (the execution log is checked,
          # so an agent that gave up — max turns, refused — still counts), or
          # the GCP auth / Cloud SDK / GCS upload / PR creation / review
          # dispatch step failed. "Implementation file not found" and a missing
          # theme render are the agent's own and keep counting.
          INFRA_CAUSE=""
          if [ "${CLAUDE_RETRY_OUTCOME}" = "failure" ]; then
            if [ -n "${CLAUDE_EXEC_FILE}" ] && [ -f "${CLAUDE_EXEC_FILE}" ] \
               && grep -qiE 'Internal error|overloaded|rate.?limit|too many requests|ECONNRESET|ETIMEDOUT|"status": *5[0-9][0-9]' "${CLAUDE_EXEC_FILE}"; then
              SNIPPET=$(grep -oiE 'Internal error[^"]{0,60}|overloaded[^"]{0,40}|rate.?limit[^"]{0,40}|too many requests|ECONNRESET|ETIMEDOUT|"status": *5[0-9][0-9]' "${CLAUDE_EXEC_FILE}" | head -1)
              INFRA_CAUSE="Claude Code action error: ${SNIPPET:-provider-side error, see the execution log}"
            fi
          elif [ "${GCP_AUTH_OUTCOME}" = "failure" ] || [ "${GCLOUD_OUTCOME}" = "failure" ] || [ "${GCS_OUTCOME}" = "failure" ]; then
            INFRA_CAUSE="Google Cloud auth/upload step failed"
          elif [ "${PR_OUTCOME}" = "failure" ] || [ "${REVIEW_DISPATCH_OUTCOME}" = "failure" ]; then
            INFRA_CAUSE="GitHub API step failed (PR creation or review dispatch)"
          fi
          if [ -n "${INFRA_CAUSE}" ]; then
            echo "::notice::Classified as infrastructure failure: ${INFRA_CAUSE}"
          fi

          # Count previous failures via hidden marker comments (more reliable than workflow runs).
          # Paginate so the marker is found even on issues with >30 comments
          # (which is common because all 15 library impls land on the same issue).
          #
          # FAIL CLOSED: if the count call errors (rate limit, transient API
          # failure), we must NOT assume zero prior failures — a zero fallback
          # turns the 3-attempt cap into an infinite self-retry loop (each
          # retry adds a failure comment, which makes the count call slower and
          # more rate-limit-prone, which re-triggers the zero fallback; issue
          # #1010 flooded ~1,200 Actions runs in 38h exactly this way).
          # A failed count is therefore treated as cap-reached: no auto-retry.
          # NB: --paginate applies --jq to EACH page separately, so the filter
          # emits one per-page count per line; awk sums them into one number
          # (the old code broke on issues with >100 comments for this reason).
          # pipefail (Actions bash default) makes a gh failure fail the whole
          # pipeline, so the fail-closed else-branch still triggers.
          #
          # CAMPAIGN-SCOPED: only markers younger than CAMPAIGN_WINDOW_H count.
          # The markers are the permanent audit trail — nothing deletes them —
          # so counting all of them made the "3 attempts" cap per-issue-lifetime
          # instead of per-generation-run. Any (spec, library) pair that ever
          # failed twice then got exactly ONE attempt on every future dispatch,
          # and a single hit of the ~9%/run "agent reports success but writes no
          # file" flake parked it under `impl:<lib>:failed`, which nothing
          # retries (the watchdog reports it as "needs manual attention").
          # Measured 2026-08-24: counts of 3 and 4 on pairs that then succeeded
          # on the very next manual dispatch, and 87 pairs parked repo-wide.
          # A generation campaign is minutes long, so a window of hours is
          # generous while still letting stale history age out on its own.
          #
          # INFRASTRUCTURE-AWARE: a marker that also carries INFRA_TAG records a
          # failure that was not the agent's (see the classification above).
          # Those are counted separately: they never spend the 3-attempt budget
          # and are bounded by INFRA_WINDOW_CAP instead.
          MARKER="<!-- impl-fail:${SPEC_ID}:${LIBRARY} -->"
          INFRA_TAG="<!-- impl-fail-cause:infra -->"
          CAMPAIGN_CUTOFF=$(date -u -d "${CAMPAIGN_WINDOW_H} hours ago" +%Y-%m-%dT%H:%M:%SZ)
          # One paginated call, two numbers per page ("<genuine> <infra>"), summed by awk.
          if COUNTS=$(gh api --paginate "repos/${{ github.repository }}/issues/${ISSUE}/comments?per_page=100" \
            --jq "[.[] | select(.body != null and (.body | contains(\"$MARKER\")) and .created_at > \"$CAMPAIGN_CUTOFF\")] | \"\(map(select(.body | contains(\"$INFRA_TAG\") | not)) | length) \(map(select(.body | contains(\"$INFRA_TAG\"))) | length)\"" \
            | awk '{ g += $1; i += $2 } END { print (g + 0) " " (i + 0) }'); then
            FAILURE_COUNT=${COUNTS% *}
            INFRA_COUNT=${COUNTS#* }
            echo "::notice::Previous failures for ${LIBRARY}/${SPEC_ID} since ${CAMPAIGN_CUTOFF}: $FAILURE_COUNT (plus $INFRA_COUNT infrastructure failures, not counted)"
          else
            echo "::warning::Failure-count API call failed — failing closed (treating retry cap as reached, no auto-retry)"
            FAILURE_COUNT=999
            INFRA_COUNT=999
          fi

          # Retry dispatch, shared by both branches below. Forwards
          # `change_request` so cross-library divergence hints from daily-regen
          # pre-flight survive the retry — otherwise the first attempt has the
          # hint but the retry doesn't, defeating the audit. CHANGE_REQUEST is
          # read from env to keep raw quotes/$/backticks inside the hint from
          # breaking shell parsing. `source_ref` is forwarded too: without it an
          # adopt run's retry would generate the file with Claude instead. And
          # `source_model`, or the retry's metadata would lose the author.
          dispatch_retry() {
            gh workflow run impl-generate.yml --ref "${TRIGGER_REF:-main}" \
              -f specification_id="${SPEC_ID}" \
              -f library="${LIBRARY}" \
              -f issue_number="${ISSUE}" \
              -f model="${MODEL}" \
              -f change_request="${CHANGE_REQUEST}" \
              -f regen_gate="${REGEN_GATE}" \
              -f source_ref="${SOURCE_REF}" \
              -f source_model="${SOURCE_MODEL}"
            if [ -n "${CHANGE_REQUEST}" ]; then
              echo "::notice::Triggered automatic retry for ${LIBRARY}/${SPEC_ID} ($1, model=${MODEL}, change_request=present)"
            else
              echo "::notice::Triggered automatic retry for ${LIBRARY}/${SPEC_ID} ($1, model=${MODEL}, change_request=none)"
            fi
          }

          if [ -n "${INFRA_CAUSE}" ]; then
            INFRA_ATTEMPT=$((INFRA_COUNT + 1))
            if [ "${INFRA_COUNT}" -ge $((INFRA_WINDOW_CAP - 1)) ]; then
              # Parked, not failed: nothing here says the pair is impossible.
              # No `impl:<lib>:failed`, so the watchdog does not treat it as a
              # capability verdict either; the next backfill dispatch picks it
              # up with a clean budget once the markers age out.
              echo "::warning::Parking $LIBRARY/$SPEC_ID after ${INFRA_ATTEMPT} infrastructure failures in the last ${CAMPAIGN_WINDOW_H}h (cap: ${INFRA_WINDOW_CAP}) — not marked failed, no auto-retry"
              # One label per call: a name `gh` cannot resolve fails a whole
              # comma-separated edit and would leave both labels in place.
              for stale in "generate:${LIBRARY}" "impl:${LIBRARY}:pending"; do
                gh issue edit "$ISSUE" --remove-label "$stale" 2>/dev/null || true
              done
              if [ "$IS_LIVE" = "true" ]; then
                gh issue edit "$ISSUE" --add-label "impl:${LIBRARY}:done" 2>/dev/null || true
              fi
              gh issue comment "$ISSUE" --body "${MARKER}
          ${INFRA_TAG}
          ## :pause_button: ${LIBRARY} Paused (infrastructure failures)

          The **${LIBRARY}** implementation for \`${SPEC_ID}\` hit ${INFRA_ATTEMPT} infrastructure failures in the last ${CAMPAIGN_WINDOW_H}h (cap: ${INFRA_WINDOW_CAP}) and is paused. This is **not** a capability verdict — the pair keeps its 3-attempt budget.

          **Last cause:** ${INFRA_CAUSE}

          To retry once the incident is over:
          \`\`\`
          gh workflow run impl-generate.yml -f specification_id=${SPEC_ID} -f library=${LIBRARY} -f issue_number=${ISSUE} -f model=${MODEL}${SOURCE_REF:+ -f source_ref=${SOURCE_REF}}${SOURCE_MODEL:+ -f source_model=${SOURCE_MODEL}}
          \`\`\`

          ---
          :robot: *[impl-generate](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*"
              if [ "$IS_LIVE" = "true" ]; then
                close_issue_if_complete
              fi
            else
              gh issue comment "$ISSUE" --body "${MARKER}
          ${INFRA_TAG}
          ## :cloud: ${LIBRARY} Infrastructure Failure (${INFRA_ATTEMPT}/${INFRA_WINDOW_CAP} in window)

          **Cause:** ${INFRA_CAUSE}

          Not counted toward the 3-attempt cap. Automatically retrying...

          ---
          :robot: *[impl-generate](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*"
              gh issue edit "$ISSUE" --remove-label "generate:${LIBRARY}" 2>/dev/null || true
              dispatch_retry "infrastructure retry ${INFRA_ATTEMPT}/${INFRA_WINDOW_CAP}"
            fi
            exit 0
          fi

          # FAILURE_COUNT counts marker comments BEFORE this run.
          # 0 → this is attempt 1 fail, 1 → attempt 2 fail, 2 → attempt 3 fail.
          ATTEMPT=$((FAILURE_COUNT + 1))

          # After 2 previous failures (= this is attempt 3) → mark as failed.
          # Also entered when the failure count could not be determined
          # (FAILURE_COUNT=999, fail-closed — see above).
          if [ "$FAILURE_COUNT" -ge 2 ]; then
            if [ "$FAILURE_COUNT" -eq 999 ]; then
              CAP_REASON="the failure counter could not be read (failed closed — auto-retry disabled)"
            else
              # State the real total, not a flat "3 attempts": a pair capped by
              # stale history had ONE attempt today, and reading the old wording
              # as "tried three times, must be a capability gap" is exactly how
              # recoverable pairs got written off (2026-08-24).
              # ATTEMPT, not FAILURE_COUNT: the latter excludes the failure being
              # handled right now, so at the cap it would under-report by one.
              CAP_REASON="${ATTEMPT} failed attempt(s) in the last ${CAMPAIGN_WINDOW_H}h (cap: 3 per campaign)"
            fi

            if [ "$IS_LIVE" = "true" ]; then
              # Regeneration: the implementation on main is untouched and still
              # live — no `impl:<lib>:failed`, the pair stays done.
              echo "::warning::Regeneration of $LIBRARY gave up ($CAP_REASON) — the live implementation stays, not marked failed"
              gh issue edit "$ISSUE" --add-label "impl:${LIBRARY}:done" 2>/dev/null || true
              for stale in "generate:${LIBRARY}" "impl:${LIBRARY}:pending"; do
                gh issue edit "$ISSUE" --remove-label "$stale" 2>/dev/null || true
              done
              gh issue comment "$ISSUE" --body "${MARKER}
          ## :leftwards_arrow_with_hook: ${LIBRARY} Regeneration Abandoned (retry cap reached)

          The regeneration of **${LIBRARY}** for \`${SPEC_ID}\` produced no implementation after ${CAP_REASON}. The implementation on main is unchanged and stays live; the pair is **not** marked failed.

          ---
          :robot: *[impl-generate](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*"
              close_issue_if_complete
              exit 0
            fi

            echo "::warning::Marking $LIBRARY as failed: $CAP_REASON"
            if [ -n "${SOURCE_REF}" ]; then
              FAIL_REASON="Adopting the implementation from ${SOURCE_REF} failed in a step after the file was taken; see the linked run."
            else
              FAIL_REASON="Claude Code failed to create the implementation file."
            fi

            # Create failed label if needed
            gh label create "impl:${LIBRARY}:failed" --color "d73a4a" \
              --description "${LIBRARY} implementation failed" 2>/dev/null || true

            # Add failed first, then drop the stale labels one per call: a
            # name `gh` cannot resolve fails a whole comma-separated edit, and
            # the old single call could leave the pair marked pending forever.
            gh issue edit "$ISSUE" --add-label "impl:${LIBRARY}:failed" 2>/dev/null || true
            for stale in "generate:${LIBRARY}" "impl:${LIBRARY}:pending"; do
              gh issue edit "$ISSUE" --remove-label "$stale" 2>/dev/null || true
            done

            # Post final failure comment with marker
            gh issue comment "$ISSUE" --body "${MARKER}
          ## :x: ${LIBRARY} Failed (retry cap reached)

          The **${LIBRARY}** implementation for \`${SPEC_ID}\` was marked failed after ${CAP_REASON}.

          **Reason:** ${FAIL_REASON}

          To retry manually:
          \`\`\`
          gh workflow run impl-generate.yml -f specification_id=${SPEC_ID} -f library=${LIBRARY} -f issue_number=${ISSUE} -f model=${MODEL}${SOURCE_REF:+ -f source_ref=${SOURCE_REF}}${SOURCE_MODEL:+ -f source_model=${SOURCE_MODEL}}
          \`\`\`

          ---
          :robot: *[impl-generate](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*"

          else
            # Attempt 1 or 2 failed → post comment with marker and auto-retry
            gh issue comment "$ISSUE" --body "${MARKER}
          ## :warning: ${LIBRARY} Generation Failed (Attempt ${ATTEMPT}/3)

          Attempt ${ATTEMPT} failed. Automatically retrying...

          ---
          :robot: *[impl-generate](https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }})*"

            # Clean up generate label before retry
            gh issue edit "$ISSUE" --remove-label "generate:${LIBRARY}" 2>/dev/null || true

            dispatch_retry "attempt $((ATTEMPT + 1))"
          fi