build: require validate branch protection context

Why:
GitHub exposes the managed repo-maintenance workflow check as the job context validate, not the display-style Validate Repo Maintenance / validate string. New repos could pass CI but stay blocked by branch protection when guidance used the display string.

Verification:
- uv run pytest skills/maintain-project-repo/tests/test_maintain_project_repo_workflow.py
- uv run pytest tests/test_swift_package_guidance_sync_workflow.py tests/test_xcode_guidance_sync_workflow.py
- bash .github/scripts/validate_repo_docs.sh
- uv run scripts/validate_socket_metadata.py
- uv run pytest (plugins/apple-dev-skills)
- uv run pytest (plugins/productivity-skills)

Closes #14

Author: gaelic-ghost

plugins/apple-dev-skills/ROADMAP.md

@@ -359,6 +359,7 @@ Completed Milestone 40 by shipping `swiftui-app-architecture-workflow`, groundin
 
 ## History
 
+- Clarified the Apple repo-maintenance toolkit's branch-protection contract so generated and synced repos require the `validate` Actions check context instead of the workflow-title display string.
 - Completed Milestones 1 through 17 by establishing the repository, shipping the core Apple skill bundle, improving portability and customization guidance, adding bootstrap and repo-sync workflows, extracting Apple docs exploration into its own skill, and cleaning up the install surface around the top-level export model.
 - Completed Milestones 19 and 20 by shipping `format-swift-sources` and `structure-swift-sources` as distinct cleanup workflows with clear boundaries.
 - Completed Milestones 22 and 23 by expanding deterministic TODO/FIXME ledger normalization and finishing the customization consolidation review. See `docs/maintainers/customization-consolidation-review.md`.

plugins/apple-dev-skills/docs/maintainers/workflow-atlas.md

@@ -88,6 +88,7 @@ flowchart TD
 - The active skill surface now uses the intended install-facing names directly.
 - The shared repo-maintenance toolkit now lives inside the active Apple skill surface under `shared/repo-maintenance-toolkit/` so bootstrap and sync skills can keep installing the same managed file set without a second plugin or repo.
 - The canonical shipped toolkit contract now lives in this repository, stays profile-aware, and gives downstream repos `scripts/repo-maintenance/config/profile.env` while Apple workflows choose either the `swift-package` or `xcode-app` profile explicitly.
+- The managed workflow's protected-branch check context is `validate`; GitHub exposes the job check run by that context, not by the display-style workflow title plus job string `Validate Repo Maintenance / validate`.
 - The Swift package side of the execution split is now in place, with build-run and testing split into separate primary skills while `swift-package-workflow` remains only as a legacy compatibility-routing surface.
 - The Xcode side of the execution split is now in place too, with `xcode-build-run-workflow` and `xcode-testing-workflow` as the real owners while `xcode-app-project-workflow` remains only as a legacy compatibility-routing surface.
 

plugins/apple-dev-skills/shared/repo-maintenance-toolkit/assets/github/repo-maintenance-workflows/validate-repo-maintenance.yml

@@ -1,5 +1,8 @@
 name: Validate Repo Maintenance
 
+# Branch protection should require the Actions check context `validate`.
+# GitHub exposes the job check run by this job name, not by the workflow title.
+
 on:
   pull_request:
   push:
@@ -8,6 +11,7 @@ on:
 
 jobs:
   validate:
+    name: validate
     runs-on: macos-latest
     steps:
       - uses: actions/checkout@v4

plugins/apple-dev-skills/skills/bootstrap-swift-package/SKILL.md

@@ -62,6 +62,7 @@ Create a new Swift package repository with one top-level entry point, a simplici
    - `scripts/repo-maintenance/release.sh`
    - `Tests/`
    - `swift build` and `swift test` unless `--skip-validation` was requested
+   - branch protection, when enabled, requires the GitHub Actions check context `validate`; do not require the display-style string `Validate Repo Maintenance / validate`
 7. Ensure the generated guidance encodes the shared Swift policy:
    - apply the detailed local policy in `references/snippets/apple-swift-package-core.md`
    - keep the generated repo aligned with the simplicity-first, shape-preserving, and anti-ceremony Swift guidance in that snippet
@@ -138,6 +139,7 @@ Create a new Swift package repository with one top-level entry point, a simplici
 - After a successful scaffold, hand off Xcode-managed package build or run tasks to `xcode-build-run-workflow`.
 - After a successful scaffold, hand off Xcode-managed package test tasks to `xcode-testing-workflow`.
 - After a successful scaffold, use `scripts/repo-maintenance/validate-all.sh` for local maintainer validation and `scripts/repo-maintenance/release.sh` for releases.
+- After a successful scaffold, configure protected branches to require `validate` for the managed repo-maintenance workflow; GitHub exposes that job check context directly rather than the workflow title plus job string.
 - After a successful scaffold, hand off later repo-guidance alignment work to `sync-swift-package-guidance`.
 - For ordinary package work, prefer `swift build` and `swift test`.
 - For package builds that need Xcode-managed SDK or toolchain behavior, use `xcode-build-run-workflow` and `xcodebuild` guidance instead of stretching the bootstrap skill into an execution skill.

plugins/apple-dev-skills/skills/bootstrap-swift-package/assets/github/repo-maintenance-workflows/validate-repo-maintenance.yml

@@ -1,5 +1,8 @@
 name: Validate Repo Maintenance
 
+# Branch protection should require the Actions check context `validate`.
+# GitHub exposes the job check run by this job name, not by the workflow title.
+
 on:
   pull_request:
   push:
@@ -8,6 +11,7 @@ on:
 
 jobs:
   validate:
+    name: validate
     runs-on: macos-latest
     steps:
       - uses: actions/checkout@v4

plugins/apple-dev-skills/skills/bootstrap-swift-package/references/automation-prompts.md

@@ -91,6 +91,7 @@ Verification:
 - Confirm `Package.swift` keeps the explicit Swift 6 language-mode declaration `swiftLanguageModes: [.v6]`.
 - Confirm `Package.swift` keeps `// swift-tools-version:` at `6.0` or newer, even if it is lowered from the scaffold default.
 - If validation is enabled, verify `swift build` and `swift test` success.
+- If branch protection is configured, require the GitHub Actions check context `validate`, not `Validate Repo Maintenance / validate`.
 
 Return contract:
 - `status: success|blocked|failed`
@@ -116,3 +117,4 @@ Return contract:
 - Stop if target exists and is non-empty.
 - Stop if script invocation fails at any step.
 - Never continue after failed validation unless `<SKIP_VALIDATION>` is explicitly `true`.
+- Do not configure protected branches to require the workflow-title display string `Validate Repo Maintenance / validate`.

plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/SKILL.md

@@ -63,6 +63,7 @@ Create a new native Apple app repository from nothing to a usable baseline on di
    - verify `AGENTS.md` exists when enabled
    - verify `scripts/repo-maintenance/hooks/pre-commit.sample` exists
    - verify `scripts/repo-maintenance/validate-all.sh` and `scripts/repo-maintenance/release.sh` exist
+   - verify branch protection, when enabled, requires the GitHub Actions check context `validate` rather than `Validate Repo Maintenance / validate`
    - if validation is enabled, verify project generation and basic project introspection succeeded
 9. Hand off existing-project work cleanly:
    - recommend `sync-xcode-project-guidance` when the repo guidance should be refreshed or merged after creation
@@ -128,6 +129,7 @@ Create a new native Apple app repository from nothing to a usable baseline on di
 - After a successful bootstrap, hand off to `sync-xcode-project-guidance` for repo-guidance alignment when needed, then to `xcode-build-run-workflow` for build, run, diagnostics, mutation, preview, and docs work.
 - After a successful bootstrap, hand off to `xcode-testing-workflow` for Swift Testing, XCTest, XCUITest, `.xctestplan`, and test diagnosis work.
 - After a successful bootstrap, use `scripts/repo-maintenance/validate-all.sh` for local maintainer validation and `scripts/repo-maintenance/release.sh` for releases.
+- After a successful bootstrap, configure protected branches to require `validate` for the managed repo-maintenance workflow; GitHub exposes that job check context directly rather than the workflow title plus job string.
 - Recommend `bootstrap-swift-package` directly when the task is really package bootstrap.
 - Recommend `sync-xcode-project-guidance` when the repo already exists and only needs repo-guidance or documentation alignment.
 

plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/assets/github/repo-maintenance-workflows/validate-repo-maintenance.yml

@@ -1,5 +1,8 @@
 name: Validate Repo Maintenance
 
+# Branch protection should require the Actions check context `validate`.
+# GitHub exposes the job check run by this job name, not by the workflow title.
+
 on:
   pull_request:
   push:
@@ -8,6 +11,7 @@ on:
 
 jobs:
   validate:
+    name: validate
     runs-on: macos-latest
     steps:
       - uses: actions/checkout@v4

plugins/apple-dev-skills/skills/bootstrap-xcode-app-project/references/automation-prompts.md

@@ -101,6 +101,7 @@ Constraints:
 Verification:
 - Confirm the expected scaffold files exist.
 - If validation is enabled, verify the supported project-generation path completed successfully.
+- If branch protection is configured, require the GitHub Actions check context `validate`, not `Validate Repo Maintenance / validate`.
 
 Return contract:
 - `status: success|blocked|failed`

plugins/apple-dev-skills/skills/sync-swift-package-guidance/SKILL.md

@@ -69,6 +69,7 @@ Bring an existing Swift package repository up to the expected guidance baseline
    - `scripts/repo-maintenance/validate-all.sh`
    - `scripts/repo-maintenance/sync-shared.sh`
    - `scripts/repo-maintenance/release.sh`
+   - protected branches, when configured, require the GitHub Actions check context `validate` rather than `Validate Repo Maintenance / validate`
 10. Hand off ongoing package work cleanly:
    - prefer `swift-package-build-run-workflow` or `swift-package-testing-workflow` for ordinary package work after guidance sync
    - recommend `xcode-build-run-workflow` or `xcode-testing-workflow` only when package work needs Xcode-managed SDK, toolchain, or test behavior
@@ -117,6 +118,7 @@ Bring an existing Swift package repository up to the expected guidance baseline
 - The only current fallback is a non-mutating dry-run or guided result that explains what the sync would do.
 - After a successful sync, use `swift-package-build-run-workflow` or `swift-package-testing-workflow` for ordinary package work by default.
 - After a successful sync, use `scripts/repo-maintenance/validate-all.sh` for local maintainer validation and `scripts/repo-maintenance/release.sh` for releases.
+- After a successful sync, configure protected branches to require `validate` for the managed repo-maintenance workflow; GitHub exposes that job check context directly rather than the workflow title plus job string.
 - Recommend `xcode-build-run-workflow` when package work needs Xcode-managed SDK or toolchain behavior.
 - Recommend `xcode-testing-workflow` when package work needs Xcode-managed test execution behavior.
 - Recommend `bootstrap-swift-package` when the repository still needs to be created from scratch.