---
name: dbt-databricks-pr-ready
description: "Use for an open dbt-databricks pull request, including your own PR or a fork PR, to assess merge readiness and optionally repair selected gaps on the PR head branch. Accepts a PR link or number and optional --auto."
---

# dbt-databricks PR-readiness driver

Input is a URL or bare number for `databricks/dbt-databricks`, plus optional
`--auto`. If no PR is supplied, run `gh pr view` without `--repo` from the
current branch and use the result only when it resolves exactly one PR in
`databricks/dbt-databricks`; otherwise ask for the URL or number. For an
explicit URL or number, use `gh pr view <input> --repo databricks/dbt-databricks`.
`--auto` selects recommended gaps only. It never authorizes a commit or push.

The deliverable is an assessment report and, only when the caller can write the
PR head branch and approves each gate, verified commits on that branch.

## Hard rules

- Never merge, comment on, label, retarget, or create a PR.
- Never rewrite history, rebase silently, or discard local work.
- Never commit or push without explicit user approval after showing the changes
  and verification evidence. `--auto` does not bypass either approval.
- Run and read every selected test and lint command. Commit only verified work.
- Stop if the PR head moves after the run starts. Never overwrite a contributor's
  newer head.
- Never make tracked repairs in the repository's shared primary checkout. Do
  writable work in a git worktree that is not that checkout. Use the worktree
  the active harness already supplied, or create one; its location does not
  matter. Keep the run report under the primary checkout's ignored
  `.agents/pr-ready/` directory.
- Do not put run reports, generated evaluation output, personal paths, accounts,
  or local tooling details into committed files. The co-located `eval-spec.md`
  is a checked-in behavioral contract, not run output.

## Phase 1 — Resolve the PR, write scope, and worktree

1. Set `ACTIVE_ROOT` to `git rev-parse --show-toplevel`, `COMMON_GIT_DIR` to
   `git -C "$ACTIVE_ROOT" rev-parse --git-common-dir` resolved against
   `ACTIVE_ROOT` when the result is relative, `PRIMARY_ROOT` to the parent of
   `COMMON_GIT_DIR`, and `REPO` to `databricks/dbt-databricks`. Require a
   non-bare repository whose common Git directory is `PRIMARY_ROOT/.git`, and
   require at least one configured remote whose normalized GitHub slug is
   exactly `REPO`; otherwise stop before any mutation.

   Set `REPORT` to `$PRIMARY_ROOT/.agents/pr-ready/pr-<N>/report.md`. Do not
   use `PRIMARY_ROOT` as the repair worktree.
2. Confirm `gh auth status`, capture `ME` with `gh api user -q .login`, and
   fetch PR metadata including its state, draft status, author, base branch,
   head branch, head SHA, head repository, head repository owner,
   `isCrossRepository`, `maintainerCanModify`, `mergeable`,
   `statusCheckRollup`, `closingIssuesReferences`, and `files`.
   Re-query an initially `UNKNOWN` mergeability result before treating it as a
   verdict. Stop for a closed or merged PR, a missing head repository, or a
   missing head ref. Draft PRs are valid inputs.
3. Record `SOURCE_SHA=headRefOid`. Derive `HEAD_SLUG` from
   `headRepositoryOwner.login` and `headRepository.name`; do not use
   `headRepository.nameWithOwner`. Prefer an existing Git remote whose URL
   normalizes to that exact slug. Otherwise use
   `https://github.com/<HEAD_SLUG>.git` directly without adding a persistent
   remote or guessing from the branch name.
4. Classify branch write access before proposing repairs:

   | PR head | Write mode |
   |---|---|
   | Head repository owner is `ME` | `owner` — the contributor may update their own fork branch. |
   | PR is in `REPO` and the caller has `ADMIN`, `MAINTAIN`, or `WRITE` viewer permission | `repository` — update the in-repository head branch. |
   | Fork PR, `maintainerCanModify` is true, and the caller has upstream `ADMIN`, `MAINTAIN`, or `WRITE` permission | `maintainer` — update that contributor's fork head branch. |
   | Any other case | `read-only` — assess only; do not edit, commit, or push. |

   Obtain upstream viewer permission with `gh repo view "$REPO" --json
   viewerPermission`. The PR author is never a hard stop. `maintainerCanModify`
   controls only the third row; it is not required for an in-repository PR or
   for the contributor's own fork.
5. For `owner`, `repository`, or `maintainer` mode, fetch the exact source ref
   into `refs/pr-ready/<N>/head` and verify it equals `SOURCE_SHA`. Do not use
   `gh pr checkout`: it does not provide a stable, unambiguous push target for
   this workflow.
   - If `ACTIVE_ROOT` differs from `PRIMARY_ROOT`, set `WT` to `ACTIVE_ROOT`.
     Require it to use `COMMON_GIT_DIR` and to have an empty
     `git status --porcelain` (do not pass `--ignored`). If `HEAD` equals the
     fetched source ref, keep it. If `HEAD` differs and the current commit is
     detached and not reachable from any local branch or remote-tracking ref,
     do not check out into that worktree; create a different detached worktree
     at the fetched ref using the host's usual worktree location and set `WT`
     to that path. Otherwise check out the exact fetched ref detached.
   - If `ACTIVE_ROOT` equals `PRIMARY_ROOT`, create a detached worktree at the
     fetched ref using the host's usual worktree location and set `WT` to that
     path. When creating a worktree, if the chosen path already exists and
     diverges, pick another path or stop; never discard its work.
   - Do not create symlinks or shared configuration inside the worktree.
   - In `read-only` mode, do not create, check out, edit, or configure `WT`.
     Gather assessment evidence from PR metadata, the PR diff, public check
     output, and other non-mutating reads instead.
   After `WT` is final in a writable mode, require
   `git -C "$WT" rev-parse --show-toplevel` to equal `WT` and to differ from
   `PRIMARY_ROOT`, then verify `HEAD` equals `SOURCE_SHA` before edits. Run
   every later edit, test, and git command with `WT` as the working directory.
   If the host can retarget the visible workspace root, do that immediately;
   if it cannot, keep using explicit paths under `WT` and do not edit
   `PRIMARY_ROOT`.
6. In a writable mode only, install pre-commit hooks in `WT` when
   `core.hooksPath` is unset. When it is set, record that hooks are configured
   externally. Never install or run pre-commit hooks in `read-only` mode; hooks
   may mutate files. The explicit all-files pre-commit run in Phase 5 remains
   mandatory for writable runs.
7. Create the report skeleton at `REPORT`, noting PR URL, `SOURCE_SHA`, write
   mode, resolved head slug, and worktree path.

## Phase 2 — Assessment

Read `references/rubric.md` and evaluate every item against the PR metadata and
diff. The report must contain one **met**, **gap**, or **n-a** row per item;
each gap needs evidence, a one-line fix, rough effort, and its recommended or
optional status. If there are no gaps, mark the PR merge-ready as-is and stop.

## Phase 3 — Selection

- Interactive mode: present each gap as a selectable option, recommended items
  first, and record the user's selection.
- `--auto`: select every recommended gap and record optional gaps as
  skipped-by-policy.

Selection authorizes edits and verification only. It does not authorize a
commit or push. In `read-only` mode, report the selected fixes but do not start
an edit; explain that the PR head is not writable by the current caller,
finalize the assessment and selection report, and stop immediately. Do not
enter Phase 4 or Phase 5, edit a worktree, or invoke a mutating hook.

## Phase 4 — Repair selected gaps

Work selected items in this order: code and test changes, lint, then changelog.
For every item, follow the rubric's fix recipe and read the resulting test
output. Review the run's additions for unnecessary complexity, show the exact
diff and test evidence, and obtain explicit commit approval. After approval and
immediately before the commit, re-check that the PR head still equals
`SOURCE_SHA`. Commit only that verified item and never add attribution footers.

After three unsuccessful repair attempts or an unavailable required service,
mark the item blocked. If the run created a partial diff, preserve it with
untracked files in a clearly named stash, for example:

```bash
git stash push --include-untracked \
  -m "pr-ready #<N>: blocked <rubric-item> partial repair"
```

Record the stash reference and name in the report, then require
`git status --porcelain` to be empty. If the stash cannot be created or the
worktree cannot be made clean without discarding work, stop the entire run.
Only after successful preservation and cleanup may independent selected items
continue. Apply the same preservation rule before any hard stop that leaves
run-created changes, including a moved-head stop; never apply a blocked-item
stash during final verification.

## Phase 5 — Final verification and push

1. Require `git status --porcelain` to be empty, record
   `VERIFIED_SHA=$(git rev-parse HEAD)`, and confirm the index and worktree have
   no diff from `HEAD`. From `WT`, run
   `hatch run pre-commit run --all-files`; it must pass without changing the
   worktree. If it creates a diff, final verification fails; handle that diff
   as a separately approved repair or preserve it and stop.
2. Re-run every test touched by the selected repairs and read the output.
   Require `HEAD` still to equal `VERIFIED_SHA` and the worktree still to be
   clean afterward. This verification covers committed `HEAD` only; results
   from a leftover partial diff do not count.
3. Finalize `REPORT` with the assessment table, selection method, write mode,
   per-item outcome and evidence, blocked items, and pre-existing noise.
4. If no local commits were created, stop after the report.
5. Before pushing, show the exact destination and ask for explicit approval.
   After approval and immediately before the push:
   - Re-query `CURRENT_ME=$(gh api user -q .login)` and require it to equal the
     captured `ME`.
   - Re-fetch the PR's head SHA, head ref, head repository and owner,
     `isCrossRepository`, and `maintainerCanModify`, plus the upstream
     `viewerPermission`.
   - Recompute the Phase 1 write mode from those fresh values. Require the
     applicable ownership, repository permission, or opted-in maintainer
     condition still to hold, the result still to equal the captured writable
     mode, and the resolved head repository and branch still to match the
     approved destination.
   - Require the fresh remote head SHA to equal `SOURCE_SHA`, local `HEAD` to
     equal `VERIFIED_SHA`, and the worktree to remain clean.

   If any check fails, do not push. Otherwise push only to the resolved head
   repository and branch with the exact-SHA lease:

   ```bash
   git push --force-with-lease="refs/heads/<headRefName>:<SOURCE_SHA>" \
     <resolved-head-remote-or-url> HEAD:refs/heads/<headRefName>
   ```

   If the lease or permission check fails, do not retry with a broader force
   option; leave commits local and report the failure. After a successful push,
   verify that the PR head equals local `HEAD` and record that SHA in `REPORT`.