openaidr 0.0.1__tar.gz

openaidr-0.0.1/.claude/settings.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f docs/adrs/INDEX.md ]; then printf '=== ARCHITECTURE DECISIONS (docs/adrs/) ===\\n\\nRead a full ADR before changing logic in the area it covers.\\n\\n'; cat docs/adrs/INDEX.md; fi"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f docs/adrs/HOOK-PROMPT.md ]; then printf '=== ADR CHECK BEFORE COMPACTION ===\\n\\n'; cat docs/adrs/HOOK-PROMPT.md; fi"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f docs/adrs/HOOK-PROMPT.md ]; then printf '=== ADR CHECK BEFORE SESSION END ===\\n\\n'; cat docs/adrs/HOOK-PROMPT.md; fi"
+          }
+        ]
+      }
+    ]
+  }
+}

openaidr-0.0.1/.claude/skills/release-openaidr/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: release-openaidr
+description: Use when cutting a new openaidr PyPI release. Walks through version bump, release-notes drafting, pre-flight checks, tag, and push — enforces the publish-pypi.yml notes-file gate so the GitHub Releases page can't silently drift from PyPI.
+---
+
+# release-openaidr
+
+End-to-end release procedure for the `openaidr` distribution.
+`.github/workflows/publish-pypi.yml` enforces the machine-checkable gates
+(tag on main, tag matches both version strings, notes file present, four
+CI gates green). This skill is the human-side counterpart: it drafts the
+notes with judgment, runs the pre-flight checks, and pushes the tag.
+
+**Announce at start:** "I'm using the release-openaidr skill to cut a new
+openaidr release."
+
+## When to invoke
+
+User says any of: "cut a release", "ship 0.1.0", "release openaidr",
+"tag a new version", or starts editing `pyproject.toml`'s version field
+in this repo.
+
+## Inputs
+
+1. **Target version** (e.g. `0.1.0`). Inferred from `pyproject.toml` if
+   the user already bumped it; otherwise ask.
+2. **Theme** — the H1 line of the notes file. Ask the user; a commit log
+   can't infer it.
+
+## Procedure
+
+### Step 1. Pre-flight checks
+
+Run from the repo root. Stop and ask if any fails — do not "fix" a dirty
+tree or out-of-sync main automatically, those signal in-flight work.
+
+```bash
+git rev-parse --abbrev-ref HEAD                    # must be main
+git status --porcelain                             # must be empty
+git fetch --tags origin
+git rev-parse --verify "v<version>" 2>/dev/null    # MUST FAIL — tag must not exist
+test "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)"
+```
+
+PyPI versions are immutable, including yanked ones. If `<version>` is
+already on PyPI, the only path forward is a new version number:
+
+```bash
+curl -s https://pypi.org/pypi/openaidr/json | python3 -c 'import json,sys; print(sorted(json.load(sys.stdin)["releases"]))'
+```
+
+(A 404 here means the project has never been published — expected before
+the first release. See "First release" below for what that additionally
+requires.)
+
+### Step 2. Gather the commit log
+
+```bash
+prev_tag=$(git describe --tags --abbrev=0)         # empty on the first release
+git log --oneline "${prev_tag}..HEAD"
+```
+
+Raw material only — do not dump it into the notes file verbatim.
+
+### Step 2b. Span-identity and model-shape drift check (don't skip)
+
+OpenAIDR's consumer-visible contract is the session model and, above all,
+span identity: it names one tool call and must survive re-reads of a
+growing session, because a consumer draws a call when parsed and attaches
+outcome and enrichments later by naming the same span. A change to how it
+is derived breaks every consumer, and it **fails silently** — enrichments
+land on the wrong row. Nothing in CI can catch that for a downstream repo.
+
+Diff the contract-defining files since the previous release:
+
+```bash
+# session/turn/tool-call model + span identity derivation
+git diff "${prev_tag}..HEAD" -- src/openaidr/model.py
+# per-kind normalisation rules: agent kind, (server, tool) split, status mapping
+git diff "${prev_tag}..HEAD" -- src/openaidr/kinds.py src/openaidr/toolnames.py src/openaidr/readers/
+# the spec that documents the contract
+git diff "${prev_tag}..HEAD" -- docs/specs/session-collection.md
+```
+
+**Decision gate — stop and ask the user** if either holds:
+
+- Span-identity derivation changed (different inputs, different ordering,
+  a new component) → it goes under `## Compatibility` in its own
+  paragraph, named as breaking, with what a consumer must do about stored
+  spans. Never bury it in a highlights bullet.
+- The model's field set or normalisation output changed (a new status, a
+  renamed field, a different `(server, tool)` split for an existing kind)
+  but `docs/specs/session-collection.md` did not → update the spec, or
+  say why it still holds.
+
+Adding coverage for a *new* agent kind is not a contract change — that's
+a highlights bullet, not a compatibility note. The gate is about existing
+kinds' output changing shape.
+
+If nothing drifted, say so in one line in the release PR so the next
+release knows the check ran and wasn't an oversight.
+
+### Step 2c. Dependency and licence sweep
+
+```bash
+git diff "${prev_tag}..HEAD" -- pyproject.toml uv.lock | head -60
+```
+
+- `adr-sensor` is pinned exactly (`==`). A bump is consumer-visible —
+  it changes which agent formats parse and how — so it earns its own
+  bullet naming the old and new version.
+- New runtime dependencies must be Apache-2.0-compatible, and must not
+  drag in anything proprietary. OpenAIDR's standing rule: it installs and
+  runs correctly for someone who has never heard of any downstream
+  product. Check the notes file for that too — no closed-product names.
+
+### Step 3. Draft `docs/releases/v<version>.md`
+
+Follow the shape documented in `docs/releases/README.md`:
+
+```markdown
+# <version> — <theme>
+
+## Highlights
+
+- **<Theme A>.** 1-3 sentences pitched at someone writing a consumer
+  against the session model. Reference ADRs by number when a design doc
+  backs the change.
+- **Bug fixes.** Combine small fixes into one bullet, comma-separated.
+
+## Install
+
+`uv tool install openaidr==<version>` or `pip install openaidr==<version>`.
+
+## Compatibility
+
+<Behavior changes existing consumers will notice — span identity first if
+it moved. Say "pre-alpha, no back-compat hedging" while that's still true.>
+```
+
+**Judgment guidelines (apply ruthlessly):**
+
+- **Group by theme, not by commit.** Five commits adding one agent kind's
+  reader are one bullet.
+- **Lead with user-visible impact**, not implementation. "Codex sessions
+  now report MCP server names" — not "refactored `_split_tool_name`."
+- **Cut chore/format/docs-only and release-machinery commits.** They
+  aren't release-visible.
+- **Acknowledge breaking changes explicitly** under `## Compatibility` —
+  a changed span identity, a renamed model field, or a different status
+  mapping goes there.
+
+Show the draft to the user and iterate until they agree it captures what
+shipped.
+
+### Step 4. Bump both version strings together
+
+`pyproject.toml`'s `version` and `src/openaidr/__init__.py`'s
+`__version__` are separate sources; the workflow fails the build if they
+disagree with the tag. Move them together:
+
+```bash
+sed -i.bak 's/^version = ".*"/version = "<version>"/' pyproject.toml && rm pyproject.toml.bak
+sed -i.bak 's/^__version__ = ".*"/__version__ = "<version>"/' src/openaidr/__init__.py && rm src/openaidr/__init__.py.bak
+uv lock                                            # refresh uv.lock
+uv run openaidr --version                          # sanity: prints openaidr <version>
+```
+
+### Step 5. Release-prep commit + PR
+
+If the user's original request did not explicitly ask to cut, ship, or
+publish a release, stop before the push and ask. Editing the version
+field is enough to invoke this skill; it is not permission to publish.
+
+```bash
+git checkout -b release/<version>
+git add pyproject.toml uv.lock src/openaidr/__init__.py docs/releases/v<version>.md
+git status --porcelain          # inspect anything still unstaged; stage intentionally or stop
+git commit -m "release: <version> — <theme>"
+git push -u origin release/<version>
+```
+
+Opening the PR needs its own explicit ask. Then:
+
+```bash
+gh pr create --title "release: <version>" --body "Release prep for <version>.
+
+- Bumps \`pyproject.toml\` and \`__version__\` to <version>
+- Adds release notes at \`docs/releases/v<version>.md\`
+- After merge: tag \`v<version>\` on main and push to trigger PyPI publish + GitHub Release"
+```
+
+Surface the PR URL. **Stop here.** The user reviews and merges.
+
+### Step 6. After merge: tag + push
+
+After the user confirms the PR merged, on a clean main:
+
+```bash
+git checkout main
+git pull --ff-only
+git tag v<version>
+git push origin v<version>
+```
+
+The tag-triggered run registers asynchronously, so `--limit 1` can grab a
+stale earlier run. Poll for the run tied to the tagged commit:
+
+```bash
+tag_sha=$(git rev-parse "v<version>^{commit}")
+run_id=""
+until [ -n "$run_id" ]; do
+  run_id=$(gh run list --repo open-agent-security/openaidr \
+    --workflow publish-pypi.yml --commit "$tag_sha" \
+    --json databaseId --jq '.[0].databaseId // empty')
+  [ -z "$run_id" ] && sleep 5
+done
+gh run watch --repo open-agent-security/openaidr "$run_id"
+```
+
+### Step 7. Verify
+
+```bash
+curl -s https://pypi.org/pypi/openaidr/json | python3 -c 'import json,sys; print(sorted(json.load(sys.stdin)["releases"]))'
+gh release view v<version> --repo open-agent-security/openaidr --json name,body
+uvx --from openaidr==<version> openaidr --version    # installs from PyPI, must print <version>
+```
+
+All three must succeed. If any fails, surface the workflow run URL rather
+than guessing.
+
+## First release
+
+Before the *first* tag only, a human must have done two things that no
+workflow can do for itself. Check both and stop if either is missing:
+
+1. A **pending** Trusted Publisher on
+   <https://pypi.org/manage/account/publishing/> — project `openaidr`,
+   owner `open-agent-security`, repository `openaidr`, workflow
+   `publish-pypi.yml`, environment `pypi`. Pending, because the project
+   does not exist on PyPI until the first successful upload.
+2. A repo **environment named `pypi`** (Settings → Environments). The
+   name must match the publisher config exactly or the OIDC exchange is
+   rejected — which surfaces as a confusing `invalid-publisher` error at
+   the very last step, after a green build.
+
+```bash
+gh api repos/open-agent-security/openaidr/environments --jq '.environments[].name'
+```
+
+Nothing else about the first release differs: same notes file, same gates.
+
+## Failure modes this prevents
+
+1. **On PyPI but not on GitHub Releases.** The workflow's notes-file gate
+   runs before publish: no notes file at the tag → no PyPI upload.
+2. **Notes file is a raw commit dump.** Step 3's judgment guidelines.
+3. **Tagging a non-main commit.** The workflow's "Verify tag is on main".
+4. **Tag ≠ `pyproject.toml` version, or `__version__` drift.** Two
+   separate workflow steps; Step 4 keeps them moving together.
+5. **Forgetting to refresh `uv.lock`.** `uv sync --frozen` fails in the
+   build job; Step 4 bumps the lock to avoid the round-trip.
+6. **Silent span-identity or model-shape drift.** Step 2b — the one
+   breakage no CI gate in this repo can see, because it only shows up in
+   a consumer that stored spans from an earlier version.
+
+## What this skill does NOT do
+
+- **Doesn't publish to PyPI directly.** The workflow does, via Trusted
+  Publishing (OIDC). There is no PyPI token anywhere in this repo, and
+  none should be added.
+- **Doesn't create the GitHub Release directly.** The workflow's
+  `release-github` job does, from the notes file.
+- **Doesn't write a CHANGELOG.md.** The convention is per-release files
+  under `docs/releases/`.
+- **Doesn't yank.** PyPI versions are immutable; a broken release is
+  fixed by shipping the next version, not by re-uploading.

openaidr-0.0.1/.github/workflows/autofix.yml

@@ -0,0 +1,332 @@
+name: Autofix
+
+# Two-direction comment-bounce that closes the Codex/Claude review loop
+# without human intervention:
+#
+#   1. Codex bot reviews a PR  ->  this workflow posts `@claude please
+#      address...`  ->  claude.yml fires, claude reads the review, fixes
+#      it, pushes commits, posts a "Claude finished" summary comment.
+#
+#   2. Any new commits land on a PR head (`pull_request: synchronize`) ->
+#      this workflow posts `@codex review` -> Codex re-reviews HEAD. ONE
+#      job covers every source of new commits — the claude bot's fixes, a
+#      human / local-agent push, AND the auto-rebase force-push below —
+#      because `synchronize` fires regardless of who pushed. (Codex
+#      auto-reviews on PR open / draft->ready natively, but NOT on
+#      subsequent pushes; without this, later commits land unreviewed.)
+#
+# The two bounces together produce: codex-flag -> claude-fix ->
+# codex-rereview -> ... bounded by the claude-side iteration cap in
+# bounce 1 (the cap counts claude runs, so push-driven re-reviews add
+# entry points, not an unbounded cycle). Codex is silent when clean
+# (thumbs reaction), so an unnecessary @codex review on a no-op SHA costs
+# one cheap call with no PR noise.
+#
+# Authentication: comments are posted (and PR branches are rebased)
+# using AUTOFIX_TRIGGER_PAT, NOT secrets.GITHUB_TOKEN. GitHub explicitly
+# suppresses workflow runs triggered by events created with
+# GITHUB_TOKEN (recursion guard) — so a comment posted under
+# github-actions[bot] would be silently dropped before claude.yml ever
+# fired, and a rebase pushed under GITHUB_TOKEN would not re-trigger
+# CI / Codex on the rebased branch. The PAT is fine-grained, owned by
+# a repo OWNER/MEMBER, with BOTH:
+#   - `Pull requests: Read and write` — for `gh pr comment` (bounces 1
+#     and 2) and `gh pr list` (bounce 0).
+#   - `Contents: Read and write` — for `actions/checkout` to fetch and
+#     `git push` from the rebase-stale-prs job. WITHOUT this, the job
+#     fails at the `Checkout` step with `403: Write access to
+#     repository not granted` — actions/checkout asks GitHub to verify
+#     write permission upfront because the same token will push later.
+# The resulting comments/pushes are authored by that user, which DOES
+# trigger downstream workflows AND naturally passes claude.yml's
+# OWNER/MEMBER/COLLABORATOR trust gate. The same PAT serves all three
+# bounces — Codex's webhook listener watches @-mentions in PR comments
+# regardless of author.
+#
+# If AUTOFIX_TRIGGER_PAT is unset, both `gh pr comment` paths fail
+# with an auth error and the chain breaks; rebase-stale-prs detects
+# the missing secret and skips with a workflow warning. Manual
+# @claude triggers are unaffected.
+#
+# Workflow-injection safety: every user/bot-controlled input (PR number,
+# comment body, review id) is read via env: and referenced as a shell
+# variable. Comment bodies posted to the PR are hardcoded literals — no
+# interpolation of untrusted input into shell.
+
+on:
+  pull_request_review:
+    types: [submitted]
+  pull_request:
+    # Bounce 2: new commits on a PR head -> request a Codex re-review.
+    # `synchronize` fires for pushes from ANY author — claude bot fixes,
+    # human / local-agent pushes, AND the auto-rebase force-push from
+    # rebase-stale-prs. App-authored pushes (claude[bot]) are NOT the
+    # workflow's GITHUB_TOKEN, so they are not recursion-suppressed and DO
+    # fire this event (verified: CI runs on claude's pushed commits).
+    types: [synchronize]
+  push:
+    # Bounce 0: main moved -> rebase open PRs that are now stale. Catches
+    # both PR merges AND direct pushes to main (manual hotfixes, manual
+    # main pushes). pull_request:closed+merged would miss the latter.
+    branches: [main]
+
+jobs:
+  trigger-claude-via-comment:
+    # Bounce 1: Codex review submitted -> @claude addresses it.
+    if: github.event_name == 'pull_request_review' && github.event.review.user.login == 'chatgpt-codex-connector[bot]' && github.event.review.state == 'commented'
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    env:
+      GH_TOKEN: ${{ secrets.AUTOFIX_TRIGGER_PAT }}
+      REPO: ${{ github.repository }}
+      PR_NUM: ${{ github.event.pull_request.number }}
+      REVIEW_ID: ${{ github.event.review.id }}
+      RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+    steps:
+      # Cap the auto-address loop at 7 claude runs per PR. If claude has
+      # already run 7+ times and Codex is still finding issues, the loop
+      # isn't converging — force human attention rather than burn cycles.
+      #
+      # Default was 3 originally; bumped to 7 because legitimate Codex
+      # reviews on substantive PRs routinely surface 5-6 rounds of real
+      # findings (defensive type guards across sibling files, CLI-flag
+      # table extensions, OSV event-window edge cases). 3 was capping
+      # real review work, not just runaway loops; 7 keeps the safety
+      # net while accommodating multi-round legitimate review. Adjust
+      # MAX below if your project's review patterns differ.
+      #
+      # Count claude-code-action runs by counting top-level PR comments
+      # authored by the bot (the action posts ONE in-progress comment
+      # per run and edits it in place to the "Claude finished..." summary
+      # — 1 comment == 1 run). More accurate than counting bot commits:
+      # a run that lands 0 commits (no-op fix or pre-push failure) and a
+      # run that lands N commits both equal one iteration of the loop.
+      #
+      # Login string is "claude" — NOT "claude[bot]" — because
+      # `gh pr view --json comments` uses GraphQL, and GraphQL's
+      # `author.login` returns the bare bot name without the `[bot]`
+      # suffix. The `[bot]` suffix only appears in REST surfaces (e.g.
+      # `github.event.comment.user.login` at bounce-2 below). Same bot,
+      # two string representations depending on which API you read.
+      - name: Cap auto-address iterations (max 7)
+        run: |
+          MAX=7
+          CLAUDE_RUNS=$(gh pr view "$PR_NUM" -R "$REPO" --json comments \
+            --jq '[.comments[] | select(.author.login == "claude")] | length')
+          if [ "$CLAUDE_RUNS" -ge "$MAX" ]; then
+            gh pr comment "$PR_NUM" -R "$REPO" --body "🛑 Auto-address loop limit hit — claude has already run $CLAUDE_RUNS times on this PR (max $MAX). Codex review id $REVIEW_ID was NOT auto-addressed. Manual review needed; re-tag claude explicitly after addressing the underlying issue if you want to continue. ([workflow run]($RUN_URL))"
+            echo "::error::Auto-address loop limit hit ($CLAUDE_RUNS/$MAX) — see PR comment."
+            exit 1
+          fi
+          echo "Auto-address iteration $((CLAUDE_RUNS + 1)) of $MAX"
+
+      # Post the @claude trigger. The body intentionally references "the
+      # Codex review above" — claude-code-action's default prompt
+      # construction will include the full review thread so the bot has
+      # the actual findings + line context to act on.
+      #
+      # No HEAD-SHA marker is needed here: bounce 2 is now driven by
+      # `pull_request: synchronize` (a real push), so "claude finished
+      # without pushing" simply produces no synchronize and no re-review —
+      # the old comment-driven no-push detection it required is gone.
+      - name: Post @claude trigger comment
+        run: |
+          gh pr comment "$PR_NUM" -R "$REPO" --body "@claude please address the Codex review feedback above. CRITICAL: before applying any fix that depends on infrastructure or invariants you have not verified, check the claim against its actual source of truth: for in-repo invariants (DLQ, schema, contracts, ADRs in docs/adrs/), grep the repo for the prerequisite; for claims about EXTERNAL behavior (a third-party SDK's import paths or API contract, a vendor's documented semantics, a wire format), use WebFetch/WebSearch to check the current official docs — do not accept the reviewer's citation on authority, and do not defend repo-internal assertions you cannot falsify. Only if the claim cannot be verified either way, push back via a PR comment explaining exactly what needs human confirmation rather than implementing on a false premise."
+
+  request-codex-rereview-on-push:
+    # Bounce 2: new commits pushed to a PR head -> @codex re-reviews HEAD.
+    # `pull_request: synchronize` fires on EVERY push to the PR head
+    # regardless of author — the claude bot's fixes, a human / local-agent
+    # push, AND the auto-rebase force-push from rebase-stale-prs — so this
+    # single job covers all of them. Replaces the old issue_comment /
+    # "Claude finished" trigger: claude-code-action commits via the Claude
+    # GitHub App (author claude[bot]), and App-authored pushes fire
+    # pull_request events (they are not the workflow's GITHUB_TOKEN, so not
+    # recursion-suppressed). "Claude finished without pushing" needs no
+    # special case now — no commits means no synchronize means no review.
+    #
+    # Same-repo only: GitHub withholds secrets from pull_request runs on
+    # fork PRs, so AUTOFIX_TRIGGER_PAT would be empty and `gh pr comment`
+    # would fail. Excluding forks here keeps fork PRs from producing red
+    # runs (and claude.yml refuses fork PRs downstream anyway).
+    if: >
+      github.event_name == 'pull_request'
+      && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    concurrency:
+      # Coalesce rapid pushes to one review of the final SHA. Without this,
+      # 5 quick commits = 5 separate @codex reviews (each distinct SHA
+      # dodges the per-SHA marker). cancel-in-progress keeps only the
+      # latest push's job, which then reads the current HEAD.
+      group: codex-rereview-${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+    env:
+      GH_TOKEN: ${{ secrets.AUTOFIX_TRIGGER_PAT }}
+      REPO: ${{ github.repository }}
+      PR_NUM: ${{ github.event.pull_request.number }}
+    steps:
+      # Per-SHA idempotency: skip if we already requested review for the
+      # current HEAD. Guards a double-synchronize on the same SHA and any
+      # overlap with a manual @codex review. Read live HEAD (not the event
+      # SHA) so a coalesced burst reviews the latest commit.
+      - name: Post @codex re-review trigger (idempotent per SHA)
+        run: |
+          HEAD_SHA=$(gh pr view "$PR_NUM" -R "$REPO" --json headRefOid --jq '.headRefOid')
+          MARKER="<!-- autofix-rereview-sha:$HEAD_SHA -->"
+          ALREADY=$(gh pr view "$PR_NUM" -R "$REPO" --json comments \
+            --jq "[.comments[] | select(.body | contains(\"$MARKER\"))] | length")
+          if [ "$ALREADY" -gt 0 ]; then
+            echo "Already requested @codex review for $HEAD_SHA — skipping."
+            exit 0
+          fi
+          gh pr comment "$PR_NUM" -R "$REPO" --body "$MARKER
+          @codex review the latest commits pushed to this PR."
+
+  rebase-stale-prs:
+    # Bounce 0: main moved -> for each open PR (same-repo only, fork PRs
+    # excluded), check mergeStateStatus and either rebase cleanly or ask
+    # @claude to resolve conflicts. Catches both PR-merge pushes and
+    # direct pushes to main.
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    concurrency:
+      # Coalesce: if main moves twice while we're still working on the
+      # first push, cancel and re-run with the latest SHA. Avoids racing
+      # two rebase runs against the same PR.
+      group: rebase-stale-prs
+      cancel-in-progress: true
+    env:
+      # Use the PAT for both gh API calls AND the git push. Pushing to a
+      # PR branch under GITHUB_TOKEN works but invalidates downstream
+      # workflow triggers (recursion guard) — the PAT keeps the @claude
+      # comment path working if this rebase later races with a Codex
+      # review on the same PR.
+      GH_TOKEN: ${{ secrets.AUTOFIX_TRIGGER_PAT }}
+      REPO: ${{ github.repository }}
+      MAIN_SHA: ${{ github.sha }}
+    steps:
+      # Graceful skip when the PAT secret isn't configured yet (initial
+      # repo setup). Without this guard, actions/checkout fails with
+      # "Input required and not supplied: token" on every push to main,
+      # turning every merge into a red workflow run during the window
+      # between "workflows scaffolded" and "secrets configured."
+      - id: have_pat
+        name: Check AUTOFIX_TRIGGER_PAT presence
+        env:
+          PAT: ${{ secrets.AUTOFIX_TRIGGER_PAT }}
+        run: |
+          if [ -z "$PAT" ]; then
+            echo "::warning::AUTOFIX_TRIGGER_PAT not set; skipping rebase. Add the secret per setup-autofix instructions to enable."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Checkout (full history for rebase)
+        if: steps.have_pat.outputs.skip != 'true'
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.AUTOFIX_TRIGGER_PAT }}
+
+      - name: Configure git author
+        if: steps.have_pat.outputs.skip != 'true'
+        run: |
+          git config user.email "actions@users.noreply.github.com"
+          git config user.name "github-actions[bot]"
+
+      - name: Rebase BEHIND PRs / flag DIRTY ones
+        if: steps.have_pat.outputs.skip != 'true'
+        run: |
+          set -euo pipefail
+
+          # mergeStateStatus values that matter:
+          #   CLEAN     - up to date with main (or ahead). skip.
+          #   BEHIND    - mergeable, base moved. clean rebase needed.
+          #   DIRTY     - conflicts. ask @claude.
+          #   BLOCKED   - branch protection or required checks failing. skip.
+          #   UNSTABLE  - mergeable but failing checks. skip — pre-existing.
+          #   UNKNOWN   - GitHub still computing. skip; next push retries.
+          #
+          # We exclude fork PRs: pushing to a fork branch from this workflow
+          # 403s, and posting @claude on a fork is blocked downstream by
+          # claude.yml's fork-refusal step anyway.
+          PRS_JSON=$(gh pr list --state open -R "$REPO" \
+            --json number,headRefName,mergeStateStatus,baseRefName,headRepository \
+            --jq "[.[] | select(.baseRefName == \"main\") | select(.headRepository.nameWithOwner == \"$REPO\")]")
+
+          echo "Open same-repo PRs targeting main:"
+          echo "$PRS_JSON" | jq -r '.[] | "  #\(.number) [\(.mergeStateStatus)] \(.headRefName)"'
+
+          # Process each PR. Loop over JSON array via index so we can read
+          # only env-style fields and never interpolate untrusted data.
+          COUNT=$(echo "$PRS_JSON" | jq 'length')
+          for i in $(seq 0 $((COUNT - 1))); do
+            PR_NUM=$(echo "$PRS_JSON" | jq -r ".[$i].number")
+            BRANCH=$(echo "$PRS_JSON" | jq -r ".[$i].headRefName")
+            STATUS=$(echo "$PRS_JSON" | jq -r ".[$i].mergeStateStatus")
+
+            # Defensive: branch names are user-controlled. Refuse anything
+            # that isn't a sane ref. (`refs/heads/<name>` syntax: letters,
+            # digits, slashes, dashes, underscores, dots.)
+            if ! printf '%s' "$BRANCH" | grep -qE '^[A-Za-z0-9._/-]+$'; then
+              echo "::warning::PR #$PR_NUM has unsafe branch name; skipping"
+              continue
+            fi
+
+            case "$STATUS" in
+              BEHIND)
+                echo "PR #$PR_NUM ($BRANCH): clean rebase needed"
+                git fetch origin "$BRANCH":"refs/remotes/origin/$BRANCH" --force
+                git checkout -B "$BRANCH" "origin/$BRANCH"
+                if git rebase origin/main; then
+                  if git push --force-with-lease origin "$BRANCH"; then
+                    gh pr comment "$PR_NUM" -R "$REPO" \
+                      --body "🔁 Auto-rebased on \`main\` (no conflicts) after $MAIN_SHA."
+                  else
+                    echo "::warning::Force-push of #$PR_NUM failed (lease lost?). Will retry on next push."
+                  fi
+                else
+                  # Race: GitHub said BEHIND but the rebase produced
+                  # conflicts. The next push will see DIRTY and route to
+                  # the @claude path.
+                  git rebase --abort
+                  echo "::warning::Rebase of #$PR_NUM failed despite BEHIND status (likely race with another push)"
+                fi
+                git checkout main
+                ;;
+              DIRTY)
+                echo "PR #$PR_NUM ($BRANCH): conflicts — asking @claude to rebase"
+                # Idempotency: don't re-ask claude for the same main SHA.
+                MARKER="<!-- autofix-rebase-claude:$MAIN_SHA -->"
+                ALREADY=$(gh pr view "$PR_NUM" -R "$REPO" --json comments \
+                  --jq "[.comments[] | select(.body | contains(\"$MARKER\"))] | length")
+                if [ "$ALREADY" -gt 0 ]; then
+                  echo "  already asked @claude for $MAIN_SHA — skipping"
+                  continue
+                fi
+                gh pr comment "$PR_NUM" -R "$REPO" --body "$MARKER
+                @claude main has moved and this PR has merge conflicts. Rebase \`$BRANCH\` onto the LATEST \`origin/main\` and resolve the conflicts.
+
+                CRITICAL — main may move again while you work (resolve + gate take minutes), so a rebase onto the main you first fetched can be stale by the time you push. Immediately before force-pushing, run \`git fetch origin main\` and verify ALL of:
+                1. \`git merge-base --is-ancestor origin/main HEAD\` exits 0 — the branch is on top of CURRENT main. If it fails, main advanced mid-rebase: re-fetch and rebase again.
+                2. \`git log --oneline origin/main..HEAD\` shows ONLY this PR's own commits — no main commits and no merge commit (a merge commit means you merged instead of rebased).
+                3. the local pre-push gate passes.
+                Then force-push. AFTER pushing, confirm \`gh pr view $PR_NUM --json mergeStateStatus -q .mergeStateStatus\` is no longer DIRTY/CONFLICTING (wait for it to leave UNKNOWN — GitHub recomputes for a few seconds). Do NOT report the rebase as done until that check passes; if it stays conflicting or main keeps moving, say so in a comment instead of force-fitting a resolution.
+
+                If the conflicts indicate the new main invalidates this PR's approach, push back via a comment instead of resolving."
+                ;;
+              CLEAN)
+                echo "PR #$PR_NUM ($BRANCH): already current — skipping"
+                ;;
+              *)
+                echo "PR #$PR_NUM ($BRANCH): status $STATUS — leaving alone"
+                ;;
+            esac
+          done