feat: require branch protection at repo init (close enforcement gap)

[CybotTM]

Summary

Close the structural enforcement gap that just allowed three unresolved bot-reviewer threads — including a HIGH-severity token leak — to ship to main in netresearch/snipe-it-docker-compose-stack#17. The skill already documented branch protection and already had a checkpoint (GH-31) for required_conversation_resolution: true, but there was nothing prompting an operator to actually apply protection at gh repo create time, before the first PR opens. By the time /assess github-project would have caught the miss, PRs were already merging.

This PR adds a first-class init surface so the structural rule is applied at repo-creation time, not audited after the fact.

What's in the PR

• skills/github-project/scripts/init-branch-protection.sh — runnable, idempotent. Takes <owner>/<repo>, reads the new template, PUTs to repos/{owner}/{repo}/branches/{default_branch}/protection. Uses gh api -X PUT --input - with JSON body (NOT --raw-field, which silently breaks on nested JSON — that's exactly what wasted three retries in snipe-it#15). Handles empty-repo (exit 4), no access (exit 3), already-compliant (exit 0), and drift on opinionated fields (exit 1 with a per-field diff, no silent clobber).
• skills/github-project/assets/branch-protection.json.template — synthesized from snipe-it's live post-fix state with two deliberate adjustments: enforce_admins: false explicit (so solo-maintainer repos like ldap-selfservice-… or usercentrics-widgets aren't painted into a corner), and required_signatures omitted (not set to false) so the script never resets a repo that has already opted into signing. Both are documented in the script header as per-repo tightening one-liners.
• --from-current-checks follow-up flag — after the first CI run completes on the default branch, re-invoke with this flag and the script discovers the successful check-run names from the most recent completed run and PATCHes them in as required status contexts with strict: true.
• SKILL.md — new "Required First Step After `gh repo create`" section right after "When to Use". The "When to Use" list now leads with the init step. "Quick Diagnostics" gets a one-liner (gh api repos/OWNER/REPO/branches/.../protection --jq '.required_conversation_resolution.enabled'). "Running Scripts" lists the new script alongside the existing verifier.
• checkpoints.yaml feat: add skill validation CI job #31 — severity was already error (verified). The desc: now names the user-visible failure mode (silent unresolved-thread merges including token leaks like snipe-it#17) and points operators at the new script as the apply path.
• README.md — 7-line callout at the top so someone landing on the repo page sees the init step without scrolling.

The new flow

gh repo create netresearch/new-thing --public --clone
cd new-thing
git push -u origin main          # need at least one commit so the default branch ref exists
bash ../github-project-skill/main/skills/github-project/scripts/init-branch-protection.sh \\
    netresearch/new-thing
# ... open PRs, run CI ...
bash .../init-branch-protection.sh netresearch/new-thing --from-current-checks

What this does NOT fix (deliberately, follow-up)

GitHub branch protection still cannot block on a requested-but-pending review. The snipe-it#17 leak slipped through the unresolved-threads class, which this PR's baseline (required_conversation_resolution: true) DOES close structurally. The pending-reviewer class (Copilot is mid-review, merge anyway) remains a workflow-discipline gap — see references/security-config.md lines 144-152. Closing it requires a status-check workflow (out of scope here).

Verification before merge

Run the unresolved-threads GraphQL check before any merge attempt:

gh api graphql -f query='query{repository(owner:\"netresearch\",name:\"github-project-skill\"){
  pullRequest(number:NUMBER){reviewThreads(first:100){nodes{isResolved}}}
}}' --jq '.data.repository.pullRequest.reviewThreads.nodes | map(select(.isResolved == false)) | length'

Abort merge if non-zero. (This PR's own correctness is also a useful test of the rule it documents.)

Test plan

• shellcheck clean on init-branch-protection.sh
• bash -n clean
• Live-tested against netresearch/snipe-it-docker-compose-stack — reports already compliant (idempotent path works against the repo whose incident motivated this PR)
• Error paths exercised: no arg → exit 2, bad slug → exit 2, 404 repo → exit 3, bad flag → exit 2
• markdownlint-cli2 clean on SKILL.md and README.md
• yamllint clean on checkpoints.yaml
• All four commits signed (verified via git log --show-signature)
• CI green on this branch
• Unresolved-threads GraphQL check returns 0 before merge

Atomic commits

1. feat(scripts): add init-branch-protection.sh for new-repo bootstrap
2. docs(skill): require branch-protection init step before first PR/commit
3. feat(checkpoints): clarify required_conversation_resolution failure mode in GH-31
4. docs(readme): announce required init step at top of README

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Pull request overview

Adds a repository-initialization step to apply a baseline GitHub branch protection configuration at repo creation time, closing the gap where “required conversation resolution” was documented/audited but not structurally enforced early enough to prevent unresolved-thread merges.

Changes:

• Introduces an idempotent init-branch-protection.sh script plus a JSON template to apply baseline branch protection and optionally derive required checks from the latest CI run.
• Updates skill documentation (SKILL.md + README) to require running the init step for new repositories and adds quick diagnostics commands.
• Clarifies checkpoint GH-31 messaging to point to the new apply path and describe the concrete failure mode.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
skills/github-project/SKILL.md	Documents the required “post-gh repo create” initialization flow and adds diagnostics/script references.
skills/github-project/scripts/init-branch-protection.sh	New script to apply baseline branch protection and optionally set required checks from current CI runs.
skills/github-project/checkpoints.yaml	Updates GH-31 description to describe the enforcement gap and reference the new init script.
skills/github-project/assets/branch-protection.json.template	Adds the baseline branch protection JSON used by the init script.
README.md	Adds a prominent callout instructing new repos to run the init branch protection script before the first PR.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[gemini-code-assist]

Code Review

This pull request introduces a new script, init-branch-protection.sh, and a JSON template to automate the application of standard branch protection rules to GitHub repositories. It also updates documentation across README.md, SKILL.md, and checkpoints.yaml to mandate this process after repository creation. Review feedback highlighted a bug in the script where missing jq flags would cause incorrect job name encoding and suggested using $ARGS.positional for more robust JSON array construction.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud