cli-ci.yml

name: cli CI

# No `paths:` filter, deliberately: a filtered workflow that is not triggered still leaves
# its required checks "expected" on GitHub's side, blocking merge on a PR outside its scope.
# The `changes` job decides in bash instead, every other job is gated on its `relevant`
# output, and `gate` reports green when nothing was relevant.
#
# kanban/ has its own job and its own dependencies; no CLI job needs its node_modules.

on:
  push:
    branches: [main, next]
  pull_request:
  schedule:
    # Weekly, every mutant of every scope from scratch: the incremental files PRs restore
    # only replay what a change touched, so drift through a dependency is caught here.
    - cron: "0 3 * * 1"

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}

permissions:
  actions: read
  contents: read

jobs:
  changes:
    name: cli / changes
    permissions:
      actions: read
      contents: read
      pull-requests: read
    runs-on: ubuntu-latest
    outputs:
      relevant: ${{ steps.filter.outputs.relevant }}
      trusted_promotion: ${{ steps.promotion.outputs.trusted }}
      mutation_legs: ${{ steps.mutation.outputs.legs }}
      mutation_sharded: ${{ steps.mutation.outputs.sharded }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0

      - name: Decide whether this workflow's scope changed
        id: filter
        run: |
          set -euo pipefail
          # The scope the jobs below actually exercise.
          if [[ "${{ github.event_name }}" == "pull_request" ]]; then
            BASE="${{ github.event.pull_request.base.sha }}"
            HEAD="${{ github.event.pull_request.head.sha }}"
          else
            BASE="${{ github.event.before }}"
            HEAD="${{ github.sha }}"
          fi

          # A new branch or a force-push gives an all-zero `before`: with no base to diff
          # against, `git diff` would error into a skip reading as "nothing changed".
          if [[ -z "$BASE" || "$BASE" =~ ^0+$ ]]; then
            echo "no usable base SHA (new branch or force-push) - treating as relevant"
            echo "relevant=true" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          relevant=false
          while IFS= read -r f; do
            [[ -z "$f" ]] && continue
            case "$f" in
              cli/*|kanban/*|scripts/__tests__/*|README.md)
                relevant=true
                ;;
              # The identifier-join probe, and the hook predicates it judges the real tool by.
              scripts/probe-identifier-join.cjs|scripts/check-claude-tokens-end-to-end.cjs|plugins/aidd-telemetry/hooks/*)
                relevant=true
                ;;
              # This file: a change to how the suite runs matches nothing else here, so the
              # workflow deciding whether the suite passes would land unverified.
              .github/workflows/cli-ci.yml)
                relevant=true
                ;;
            esac
            [[ "$relevant" == "true" ]] && break
          done < <(git diff --name-only "$BASE" "$HEAD")

          echo "relevant=$relevant" >> "$GITHUB_OUTPUT"

      # A promotion branch is a snapshot of next, not the live next branch. Reuse only proves
      # a tree already gated on next: every missing Git or API proof falls back to mutations.
      - name: Check whether a promotion snapshot or main merge passed next
        id: promotion
        env:
          GH_TOKEN: ${{ github.token }}
          REPO: ${{ github.repository }}
          EVENT_NAME: ${{ github.event_name }}
          GITHUB_REF: ${{ github.ref }}
          CURRENT_SHA: ${{ github.sha }}
          BASE_REF: ${{ github.event.pull_request.base.ref }}
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_REF: ${{ github.event.pull_request.head.ref }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
        run: |
          set -euo pipefail
          trusted=false
          reason="not a reusable promotion snapshot"

          has_successful_next_gate() {
            local run_ids run_id gate
            reason="no successful cli CI push run found for the snapshot SHA"
            if run_ids="$(gh api --paginate "/repos/$REPO/actions/workflows/cli-ci.yml/runs?branch=next&event=push&status=completed&head_sha=$HEAD_SHA&per_page=100" \
              --jq '.workflow_runs[] | select(.conclusion == "success") | .id' 2>/dev/null)"; then
              while IFS= read -r run_id; do
                [[ -z "$run_id" ]] && continue
                if gate="$(gh api "/repos/$REPO/actions/runs/$run_id/jobs?filter=latest&per_page=100" \
                  --jq 'any(.jobs[]; .name == "cli / gate" and .conclusion == "success")' 2>/dev/null)"; then
                  if [[ "$gate" == "true" ]]; then
                    reason="reusing the successful cli CI gate from next run $run_id"
                    return 0
                  fi
                  reason="cli / gate did not pass in next run $run_id"
                else
                  reason="could not inspect cli CI run $run_id"
                fi
              done <<< "$run_ids"
            else
              reason="could not list successful cli CI push runs"
            fi
            return 1
          }

          # GitHub tests pull requests at a synthetic merge ref. The source gate may be reused
          # only if main is already in the snapshot and that merge ref has the same file tree.
          if [[ "$EVENT_NAME" == "pull_request" && "$BASE_REF" == "main" && "$HEAD_REF" =~ ^promote/next-to-main-[0-9]+$ && "$HEAD_REPO" == "$REPO" ]]; then
            if ! git merge-base --is-ancestor "$BASE_SHA" "$HEAD_SHA" 2>/dev/null; then
              reason="main base is not an ancestor of the promotion snapshot"
            elif ! snapshot_tree="$(git rev-parse "$HEAD_SHA^{tree}" 2>/dev/null)" || ! merge_tree="$(git rev-parse "$CURRENT_SHA^{tree}" 2>/dev/null)"; then
              reason="could not prove the promotion merge tree"
            elif [[ "$merge_tree" != "$snapshot_tree" ]]; then
              reason="promotion merge tree differs from the snapshot"
            elif has_successful_next_gate; then
              trusted=true
            fi
          # A main push is reusable only for the exact merge of a numbered, same-repository
          # promotion PR. Parent two is its source snapshot; neither a squash nor an unrelated
          # merge can satisfy this proof.
          elif [[ "$EVENT_NAME" == "push" && "$GITHUB_REF" == "refs/heads/main" ]]; then
            if ! parents="$(git rev-list --parents -n 1 "$CURRENT_SHA" 2>/dev/null)" || ! read -r merge_sha first_parent snapshot_sha extra_parent <<< "$parents" || [[ "$merge_sha" != "$CURRENT_SHA" || -z "$first_parent" || -z "$snapshot_sha" || -n "${extra_parent:-}" ]]; then
              reason="main commit is not a two-parent merge"
            elif ! snapshot_tree="$(git rev-parse "$snapshot_sha^{tree}" 2>/dev/null)" || ! main_tree="$(git rev-parse "$CURRENT_SHA^{tree}" 2>/dev/null)"; then
              reason="could not read the main merge or snapshot tree"
            elif [[ "$main_tree" != "$snapshot_tree" ]]; then
              reason="main merge tree differs from the promotion snapshot"
            elif ! prs="$(gh api "/repos/$REPO/commits/$CURRENT_SHA/pulls" \
              --jq '.[] | select(.base.ref == "main" and (.head.ref | test("^promote/next-to-main-[0-9]+$")) and .merged_at != null) | [.base.repo.full_name, .head.repo.full_name, .head.ref, .head.sha, .merged_at, .merge_commit_sha] | @tsv' 2>/dev/null)"; then
              reason="could not inspect pull requests associated with the main commit"
            else
              matching_prs=0
              while IFS=$'\t' read -r base_repo head_repo head_ref pr_head_sha merged_at merge_commit_sha; do
                if [[ "$base_repo" == "$REPO" && "$head_repo" == "$REPO" && "$head_ref" =~ ^promote/next-to-main-[0-9]+$ && "$pr_head_sha" == "$snapshot_sha" && -n "$merged_at" && "$merge_commit_sha" == "$CURRENT_SHA" ]]; then
                  ((matching_prs += 1))
                fi
              done <<< "$prs"

              if [[ "$matching_prs" -ne 1 ]]; then
                reason="no unique matching promotion pull request proved this main merge"
              else
                HEAD_SHA="$snapshot_sha"
                if has_successful_next_gate; then
                  trusted=true
                fi
              fi
            fi
          fi

          echo "promotion mutation reuse: $reason"
          echo "trusted=$trusted" >> "$GITHUB_OUTPUT"

      - name: Decide which mutation scopes a change can move
        id: mutation
        run: |
          set -euo pipefail
          if [[ "${{ steps.promotion.outputs.trusted }}" == "true" ]]; then
            legs='[]'
            sharded='[]'
          else
            if [[ "${{ github.event_name }}" == "pull_request" ]]; then
              BASE="${{ github.event.pull_request.base.sha }}"
              HEAD="${{ github.event.pull_request.head.sha }}"
            else
              BASE="${{ github.event.before }}"
              HEAD="${{ github.sha }}"
            fi
            if [[ -z "$BASE" || "$BASE" =~ ^0+$ ]]; then
              changed=""
              all=true
            else
              changed="$(git diff --name-only "$BASE" "$HEAD")"
              all=false
            fi
            legs="$(ALL="$all" CHANGED="$changed" node cli/scripts/mutation-scopes-to-run.mjs)"
            sharded="$(ALL="$all" CHANGED="$changed" OUTPUT=sharded node cli/scripts/mutation-scopes-to-run.mjs)"
          fi
          echo "mutation legs: $legs"
          echo "sharded scopes: $sharded"
          echo "legs=$legs" >> "$GITHUB_OUTPUT"
          echo "sharded=$sharded" >> "$GITHUB_OUTPUT"

  cli-typecheck:
    name: cli / Typecheck
    needs: [changes]
    if: needs.changes.outputs.relevant == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Install pnpm
        run: corepack enable
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: "22"
      - name: Cache pnpm store
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.local/share/pnpm/store
          key: pnpm-${{ runner.os }}-${{ hashFiles('cli/pnpm-lock.yaml') }}
          restore-keys: pnpm-${{ runner.os }}-
      - run: cd cli && pnpm install --frozen-lockfile
      - run: cd cli && pnpm typecheck

  cli-lint:
    name: cli / Lint
    needs: [changes]
    if: needs.changes.outputs.relevant == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Install pnpm
        run: corepack enable
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: "22"
      - name: Cache pnpm store
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.local/share/pnpm/store
          key: pnpm-${{ runner.os }}-${{ hashFiles('cli/pnpm-lock.yaml') }}
          restore-keys: pnpm-${{ runner.os }}-
      - run: cd cli && pnpm install --frozen-lockfile
      - run: cd cli && pnpm lint

  cli-architecture:
    name: cli / Architecture invariants
    needs: [changes]
    if: needs.changes.outputs.relevant == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Install pnpm
        run: corepack enable
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: "22"
      - name: Cache pnpm store
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.local/share/pnpm/store
          key: pnpm-${{ runner.os }}-${{ hashFiles('cli/pnpm-lock.yaml') }}
          restore-keys: pnpm-${{ runner.os }}-
      - run: cd cli && pnpm install --frozen-lockfile
      - run: cd cli && pnpm test:arch

  # Every tier once, instrumented: coverage is the test run, and a second uninstrumented
  # pass would prove nothing this one does not.
  cli-coverage:
    name: cli / Test & Coverage thresholds
    needs: [changes]
    if: needs.changes.outputs.relevant == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      # The runner image carries Google's chrome apt source, whose mirror serves a stale index a
      # few times a day ("Hash Sum mismatch") and fails the whole update; expect comes from ubuntu.
      - name: Install expect (TTY persona tests)
        run: |
          sudo rm -f /etc/apt/sources.list.d/google-chrome.list /etc/apt/sources.list.d/google-chrome.sources
          sudo apt-get update && sudo apt-get install -y --no-install-recommends expect
      - name: Install pnpm
        run: corepack enable
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: "22"
      - name: Cache pnpm store
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.local/share/pnpm/store
          key: pnpm-${{ runner.os }}-${{ hashFiles('cli/pnpm-lock.yaml') }}
          restore-keys: pnpm-${{ runner.os }}-
      - run: cd cli && pnpm install --frozen-lockfile
      - run: cd cli && pnpm test:coverage

  cli-smoke:
    name: cli / Smoke
    needs: [changes]
    if: needs.changes.outputs.relevant == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Install pnpm
        run: corepack enable
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: "22"
      - name: Cache pnpm store
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.local/share/pnpm/store
          key: pnpm-${{ runner.os }}-${{ hashFiles('cli/pnpm-lock.yaml') }}
          restore-keys: pnpm-${{ runner.os }}-
      - run: cd cli && pnpm install --frozen-lockfile
      # Hermetic: every setup uses the local framework fixture, so this needs no
      # token and no network. `smoke:full` adds the remote-fetch section on demand.
      - run: cd cli && pnpm smoke

  cli-kilo-runtime:
    name: cli / Kilo runtime smoke
    needs: [changes]
    if: needs.changes.outputs.relevant == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Install pnpm
        run: corepack enable
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: "22"
      - name: Cache pnpm store
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.local/share/pnpm/store
          key: pnpm-${{ runner.os }}-${{ hashFiles('cli/pnpm-lock.yaml') }}
          restore-keys: pnpm-${{ runner.os }}-
      - run: cd cli && pnpm install --frozen-lockfile
      # Exercise generated hooks and memory with the released Kilo server and read tool.
      # Inference uses a deterministic loopback endpoint; no provider account is needed.
      - name: Install Kilo Code CLI
        run: npm install -g @kilocode/cli@7.7.5
      - run: cd cli && pnpm test:e2e:kilo

  cli-build:
    name: cli / Build & Bundle Budget
    needs: [changes]
    if: needs.changes.outputs.relevant == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Install pnpm
        run: corepack enable
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: "22"
      - name: Cache pnpm store
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.local/share/pnpm/store
          key: pnpm-${{ runner.os }}-${{ hashFiles('cli/pnpm-lock.yaml') }}
          restore-keys: pnpm-${{ runner.os }}-
      - run: cd cli && pnpm install --frozen-lockfile
      - run: cd cli && pnpm build

  cli-knip:
    name: cli / Knip (dead code)
    needs: [changes]
    if: needs.changes.outputs.relevant == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Install pnpm
        run: corepack enable
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: "22"
      - name: Cache pnpm store
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.local/share/pnpm/store
          key: pnpm-${{ runner.os }}-${{ hashFiles('cli/pnpm-lock.yaml') }}
          restore-keys: pnpm-${{ runner.os }}-
      - run: cd cli && pnpm install --frozen-lockfile
      - run: cd cli && pnpm knip

  identifier-join:
    name: cli / Identifier join (Claude Code)
    needs: [changes]
    if: needs.changes.outputs.relevant == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Install pnpm
        run: corepack enable
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: "22"
      - name: Cache pnpm store
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.local/share/pnpm/store
          key: pnpm-${{ runner.os }}-${{ hashFiles('cli/pnpm-lock.yaml') }}
          restore-keys: pnpm-${{ runner.os }}-
      - run: cd cli && pnpm install --frozen-lockfile
      - run: cd cli && pnpm build
      # The check drives the real tool, so the real tool has to be here. No credentials are needed.
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code # floats on purpose, declared in scripts/__tests__/workflows-pin-global-installs.test.js
      # The golden snapshots pin what a claude build contains; only the host can say it loads.
      # Its `plugin validate` exits 0 either way, so the script reads the verdict from its text.
      - name: Claude Code accepts the translated marketplace
        run: node scripts/check-claude-accepts-build.cjs
      # One session id in the hook's payload, its environment and the transcript: what the
      # telemetry joins on. Against a dead API, so it spends nothing.
      - name: Claude Code keeps the session id join
        run: node scripts/probe-identifier-join.cjs

  claude-tokens:
    # The real tool, the shipped hooks and the built CLI on each OS, against a fake API whose
    # billed usage is the expected answer. No credentials, no quota. No pnpm store cache: its
    # key path is POSIX, not where a native Windows pnpm resolves its store.
    name: cli / Tokens end to end (Claude Code, ${{ matrix.os }})
    needs: [changes]
    if: needs.changes.outputs.relevant == 'true'
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    defaults:
      run:
        shell: bash
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Install pnpm
        run: corepack enable
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: "22"
      - run: cd cli && pnpm install --frozen-lockfile
      - run: cd cli && pnpm build
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code # floats on purpose, declared in scripts/__tests__/workflows-pin-global-installs.test.js
      - name: The report counts every billed token, on the declared task
        run: node scripts/check-claude-tokens-end-to-end.cjs
      # A person at a terminal, through a pseudo-terminal: asked, answered by the hook, kept
      # across /clear. Python's `pty` is POSIX only; under ConPTY (pywinpty) Claude never got
      # past its terminal setup on the runner, so Windows runs the headless check alone.
      - name: A person is asked, answered and keeps the task across /clear
        if: runner.os != 'Windows'
        run: node scripts/check-claude-tokens-end-to-end.cjs --attended

  cli-jscpd:
    name: cli / JSCPD (duplication)
    needs: [changes]
    if: needs.changes.outputs.relevant == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Install pnpm
        run: corepack enable
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: "22"
      - name: Cache pnpm store
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.local/share/pnpm/store
          key: pnpm-${{ runner.os }}-${{ hashFiles('cli/pnpm-lock.yaml') }}
          restore-keys: pnpm-${{ runner.os }}-
      - run: cd cli && pnpm install --frozen-lockfile
      - run: cd cli && pnpm jscpd

  kanban-checks:
    name: kanban / Typecheck, Lint & Test
    needs: [changes]
    if: needs.changes.outputs.relevant == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Install pnpm
        run: corepack enable
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: "22"
      - name: Cache pnpm store
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.local/share/pnpm/store
          key: pnpm-${{ runner.os }}-${{ hashFiles('kanban/pnpm-lock.yaml') }}
          restore-keys: pnpm-${{ runner.os }}-
      - run: cd kanban && pnpm install --frozen-lockfile
      - run: cd kanban && pnpm typecheck
      - run: cd kanban && pnpm lint
      - run: cd kanban && pnpm test

  windows:
    # Runs under bash (Git Bash, bundled on windows-latest) so every command is the one the
    # Linux jobs run, not a PowerShell rewrite of it. No pnpm store cache: the store path in
    # the Linux jobs' cache key is POSIX, not where a native Windows pnpm resolves its store.
    name: cli / Windows
    needs: [changes]
    if: needs.changes.outputs.relevant == 'true'
    runs-on: windows-latest
    defaults:
      run:
        shell: bash
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Install pnpm
        run: corepack enable
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: "22"

      # Wrapped: a suite writing into this repository's own .git/hooks passes every assertion
      # and destroys an install nothing can restore. The suite reads YAML through the root
      # devDependencies, so the install has to precede it.
      - run: pnpm install --frozen-lockfile
      - run: cd cli && pnpm install --frozen-lockfile
      - name: Plugin suite
        run: node scripts/check-tests-leave-git-alone.js -- node --test 'scripts/__tests__/**/*.test.js'

      # The same commit hooks on Windows; dedicated jobs cover the three CLI checks.
      - name: Hooks - a commit's hooks pass on Windows
        run: |
          echo "# lefthook subject" > "$RUNNER_TEMP/msg"
          status=0
          LEFTHOOK_EXCLUDE=cli-biome,cli-architecture,cli-typecheck \
            pnpm exec lefthook run pre-commit --all-files --no-auto-install --no-tty > "$RUNNER_TEMP/hooks.log" 2>&1 || status=1
          pnpm exec lefthook run prepare-commit-msg "$RUNNER_TEMP/msg" message --no-auto-install --no-tty >> "$RUNNER_TEMP/hooks.log" 2>&1 || status=1
          cat "$RUNNER_TEMP/hooks.log"
          if grep -n "syntax error" "$RUNNER_TEMP/hooks.log"; then
            echo "::error::lefthook handed sh a broken command line"
            exit 1
          fi
          exit $status

      # A real global install, not `node dist/cli.js` by path: nothing else proves `aidd`
      # resolves on this platform's PATH. The recipe hook builds it first; this step
      # rebuilds and packages it for the global install.
      #
      # Inlined rather than `pnpm run install:local`: a package.json script runs through
      # pnpm's configured shell, `cmd.exe` on Windows, where that script's `$(node -p ...)`
      # is not valid syntax. This block is bash by the job's `defaults.run.shell`.
      - name: Install the built CLI globally, the way a person actually would
        run: |
          cd cli
          pnpm build
          pnpm pack --pack-destination ./dist
          npm install -g ./dist/ai-driven-dev-cli-*.tgz --force
      # Failing `aidd --version` means the CLI could not be resolved on the PATH.
      - name: Chain - the installed CLI resolves
        run: aidd --version
      - run: cd cli && pnpm test:unit
      - run: cd cli && pnpm test:integration
      - run: cd cli && pnpm test:arch
      # Every e2e but the one named below.
      - name: cli e2e
        # `--max-workers=2`, and only here. Vitest transforms modules on its own main thread
        # while every worker calls back into it, and that call has a fixed 60 s timeout no
        # configuration exposes: on this runner the default pool queued it past 60 s and
        # failed with `Timeout calling "onTaskUpdate"` while every test passed. A fixed pool
        # of two caps the competing requests whatever the runner's core count.
        run: |
          cd cli
          pnpm exec vitest run --project=e2e --max-workers=2 \
            --exclude "tests/e2e/persona.e2e.test.ts"
        # persona.e2e.test.ts needs /usr/bin/expect, which windows-latest does not carry.

  # Fan-in: every job above either ran and passed, or was skipped because `changes` found
  # nothing relevant. The one check the branch rulesets require — without it a pull request
  # merges with the real jobs red, because nothing names them.
  cli-mutation:
    # A heavy scope runs as several legs in parallel, each mutating its share of the files; the
    # job below scores it once over every leg. Any other scope is one leg and gates itself.
    name: cli / Mutation (${{ matrix.scope }}${{ matrix.of > 1 && format(' {0}/{1}', matrix.shard, matrix.of) || '' }})
    needs: [changes]
    if: needs.changes.outputs.mutation_legs != '[]'
    runs-on: ubuntu-latest
    timeout-minutes: 90
    strategy:
      fail-fast: false
      matrix:
        include: ${{ fromJSON(needs.changes.outputs.mutation_legs) }}
    env:
      # `--` closes the name: `tools` must never restore `tools-codex`'s file.
      LEG: ${{ matrix.of > 1 && format('{0}-shard-{1}-of-{2}', matrix.scope, matrix.shard, matrix.of) || matrix.scope }}
      LEG_DIR: cli/reports/mutation/${{ matrix.of > 1 && format('{0}/shard-{1}-of-{2}', matrix.scope, matrix.shard, matrix.of) || matrix.scope }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Install pnpm
        run: corepack enable
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: "22"
      - name: Cache pnpm store
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ~/.local/share/pnpm/store
          key: pnpm-${{ runner.os }}-${{ hashFiles('cli/pnpm-lock.yaml') }}
          restore-keys: pnpm-${{ runner.os }}-
      - run: cd cli && pnpm install --frozen-lockfile
      # The incremental file is what keeps a run to the mutants a change can move; the newest
      # one this branch or its base saved is restored, and this run's is saved whatever the score.
      - name: Restore this leg's incremental file
        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ${{ env.LEG_DIR }}/incremental.json
          key: mutation--${{ env.LEG }}--${{ github.run_id }}
          restore-keys: mutation--${{ env.LEG }}--
      - run: cd cli && node scripts/run-mutation.mjs "${{ matrix.scope }}" ${{ matrix.of > 1 && format('--shard {0}/{1}', matrix.shard, matrix.of) || '' }} ${{ github.event_name == 'schedule' && '--force' || '' }}
      - name: Save this leg's incremental file
        if: always()
        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ${{ env.LEG_DIR }}/incremental.json
          key: mutation--${{ env.LEG }}--${{ github.run_id }}
      - name: Hand this shard's report to the scoring job
        if: matrix.of > 1
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: mutation-${{ matrix.scope }}-shard-${{ matrix.shard }}-of-${{ matrix.of }}
          path: |
            ${{ env.LEG_DIR }}/manifest.json
            ${{ env.LEG_DIR }}/mutation.json
          if-no-files-found: error
          retention-days: 1

  cli-mutation-score:
    name: cli / Mutation (${{ matrix.scope }})
    needs: [changes, cli-mutation]
    # Always, so a crashed or cancelled shard is scored as missing instead of skipped.
    if: always() && needs.changes.outputs.mutation_sharded != '[]' && needs.changes.outputs.mutation_sharded != ''
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        scope: ${{ fromJSON(needs.changes.outputs.mutation_sharded) }}
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: "22"
      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          pattern: mutation-${{ matrix.scope }}-shard-*
          path: shards
      - name: Score the scope over every shard, against its floor
        run: node cli/scripts/run-mutation.mjs "${{ matrix.scope }}" --aggregate "$GITHUB_WORKSPACE/shards"

  gate:
    name: cli / gate
    runs-on: ubuntu-latest
    if: always()
    needs:
      - changes
      - cli-typecheck
      - cli-lint
      - cli-architecture
      - cli-coverage
      - cli-smoke
      - cli-kilo-runtime
      - cli-build
      - cli-knip
      - identifier-join
      - claude-tokens
      - cli-jscpd
      - cli-mutation
      - cli-mutation-score
      - kanban-checks
      - windows
    steps:
      - name: Fail unless changes decided cleanly and every gated job passed or was skipped
        run: |
          if [[ "${{ needs.changes.result }}" != "success" ]]; then
            echo "::error::the changes job did not succeed (${{ needs.changes.result }}) — whether this workflow had anything to do could not be decided, so every job below it reads as skipped without proving it should have been"
            exit 1
          fi
          for result in \
            "${{ needs.cli-typecheck.result }}" \
            "${{ needs.cli-lint.result }}" \
            "${{ needs.cli-architecture.result }}" \
            "${{ needs.cli-coverage.result }}" \
            "${{ needs.cli-smoke.result }}" \
            "${{ needs.cli-kilo-runtime.result }}" \
            "${{ needs.cli-build.result }}" \
            "${{ needs.cli-knip.result }}" \
            "${{ needs.identifier-join.result }}" \
            "${{ needs.claude-tokens.result }}" \
            "${{ needs.cli-jscpd.result }}" \
            "${{ needs.cli-mutation.result }}" \
            "${{ needs.cli-mutation-score.result }}" \
            "${{ needs.kanban-checks.result }}" \
            "${{ needs.windows.result }}"; do
            if [[ "$result" == "failure" || "$result" == "cancelled" ]]; then
              echo "::error::a required job did not pass (result: $result)"
              exit 1
            fi
          done