#65 docs(graphite-pr): reconcile vendored copy with runtime canonical

Summary

• Reconcile two-way drift between the vendored .claude/skills/graphite-pr/SKILL.md and the runtime canonical at ~/.agents/skills/graphite-pr/SKILL.md. Each had improvements the other lacked.
• Merged section "After submit: merge" now keeps:
  • Runtime side: scripts/gt-merge-cascade.sh for stacks; GraphQL pre-flight (reviewThreads + reviewDecision) for single-PR safety net before gh pr merge.
  • Vendored side: diagnostic for when the Graphite / AI Reviews check doesn't appear; bottom-up gh pr merge alternative; --delete-branch cascade-close warning + --base $(gt trunk) workaround; "record SHA before gt sync --force" tip.
• Quick-reference: split the "track an untracked branch" row into first-time (use literal trunk name — gt trunk errors when HEAD itself is untracked) and existing-stack (the original $(gt trunk) form). This came from a real failure during a Nazgûl run earlier today.
• Runtime canonical at ~/.agents/skills/graphite-pr/SKILL.md mirrored to match — Claude continues to read it via the existing symlink at ~/.claude/skills/graphite-pr; Codex picks it up via its [[skills.config]] entry.

Test plan

• Open the file and skim the merged "After submit: merge" section reads coherently end-to-end (no leftover bullets from one side, no contradictions).
• diff -q ~/.agents/skills/graphite-pr/SKILL.md .claude/skills/graphite-pr/SKILL.md returns no output (sync verified locally; re-verify on merge).
• Markdown lint stays green per repo .markdownlint.json.

🤖 Generated with Claude Code

---

Summary by cubic

Reconciled the vendored ./.claude/skills/graphite-pr/SKILL.md with the runtime canonical and hardened the merge flow with a vendored cascade script, stricter GraphQL gates, and clearer recovery guidance to prevent unsafe merges on large PRs. Also validated cascade script CLI args to preserve the JSON error contract.

• Refactors
  • Vendored scripts/gt-merge-cascade.sh; script now validates CLI poll/timeout as positive integers, validates the stack, blocks on unresolved threads, CHANGES_REQUESTED, and >100-thread truncation, maps branches→PRs safely (fails if any branch lacks an open PR), runs gt merge, polls to completion, and emits JSON.
  • Single-PR gate: GraphQL pre-flight uses reviewThreads(first:100) with pageInfo.hasNextPage → truncated; merge only when unresolved == 0, decision != "CHANGES_REQUESTED", and truncated == false.
  • Docs: fixed broken troubleshooting link to references/recovery.md; kept the Graphite/AI Reviews diagnostic, bottom-up gh pr merge alternative, --delete-branch warning + --base $(gt trunk) workaround, SHA-before-sync tip; quick-reference splits first-time vs existing-stack gt track.

Summary by CodeRabbit

• New Features

  • Added automated merge-cascade: validates stack readiness, gates on unresolved review threads/decisions, performs merges, and reports per-PR timing and failures.
  • Added single-PR preflight to block merges when reviews are unresolved or changes are requested.

• Documentation

  • Simplified merge instructions, added a “Graphite merge queue” option, explicit recovery guidance, and clearer first-time vs existing-branch tracking steps.