ai-guidance-sync.yml

# Flags when a PR leaves the generated Boost files stale (CLAUDE.md, AGENTS.md,
# .ai/rules/index.md, .ai/rules/boost/) without blocking merge: it posts a
# "neutral" (yellow/gray) check, never a red failure.
#
# Maintainer-only for now. Creating a check run needs `checks: write`, which
# `pull_request` does NOT grant to fork PRs, so the job is gated to same-repo
# branches and pushes. Making this work on fork PRs would need the two-stage
# `workflow_run` pattern — deferred.
name: AI Guidance Sync

on:
  pull_request:
  push:
    branches:
      - master
      - develop

jobs:
  sync:
    runs-on: ubuntu-latest

    # Skip fork PRs (their token is read-only and cannot create a check run).
    if: ${{ github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository }}

    permissions:
      contents: read
      checks: write

    steps:
      - uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2
        with:
          php-version: "8.5"
          coverage: none

      - uses: actions/checkout@v7
        with:
          persist-credentials: false

      - name: Get Composer Cache Directory
        id: composer-cache
        run: |
          echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT

      - uses: actions/cache@v6
        with:
          path: ${{ steps.composer-cache.outputs.dir }}
          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
          restore-keys: |
            ${{ runner.os }}-composer-

      - name: Install Dependencies
        run: composer install -q --no-ansi --no-interaction --no-scripts --no-progress --prefer-dist

      - name: Prepare environment
        run: |
          cp -v .env.testing.example .env
          php artisan key:generate --no-interaction

      # `--no-scripts` above skips package auto-discovery, so register packages
      # explicitly — otherwise the boost:install command is not available.
      - name: Discover packages
        run: php artisan package:discover --ansi

      - name: Regenerate the Boost files
        run: php artisan boost:install --guidelines --no-interaction

      - name: Detect drift
        id: drift
        run: |
          if git diff --quiet -- CLAUDE.md AGENTS.md .ai/rules/index.md .ai/rules/boost; then
            echo "stale=false" >> "$GITHUB_OUTPUT"
          else
            echo "stale=true" >> "$GITHUB_OUTPUT"
            echo "Stale generated files:"
            git diff --name-only -- CLAUDE.md AGENTS.md .ai/rules/index.md .ai/rules/boost
          fi

      - name: Publish check
        uses: actions/github-script@v7
        with:
          script: |
            const stale = '${{ steps.drift.outputs.stale }}' === 'true';
            await github.rest.checks.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              name: 'AI guidance up to date',
              head_sha: context.payload.pull_request?.head.sha ?? context.sha,
              status: 'completed',
              conclusion: stale ? 'neutral' : 'success',
              output: {
                title: stale ? 'Boost files are stale' : 'Boost files are current',
                summary: stale
                  ? 'The committed AI guidance is out of date. Run `php artisan boost:install --guidelines` and commit the result.'
                  : 'CLAUDE.md, AGENTS.md, and .ai/rules are in sync with their sources.',
              },
            });