chore: import upstream snapshot with attribution

.github/workflows/auto-release.yml

@@ -0,0 +1,142 @@
+name: Auto Release
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  auto-release:
+    # Skip explicit non-release commits to avoid loops.
+    if: >
+      !startsWith(github.event.head_commit.message, 'chore: bump version') &&
+      !contains(github.event.head_commit.message, '[skip release]')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Validate release bot token
+        env:
+          RELEASE_BOT_TOKEN: ${{ secrets.RELEASE_BOT_TOKEN }}
+        run: |
+          if [ -z "$RELEASE_BOT_TOKEN" ]; then
+            echo "::error::RELEASE_BOT_TOKEN secret is required for release automation"
+            exit 1
+          fi
+
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.RELEASE_BOT_TOKEN }}
+
+      - name: Calculate next patch version
+        id: version
+        run: |
+          latest=$(git tag --list 'v*' --sort=-v:refname | head -1)
+          if [ -z "$latest" ]; then
+            next="v0.1.0"
+          else
+            ver="${latest#v}"
+            major=$(echo "$ver" | cut -d. -f1)
+            minor=$(echo "$ver" | cut -d. -f2)
+            patch=$(echo "$ver" | cut -d. -f3)
+            next="v${major}.${minor}.$((patch + 1))"
+          fi
+          echo "tag=$next" >> "$GITHUB_OUTPUT"
+          echo "Next version: $next"
+
+      - name: Update changelog for next version
+        id: changelog
+        env:
+          GH_TOKEN: ${{ secrets.RELEASE_BOT_TOKEN }}
+        run: |
+          tag="${{ steps.version.outputs.tag }}"
+          version="${tag#v}"
+          python scripts/update_changelog.py --version "$version"
+          if git diff --quiet CHANGELOG.md; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          branch="release/${tag}"
+          pr_body_file="$(mktemp)"
+          cat > "$pr_body_file" <<EOF
+          ## Summary
+
+          - Update CHANGELOG.md for ${tag}.
+          - Continue the automated release after changelog bookkeeping.
+
+          ## Validation
+
+          - Generated by the auto-release workflow.
+          - Release PR checks must pass before the workflow merges this changelog PR.
+
+          ## Evidence
+
+          - Not required; changelog-only release PR.
+          EOF
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git switch -c "$branch"
+          git add CHANGELOG.md
+          git commit -m "chore: update changelog for $tag"
+          release_commit="$(git rev-parse HEAD)"
+
+          pr_number="$(gh pr list --head "$branch" --state open --json number --jq '.[0].number // ""')"
+          if [ -n "$pr_number" ]; then
+            gh pr edit "$pr_number" --body-file "$pr_body_file"
+          fi
+
+          git push --force-with-lease origin "$branch"
+
+          if [ -n "$pr_number" ]; then
+            echo "Release changelog PR #$pr_number already exists"
+          else
+            pr_url="$(gh pr create \
+              --base main \
+              --head "$branch" \
+              --title "chore: update changelog for $tag" \
+              --body-file "$pr_body_file")"
+            pr_number="${pr_url##*/}"
+          fi
+
+          pr_head=""
+          for _ in $(seq 1 30); do
+            pr_head="$(gh pr view "$pr_number" --json headRefOid --jq '.headRefOid')"
+            if [ "$pr_head" = "$release_commit" ]; then
+              break
+            fi
+            echo "Waiting for release PR head to update to ${release_commit}..."
+            sleep 10
+          done
+          if [ "$pr_head" != "$release_commit" ]; then
+            echo "::error::Release PR #${pr_number} did not update to ${release_commit}"
+            exit 1
+          fi
+
+          check_count=0
+          for _ in $(seq 1 30); do
+            check_count="$(gh pr checks "$pr_number" --json name --jq 'length' 2>/dev/null || true)"
+            if [ "${check_count:-0}" -gt 0 ]; then
+              break
+            fi
+            echo "Waiting for release PR checks to start..."
+            sleep 10
+          done
+          if [ "${check_count:-0}" -eq 0 ]; then
+            echo "::error::No release PR checks started for #${pr_number}"
+            exit 1
+          fi
+
+          gh pr checks "$pr_number" --watch --fail-fast --interval 10
+          gh pr merge "$pr_number" --admin --squash --delete-branch
+          echo "changed=true" >> "$GITHUB_OUTPUT"
+
+      - name: Create and push tag
+        if: steps.changelog.outputs.changed == 'false'
+        run: |
+          tag="${{ steps.version.outputs.tag }}"
+          git tag "$tag"
+          git push origin "$tag"
+          echo "Created tag $tag"

.github/workflows/ci.yml

@@ -0,0 +1,140 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            uv.lock
+      - run: pip install ruff
+      - run: ruff check .
+      - run: ruff format --check .
+      - name: Collect changed files for PR policy
+        if: github.event_name == 'pull_request'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: gh pr view "$PR_NUMBER" --json files --jq '.files[].path' > /tmp/pr-changed-files.txt
+      - name: Validate PR body policy
+        if: github.event_name == 'pull_request'
+        run: python scripts/check_pr_policy.py --event-path "$GITHUB_EVENT_PATH" --changed-files-file /tmp/pr-changed-files.txt
+
+  screenshot-quality:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Collect screenshot-related changes
+        id: screenshot_changes
+        if: github.event_name == 'pull_request'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          gh pr view "$PR_NUMBER" --json files --jq '.files[].path' > /tmp/pr-changed-files.txt
+          if grep -Eq '^(\.agents/evidence/pr/|scripts/check_screenshots\.(py|sh))' /tmp/pr-changed-files.txt; then
+            echo "should_run=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "should_run=false" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Validate screenshot evidence quality
+        if: github.event_name != 'pull_request' || steps.screenshot_changes.outputs.should_run == 'true'
+        run: python scripts/check_screenshots.py .agents/evidence/pr/
+      - name: Skip unchanged screenshot evidence
+        if: github.event_name == 'pull_request' && steps.screenshot_changes.outputs.should_run != 'true'
+        run: echo "No screenshot evidence or screenshot checker changes in this PR; skipping full screenshot scan."
+
+  pr-policy:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    permissions:
+      contents: read
+      pull-requests: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Collect changed files
+        env:
+          GH_TOKEN: ${{ github.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: gh pr view "$PR_NUMBER" --json files --jq '.files[].path' > /tmp/pr-changed-files.txt
+      - name: Validate PR body policy
+        run: python scripts/check_pr_policy.py --event-path "$GITHUB_EVENT_PATH" --changed-files-file /tmp/pr-changed-files.txt
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            uv.lock
+      - run: pip install -e ".[dev]"
+      - run: python -m pytest tests/ -x --timeout=60
+
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            uv.lock
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: ${{ runner.os }}-playwright-${{ hashFiles('uv.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-playwright-
+      - run: pip install -e ".[dev]" playwright
+      - run: python -m playwright install --with-deps chromium
+      - run: python -m coverage erase
+      - run: python -m coverage run --append -m pytest tests/ --ignore=tests/test_e2e.py --ignore=tests/test_nav_browser.py --ignore=tests/test_responses_browser.py --ignore=tests/test_search_browser.py --ignore=tests/test_perf_viewer.py --ignore=tests/test_viewer_contracts.py -x --timeout=60 -q
+      - run: python -m coverage run --append -m pytest tests/test_e2e.py -q
+      - run: python -m coverage run --append -m pytest tests/test_nav_browser.py tests/test_perf_viewer.py -q
+      - run: python -m coverage run --append -m pytest tests/test_responses_browser.py -q
+      - run: python -m coverage run --append -m pytest tests/test_search_browser.py tests/test_viewer_contracts.py -q
+      - run: python -m coverage json -o .coverage.json
+      - run: python scripts/check_coverage.py --python-coverage .coverage.json

.github/workflows/legibility.yml

@@ -0,0 +1,22 @@
+name: Legibility
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  legibility:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Run deterministic legibility checks
+        run: python scripts/check_legibility.py

.github/workflows/publish.yml

@@ -0,0 +1,84 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to publish (e.g. v0.1.27)"
+        required: true
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag || github.ref }}
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: |
+            pyproject.toml
+            uv.lock
+      - run: pip install ruff
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: python scripts/check_changelog.py --tag "${{ inputs.tag || github.ref_name }}"
+      - run: pip install -e ".[dev]"
+      - run: python -m pytest tests/ -x --timeout=60
+
+  publish:
+    needs: ci
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.tag || github.ref }}
+          fetch-depth: 0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          tag="${{ inputs.tag || github.ref_name }}"
+          # Skip if release already exists (e.g. manual tag push)
+          if gh release view "$tag" &>/dev/null; then
+            echo "Release $tag already exists, skipping"
+            exit 0
+          fi
+          prev_tag=$(git describe --tags --abbrev=0 "${tag}^" 2>/dev/null || echo "")
+          if [ -n "$prev_tag" ]; then
+            notes="$(git log "${prev_tag}..${tag}" --pretty=format:'- %h %s')"
+          else
+            notes="$(git log --pretty=format:'- %h %s' -n 20)"
+          fi
+          gh release create "$tag" \
+            --title "$tag" \
+            --notes "$notes"