Add guarded SPI add-package automation

AGENTS.md

@@ -15,6 +15,7 @@ Use this file for durable repo-local guidance that Codex should follow before ch
 
 - Start with [README.md](./README.md), [CONTRIBUTING.md](./CONTRIBUTING.md), [ROADMAP.md](./ROADMAP.md), [`docs/maintainers/subtree-workflow.md`](./docs/maintainers/subtree-workflow.md), and [`docs/maintainers/release-modes.md`](./docs/maintainers/release-modes.md).
 - Use [`docs/maintainers/plugin-packaging-strategy.md`](./docs/maintainers/plugin-packaging-strategy.md) when the question is about the root marketplace or the independent-plugin packaging stance.
+- Use [`docs/maintainers/spi-add-package-automation-plan.md`](./docs/maintainers/spi-add-package-automation-plan.md) for Swift Package Index readiness, submission, and add-package automation.
 - When a task is really about one child repo's own behavior, read that child repo's docs before reading broadly across the superproject.
 
 ## Working Rules
@@ -51,6 +52,9 @@ Use this file for durable repo-local guidance that Codex should follow before ch
 - Keep the same names for the same concepts across `SKILL.md`, `agents/openai.yaml`, docs, automation prompts, scripts, and marketplace metadata.
 - If docs and scripts disagree, fix the script or narrow the documented contract so they match.
 - When shipped behavior, active skill inventory, packaging roots, or validation commands change, update the relevant docs and `ROADMAP.md` in the same pass unless Gale explicitly says not to.
+- For Swift Package Index work, treat repo-local readiness and external submission as different states. Use [`scripts/spi_add_package.py`](./scripts/spi_add_package.py) for readiness, official issue-form URL generation, browser opening, and hands-free Computer Use handoff. Do not create `SwiftPackageIndex/PackageList` issues with `gh issue create`, do not apply labels manually, do not fork or clone `SwiftPackageIndex/PackageList`, do not edit `packages.json`, do not open PackageList pull requests, and do not trigger PackageList validation or CLA automation through a manual contribution path. The only supported external add-package path is the documented `Add Package(s)` issue form.
+- For hands-free SPI submission, use Codex Computer Use against Zen (`app.zen-browser.zen`) only after `scripts/spi_add_package.py hands-free <package-root>` opens the prefilled official issue form and prints its handoff. Computer Use may confirm the form, confirm the package URL, click GitHub's `Submit new issue` button, and verify the created issue has the `Add Package` label. If any check fails, stop and report the failure instead of improvising another GitHub action.
+- Say `SPI-ready locally`, `SPI Add Package issue submitted`, or `indexed on SPI` only when that exact state has been verified. A blocked issue, missing label, open PackageList PR, or failed external artifact is not successful SPI setup or successful SPI submission.
 - Default user-facing plugin install and update guidance to Git-backed marketplace sources with `codex plugin marketplace add <owner>/<repo>` and `codex plugin marketplace upgrade <marketplace-name>`. Use explicit refs such as `<owner>/<repo>@vX.Y.Z` only for pinned reproducible installs, and use manual local marketplace roots only for development, unpublished testing, or fallback cases.
 - For Python-backed repositories in `socket`, use `uv` as the maintainer baseline and declare repo-local dev dependencies in `pyproject.toml` instead of relying on globally installed tools.
 - Prefer a root or package-local dev group that explicitly includes the Python maintainer tools the repo expects to run, including `pytest`, `ruff`, and `mypy` when those checks are part of the workflow.

ROADMAP.md

@@ -147,6 +147,7 @@ In Progress
 ## Backlog Candidates
 
 - [x] [#35](https://github.com/gaelic-ghost/socket/issues/35) / [#37](https://github.com/gaelic-ghost/socket/issues/37): Harden release and PR scripts around delayed GitHub state. Fold the duplicate timing reports into one implementation pass that reviews CI check registration, PR comment/review reads, remote branch/tag visibility, GitHub release visibility, timeout configuration, logs, and tests across `socket` and the reusable `maintain-project-repo` release assets.
+- [x] [#39](https://github.com/gaelic-ghost/socket/issues/39): Add a Swift Package Index add-package gate and one-shot script so agents use only the documented `SwiftPackageIndex/PackageList` Add Package issue form, with Zen plus Codex Computer Use as the hands-free browser path.
 
 ## History
 

docs/maintainers/spi-add-package-automation-plan.md

@@ -0,0 +1,133 @@
+# Swift Package Index Add-Package Automation Plan
+
+## Purpose
+
+This document records the Socket-level guardrail for adding Swift packages to Swift Package Index.
+
+The real job is to make the valid SPI path boring and impossible to improvise around. SPI submission uses the documented `SwiftPackageIndex/PackageList` `Add Package(s)` issue form. Socket agents must not replace that form with GitHub CLI issue creation, manual labels, PackageList forks, `packages.json` edits, PackageList pull requests, or any other contribution path.
+
+## Failure Mode To Prevent
+
+The SwiftASB SPI attempt failed because an agent treated SPI readiness and SPI submission as if they were the same job, then improvised around the documented form path.
+
+The concrete bad sequence was:
+
+1. Create a `SwiftPackageIndex/PackageList` issue with `gh issue create`.
+2. Try to attach the `Add Package` label without permission.
+3. Observe that SPI automation did not run.
+4. Fork `SwiftPackageIndex/PackageList`.
+5. Edit `packages.json`.
+6. Open a PackageList pull request.
+7. Trigger external validation and CLA automation.
+8. Describe the package as SPI set up even though it was not indexed.
+
+None of those steps are acceptable as the default SPI submission path.
+
+## Source-Of-Truth Process
+
+The single documented add-package path is:
+
+1. Confirm the package satisfies SPI requirements.
+2. Open the official `Add Package(s)` issue form:
+   <https://github.com/SwiftPackageIndex/PackageList/issues/new?template=add_package.yml>
+3. Put one public GitHub package URL per line in the `New Packages` field.
+4. Submit the issue through the form.
+5. Let SPI's own automation create whatever PackageList follow-up it owns.
+
+Socket tooling may inspect the public issue form definition before opening it. Socket tooling may not create or mutate any PackageList labels, forks, branches, files, or pull requests.
+
+## One-Shot Script Contract
+
+The script lives at:
+
+```bash
+scripts/spi_add_package.py
+```
+
+The intended one-shot command for a package checkout is:
+
+```bash
+uv run /Users/galew/Workspace/gaelic-ghost/socket/scripts/spi_add_package.py hands-free /path/to/package
+```
+
+The script performs these repo-local checks before any browser action:
+
+- `Package.swift` exists at the package root.
+- `Package.swift` declares Swift tools version 5.0 or later.
+- The package remote resolves to a public GitHub HTTPS `.git` URL.
+- At least one semantic-version tag exists locally and is visible on the public GitHub remote.
+- `swift package dump-package` succeeds, emits parseable JSON, and includes at least one product.
+- `swift build` succeeds unless explicitly skipped.
+- `swift test` succeeds unless explicitly skipped.
+- The package is not already indexed on SPI when the indexed-state check is available.
+
+The script then fetches the live `SwiftPackageIndex/PackageList` issue form and refuses to continue unless it still contains:
+
+- form name `Add Package(s)`
+- default title `Add <Package>`
+- default label `Add Package`
+- required `New Packages` field with id `list`
+
+If the form shape changes, the script stops. It must not invent a replacement submission path.
+
+Browser-opening modes require complete readiness and the live form-shape check. Skip flags are allowed only for `readiness` and `url` diagnostic runs. They are rejected for `open` and `hands-free`.
+
+## Modes
+
+`readiness`
+
+Runs local readiness and form-shape checks. It prints the official issue-form URL but does not open a browser.
+
+`url`
+
+Same checks as `readiness`; the important output is the prefilled official issue-form URL.
+
+`open`
+
+Runs checks, then opens the prefilled official issue form in the configured browser. The default browser target is Zen by bundle id:
+
+```text
+app.zen-browser.zen
+```
+
+`hands-free`
+
+Runs checks, opens the prefilled official issue form in Zen, and prints a Codex Computer Use handoff. The handoff is the only permitted browser automation plan:
+
+1. Use Computer Use against `app.zen-browser.zen`.
+2. Confirm the page is the `SwiftPackageIndex/PackageList` `Add Package(s)` issue form.
+3. Confirm the `New Packages` field contains the package URL exactly once.
+4. Click GitHub's `Submit new issue` button.
+5. Verify the created issue has the `Add Package` label and report the issue URL.
+
+If any of those checks fail, stop and report the failure. Do not recover by creating labels, editing the issue through an API, creating a fork, or opening a PR.
+
+## Forbidden Actions
+
+The script and any agent using it must not:
+
+- run `gh issue create` against `SwiftPackageIndex/PackageList`
+- add or edit PackageList labels
+- fork `SwiftPackageIndex/PackageList`
+- clone `SwiftPackageIndex/PackageList`
+- edit `packages.json`
+- create or push PackageList branches
+- open PackageList pull requests
+- trigger PackageList validation or CLA automation through a manual contribution path
+- call a blocked PackageList issue or PR a successful SPI submission
+
+## Success Language
+
+Use exact state language:
+
+- `SPI-ready locally`: readiness checks passed, but no external SPI issue has been submitted.
+- `SPI Add Package issue submitted`: the official issue form was submitted and the created issue has the `Add Package` label.
+- `indexed on SPI`: the package page exists on `swiftpackageindex.com`.
+
+Do not say `submitted`, `set up`, or `indexed` unless the corresponding external state has actually been verified.
+
+## Future Skill Integration
+
+Milestone 39 in `plugins/apple-dev-skills/ROADMAP.md` should treat this script contract as the implementation model for the planned Swift Package Index workflow skill.
+
+The eventual skill should call or re-export this script instead of restating the process in prose. If the script and skill disagree, the script is the safer operating surface until the skill is corrected.

plugins/SpeakSwiftlyServer/docs/maintainers/docc-spi-hosting-plan.md

@@ -104,5 +104,5 @@ Immediate CI expectations:
 2. Land the first `.docc` catalog and symbol-doc pass.
 3. Add any CI or local build check needed to keep docs generation honest.
 4. Add the short tutorial-style walkthrough if the hosted docs still need a clearer first-use path.
-5. Submit the package to Swift Package Index.
+5. Submit the package to Swift Package Index only through Socket's `scripts/spi_add_package.py` flow or the equivalent official `SwiftPackageIndex/PackageList` Add Package issue form.
 6. Review the resulting hosted docs and compatibility pages, then tighten wording or navigation based on what SPI actually renders.

plugins/SpeakSwiftlyServer/docs/releases/v3.1.1-release-and-spi-checklist.md

@@ -103,10 +103,13 @@ Once `v3.1.1` is pushed and the GitHub release exists:
 
 1. Submit the repository through the Swift Package Index add-package flow using the repository URL with the `.git` suffix:
    `https://github.com/gaelic-ghost/SpeakSwiftlyServer.git`
+   Prefer Socket's guarded script so the only external action is the official Add Package issue form:
+   `uv run /Users/galew/Workspace/gaelic-ghost/socket/scripts/spi_add_package.py hands-free /path/to/SpeakSwiftlyServer`
 2. Wait for the package page and the first build results to appear.
 3. Verify that the hosted documentation build picks up the `SpeakSwiftlyServer` DocC catalog cleanly.
 4. Review the rendered package page for README presentation, release notes, compatibility results, and hosted-doc navigation.
-5. Once the package page exists, use the maintainership flow on Swift Package Index to claim the package and then add the generated compatibility badges back into `README.md` if they look worth keeping.
+5. Once the package page exists, use the maintainership flow on Swift Package Index to claim the package.
+6. If adding badges, copy the Swift-version and platform compatibility badge Markdown generated by SPI's maintainer page, place it with the existing README badge preamble, and verify the rendered README afterward.
 
 ## Post-Submission Follow-Through
 

plugins/agent-plugin-skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-plugin-skills",
-  "version": "6.4.0",
+  "version": "6.4.1",
   "description": "Installable maintainer skills for skills-export repositories.",
   "author": {
     "name": "Gale",

plugins/agent-plugin-skills/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-plugin-skills-maintenance"
-version = "6.4.0"
+version = "6.4.1"
 description = "Maintainer-only Python tooling baseline for agent-plugin-skills."
 requires-python = ">=3.11"
 dependencies = []

plugins/apple-dev-skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "apple-dev-skills",
-  "version": "6.4.0",
+  "version": "6.4.1",
   "description": "Apple development workflows for Codex and Claude Code, including SwiftUI architecture and DocC authoring guidance.",
   "author": {
     "name": "Gale",

plugins/apple-dev-skills/ROADMAP.md

@@ -305,14 +305,17 @@ Planned
 ### Scope
 
 - [ ] Add a dedicated Swift Package Index workflow skill for package distribution, documentation hosting, build readiness, metadata, and submission or listing expectations.
-- [ ] Cover the parts of SPI work that matter to maintainers shipping public Swift packages, including documentation hosting, build compatibility, supported platform metadata, README and package-surface expectations, and listing hygiene.
+- [ ] Cover the parts of SPI work that matter to maintainers shipping public Swift packages, including documentation hosting, build compatibility, supported platform metadata, README compatibility badges, package-surface expectations, and listing hygiene.
 
 ### Tickets
 
 - [ ] Define the skill boundary so it owns SPI-specific distribution and hosting guidance without replacing the core Swift package build or testing workflows.
 - [x] Gather the relevant Swift Package Index documentation for package metadata, documentation hosting, build surfaces, listing or submission expectations, and compatibility signals.
 - [ ] Ship a workflow surface that can help maintainers prepare a package for SPI, diagnose common SPI-facing build or docs issues, and understand what SPI is deriving from the repository.
+- [ ] Integrate the Socket `scripts/spi_add_package.py` one-shot readiness, issue-form, Zen, and Codex Computer Use handoff contract into the workflow.
+- [ ] Explicitly forbid non-form PackageList actions, including `gh issue create`, manual label edits, PackageList forks, `packages.json` edits, PackageList branches, PackageList PRs, and CLA-triggering contribution paths.
 - [ ] Cover the relationship between SPI docs hosting, DocC output, README quality, package metadata, and supported platform declarations.
+- [ ] Document the post-indexing badge workflow for copying SPI-generated shields.io Swift-version and platform compatibility badges into README preambles.
 - [ ] Document common SPI failure modes such as unsupported package structure, incomplete metadata, broken docs generation, or platform mismatch signals.
 - [ ] Add tests and maintainer docs once the workflow shape is stable.