feat(gh): PR preflight for branch name, issue link, and body contract #2570

Goal

Reject an invalid branch or PR body before the pull request exists, using the same validators as the CI policy.

Background

Seven of the last forty pull requests were closed and recreated from a canonical branch, and the branch-name policy fires only after PR creation (#2547 -> #2548, #2535 -> #2537, #2522 -> #2523, and four more; see #2569). basectl gh pr create already derives the issue link from a conforming branch name, but nothing validates the name first. The CI validator is embedded Bash inside the 508-line issue-branch-policy.yml workflow.

Next-release planning review of 2026-10-14/15 against main at 7faf6dfb. Tracking: #2555.

Prerequisites: #2569.

Scope

• Add basectl gh pr preflight (and run it inside gh pr create) validating branch pattern, calendar-valid date, category versus the issue's single category label, and linked issue state.
• Share one validator implementation between the command and the workflow rather than reimplementing the regex.
• JSON output with finding IDs following the shared inspection envelope.
• Optional pre-push hook installer, off by default.

Acceptance Criteria

• Verdicts match the workflow on a fixture corpus of valid and invalid names, dates, and category mismatches.
• gh pr create refuses an invalid branch before any network call that creates a PR.
• Docs and shell completions are updated; the command's stability tier is stated.

Validation

bats cli/bash/commands/basectl/tests/gh.bats
shellcheck <changed shell files>
python -m pytest tests/test_issue_branch_policy_workflow.py tests/test_github_workflows.py
env -u BASE_HOME ./bin/base-test
git diff --check

Non-Goals

• Do not change the branch naming convention.
• Do not make the hook mandatory.

Project Fields

• Status: Backlog
• Priority: P1
• Area: CLI
• Initiative: Agentic Coding Platform
• Size: M
• Milestone: v1.11.0
• Category: enhancement

Agent Assignment

Assignee: codeforester. Blocked on #2569 findings. Then implementation-ready.