Dbt Databricks Pr Ready

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:

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:

   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.