gstack/.github/workflows/skill-docs.yml

name: Skill Docs Freshness
# push is main-only: a push to a PR branch already fires the pull_request run;
# the unrestricted push trigger double-ran every PR commit.
on:
  push:
    branches: [main]
  pull_request:

# Cancel superseded runs for the same branch (matches evals.yml,
# windows-free-tests.yml, etc.). head_ref is set on pull_request; ref_name is
# the fallback for push so a rapid push series doesn't pile up stale runs.
concurrency:
  # PR-number keyed (run_id fallback for push/dispatch): a bare branch name
  # carries no fork prefix, so same-name branches from two forks would share
  # one group and cancel each other's runs (same rationale as free-tests.yml).
  group: skill-docs-${{ github.event.pull_request.number || github.run_id }}
  cancel-in-progress: true

# The job only reads the checkout and runs the generator — no token writes.
permissions:
  contents: read

jobs:
  check-freshness:
    runs-on: ubicloud-standard-2
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
        with:
          bun-version: 1.4.0
      - run: bun install --frozen-lockfile
      # One generation pass for ALL 10 hosts. gen-skill-docs --host all
      # hard-fails on any per-host generation error (scripts/gen-skill-docs.ts
      # aggregates failures and exits non-zero), so every host is gated on
      # "generates cleanly." Known limitation, on purpose: the 9 gitignored
      # host outputs (.agents/, .factory/, .kiro/, ...) are NOT byte-freshness
      # checked — `git diff` on ignored untracked paths is always empty (the
      # previous per-host `git diff -- .agents/` gates could never fail for
      # exactly that reason). Byte-freshness is enforced only for tracked
      # output (the Claude SKILL.md files), which the two steps below cover.
      - name: Generate all host skill docs
        run: bun run gen:skill-docs --host all
      - name: Verify tracked skill docs are fresh
        run: |
          git diff --exit-code || {
            echo "Generated SKILL.md files are stale. Run: bun run gen:skill-docs --host all"
            exit 1
          }
      # git diff misses NEW untracked files (e.g. a freshly added skill whose
      # generated SKILL.md was never committed). Fail on any untracked stray
      # the generator produced outside the gitignored host dirs.
      - name: Verify no untracked generated files
        run: |
          STRAYS=$(git status --porcelain --untracked-files=all | grep '^??' || true)
          if [ -n "$STRAYS" ]; then
            echo "Generator produced untracked files that are neither committed nor gitignored:"
            echo "$STRAYS"
            echo "Commit them (bun run gen:skill-docs --host all) or gitignore them."
            exit 1
          fi