[Phase 3] Docs cutover + end-to-end new-repo validation

[github-actions]

Story

As a developer onboarding a new repo,
I want update the "Applying to a New Repository" checklists to make template + bootstrap the primary path and validate the full flow end-to-end,
so that the documented onboarding path is the one-click + one-command path, proven to produce a compliant repo.

Acceptance Criteria

1. standards/github-settings.md and standards/ci-standards.md "Applying to a New Repository" checklists are updated to point at "Use this template" + scripts/bootstrap-new-repo.sh as the primary path, with the legacy script runbook kept only as the existing-repo fallback.
2. An end-to-end DRY_RUN validation is recorded: Use-template (or a scratch repo) -> bootstrap-new-repo.sh (DRY_RUN) -> ring confirmation, whose intended state covers repo settings, both rulesets with bypass actors, required checks, labels, CODEOWNERS, push protection, and the recorded ring with no drift.
3. The validated flow passes shellcheck scripts/*.sh and the lint.yml-equivalent checks with no errors.
4. The two open onboarding questions are resolved or explicitly deferred in BOOTSTRAP.md: whether framework subtrees (frameworks/) are seeded by the template or opt-in, and whether the bootstrap performs app installs (Claude/CodeRabbit) or they remain a documented manual step.

Tasks / Subtasks

• Update standards/github-settings.md and standards/ci-standards.md (cross-repo, petry-projects/.github) to make template + bootstrap the primary path and demote the manual runbook to an existing-repo fallback. (AC: test issue from agent #1)
• Run and record the end-to-end DRY_RUN walkthrough covering the full policy surface + ring. (AC: Go-live improvements for PR review agent #2, Add @claude delegation, auto-merge, and rebase handling #3)
• Document the frameworks-seeded-vs-opt-in and app-install handling decisions in BOOTSTRAP.md. (AC: Optimize review: small-PR and incremental fast paths #4)

Dev Notes

• The docs live cross-repo in petry-projects/.github: standards/github-settings.md (the 9-step settings checklist) and standards/ci-standards.md (the 13-step CI checklist). Update them via the aw-standards-sync.sh cross-repo PR pattern (STANDARDS_REPO=petry-projects/.github).
• deploy-standard-workflows.sh remains the ongoing-sync path for EXISTING repos (out of scope to replace); the docs must state the template seeds day-0 only and ongoing updates still flow through the PR-based sync.
• frameworks/ here are installed via git subtree (bmad-method, spec-kit, gsd); the idea-enhancer comment explicitly raised "are frameworks opt-in or seeded?" and "does bootstrap handle app installs?" — both must be answered in BOOTSTRAP.md, not left implicit.

Project Structure Notes

Primary edits are cross-repo docs in petry-projects/.github plus BOOTSTRAP.md in repo-template; the validation exercises this repo's bootstrap + apply-* scripts under DRY_RUN.

References

• https://github.com/petry-projects/.github/blob/main/standards/github-settings.md
• https://github.com/petry-projects/.github/blob/main/standards/ci-standards.md
• scripts/aw-standards-sync.sh
• AGENTS.md
• discussion Create a GitHub template repository to scaffold new petry-projects repos with org standards #962

Likely target surface

• scripts/aw-standards-sync.sh

Story prepared by the BMAD Scrum Master (Bob) for epic #964. Status: ready-for-dev.

[don-petry]

Dev-Lead Implementation Plan

Issue: #970 — [Phase 3] Docs cutover + end-to-end new-repo validation

Scope

Make template + bootstrap-new-repo.sh the documented primary onboarding path, resolve the two open onboarding questions in the generated BOOTSTRAP.md, and record an end-to-end DRY_RUN validation covering the full policy surface with no drift.

Boundary note (cross-repo)

AC #1's checklists (standards/github-settings.md, standards/ci-standards.md) live in petry-projects/.github, not in this repo, and the dev-lead branch may not open cross-repo PRs. The cutover content + mechanism (template+bootstrap = primary path; legacy script runbook demoted to existing-repo fallback; template seeds day-0 only, ongoing updates via the PR-based sync) is captured in the recorded validation doc so it can be landed via the aw-standards-sync.sh / cross-repo PR pattern (STANDARDS_REPO=petry-projects/.github). This is flagged explicitly in the completion report.

Implementation Checklist

• scripts/seed-repo-template.sh — extend the generated BOOTSTRAP.md to resolve the two open questions: (a) frameworks/ subtrees are opt-in, not template-seeded; (b) app installs (Claude/CodeRabbit) remain a manual org-admin step, bootstrap only disables their check-suite auto-trigger. (AC Optimize review: small-PR and incremental fast paths #4)
• docs/bootstrap/new-repo-validation.md — recorded end-to-end DRY_RUN walkthrough (template → bootstrap-new-repo.sh DRY_RUN → ring confirmation) + intended-state checklist (repo settings, both rulesets w/ bypass actors, required checks, labels, CODEOWNERS, push protection, recorded ring, no drift) + the AC test issue from agent #1 cross-repo cutover content. (AC test issue from agent #1, Go-live improvements for PR review agent #2)

Tests to Write

• tests/test_seed_repo_template.bats — assert the generated BOOTSTRAP.md answers both open questions (frameworks opt-in; app installs manual). (AC Optimize review: small-PR and incremental fast paths #4)
• tests/test_bootstrap_new_repo.bats — add one full-surface end-to-end DRY_RUN test asserting the whole intended-state surface in a single run with zero write API calls (no drift). (AC Go-live improvements for PR review agent #2, Add @claude delegation, auto-merge, and rebase handling #3)

Test Command

scripts/run-bats.sh tests/test_bootstrap_new_repo.bats tests/test_seed_repo_template.bats and bash .dev-lead/scripts/dev-lead-lint.sh (shellcheck + frontmatter)

[don-petry]

Dev-Lead: Implementation Complete

Plan Execution

• AC Optimize review: small-PR and incremental fast paths #4 — Resolved both open onboarding questions in the generated BOOTSTRAP.md (scripts/seed-repo-template.sh): (a) frameworks/ subtrees are opt-in, not template-seeded; (b) app installs (Claude/CodeRabbit) remain a manual org-admin step — bootstrap only disables their check-suite auto-trigger.
• AC Go-live improvements for PR review agent #2/Add @claude delegation, auto-merge, and rebase handling #3 — Recorded the end-to-end DRY_RUN walkthrough (template → bootstrap-new-repo.sh DRY_RUN → ring confirmation) in docs/bootstrap/new-repo-validation.md, plus an executable full-surface validation test. The flow is clean under shellcheck and the lint suite.
• AC test issue from agent #1 — Captured the cross-repo checklist cutover content + mechanism in the validation doc (see scope note below).

Scope note — AC #1 is cross-repo

The two "Applying to a New Repository" checklists live in petry-projects/.github (standards/github-settings.md, standards/ci-standards.md), not in this repo, and the dev-lead branch must not open cross-repo PRs. The cutover content + mechanism (template+bootstrap = primary path; legacy runbook demoted to existing-repo fallback; template seeds day-0 only, ongoing updates via the PR-based sync) is recorded in docs/bootstrap/new-repo-validation.md so it can be landed via the standards cross-repo PR pattern (STANDARDS_REPO=petry-projects/.github). Follow-up: open that cross-repo PR to apply the two checklist edits.

Test Results

# Affected files
$ scripts/run-bats.sh tests/test_bootstrap_new_repo.bats tests/test_seed_repo_template.bats
38 ok, 0 not ok

# Full lint.yml bats suite (50 files)
872 ok, 0 not ok

# Required lint
$ bash .dev-lead/scripts/dev-lead-lint.sh
  [lint] all checks passed   (shellcheck warning-level clean; agent frontmatter + CODEOWNERS OK)

$ shellcheck --severity=warning scripts/seed-repo-template.sh scripts/bootstrap-new-repo.sh
  (clean)

Files Changed

• scripts/seed-repo-template.sh: added a "What this template does NOT do" section to the generated BOOTSTRAP.md resolving the frameworks-opt-in and app-install-manual questions (AC Optimize review: small-PR and incremental fast paths #4).
• docs/bootstrap/new-repo-validation.md (new): primary onboarding path, recorded DRY_RUN transcript (stable + ring1), intended-state coverage table (settings, both rulesets w/ bypass actors + required checks, push protection, labels, CODEOWNERS, recorded ring, no drift), and the AC test issue from agent #1 cross-repo cutover content.
• tests/test_seed_repo_template.bats: assert BOOTSTRAP.md answers both open questions (AC Optimize review: small-PR and incremental fast paths #4).
• tests/test_bootstrap_new_repo.bats: new end-to-end DRY_RUN test asserting the whole intended-state surface in one run with zero write API calls (AC Go-live improvements for PR review agent #2/Add @claude delegation, auto-merge, and rebase handling #3).

Notes

• TDD: the AC Optimize review: small-PR and incremental fast paths #4 assertion was written failing-first, then made green by the generator change. The new e2e test is itself the executable validation. The validation doc is pure documentation (Phase 2 exception).
• The DRY_RUN walkthrough was captured with gh stubbed to a no-op reader, so the real apply-* sub-scripts run end-to-end without network/writes — the same seam the bats suite uses.
• Out of scope (unchanged): deploy-standard-workflows.sh / aw-standards-sync.sh remain the ongoing-sync path for existing repos; the template seeds day-0 only.