ship-toolbox git:20260906.9af3950A

Immutable. This exact content never changes and is served at /api/v1/blob/410b20b68aef14e7.

---
name: ship-toolbox
description: "Use only when explicitly invoked as $ship-toolbox to validate and publish task-scoped toolbox changes, then refresh the local marketplace."
---

# Ship Toolbox

Ship one completed toolbox change from the synchronized `main` branch through
validation, an explicit scoped commit, remote verification, relevant CI, local
setup, and installed-state verification. Treat invocation as authorization for
this task-scoped sequence only.

## Boundaries

- Operate only in the `jialuohu/codex-toolbox` repository identified by
  `CODEX_TOOLBOX_ROOT`, its Git root, and its `origin` remote.
- Use `main` with upstream `origin/main`. Do not create or switch branches,
  pull requests, tags, or releases.
- Do not rebase, amend, force-push, reset, revert automatically, or rewrite
  published history.
- Never stage unrelated work. Never use `git add .` or `git add -A`.
- Never commit secrets, OAuth state, API keys, credentials, environment-file
  contents, generated runtime state, or private paths.
- Stop when scope, repository identity, ownership of a change, or recovery
  state is ambiguous.

## 1. Establish Repository and Recovery State

1. Resolve the Git root and confirm the normalized `origin` is exactly
   `jialuohu/codex-toolbox`.
2. Confirm the current branch is exactly `main` and its upstream is
   `origin/main`.
3. Fetch `origin/main`, then inspect ahead/behind counts with
   `git rev-list --left-right --count origin/main...HEAD`.
4. Stop if `main` is behind or diverged. Do not pull, merge, or rebase.
5. Require synchronized `main` for a new release. Permit an ahead-only state
   solely as push-failure recovery when every unpushed commit is clearly part
   of the active task; otherwise stop.
6. Inspect status plus staged and unstaged diffs. Derive an explicit
   task-scoped path and hunk list from the active request. Preserve clearly
   unrelated changes unstaged; stop for ambiguous mixed changes or overlapping
   hunks.

## 2. Validate the Exact Release Scope

Run all repository gates before a new commit:

1. Parse marketplace, plugin, MCP, and other changed JSON files.
2. Run `git diff --check` and shell syntax checks for changed shell scripts.
3. Run `python3 scripts/check-codex-toolbox-setup.py`.
4. Run `scripts/privacy-audit.sh current`.
5. Run the affected plugin's validators, unit tests, contract tests, and
   integration tests when present.
6. Run the full repository suite with
   `python3 -m unittest discover -s tests`.

When unrelated worktree changes exist, stage only the task-scoped paths and
hunks first, export the index to a temporary Git-backed snapshot, and run gates
that would otherwise observe the dirty worktree against that exact snapshot.
Do not weaken a gate because an unrelated change makes the working tree fail.
Do not push when any required gate fails.

## 3. Stage, Review, Commit, and Push

1. Stage only explicit paths with `git add -- <path>...`. Use interactive hunk
   staging for a shared file when needed.
2. Review `git diff --cached --name-status`, the staged diff, and
   `git diff --cached --check`. Confirm every staged hunk belongs to the task.
3. Derive a concise Conventional Commit message from the staged intent.
4. If the staged diff is non-empty, commit and run `git push origin main`
   without requesting another confirmation; explicit invocation already
   authorizes these task-scoped actions.
5. Verify `git rev-parse HEAD` exactly matches `git ls-remote origin
   refs/heads/main`.

If there is no staged change, do not create an empty commit. When local and
remote `main` already match, continue directly to refresh verification. In an
approved push-failure recovery state, push the existing verified commit rather
than creating another commit.

## 4. Require Remote Evidence

- Locate relevant GitHub Actions runs for the pushed SHA when `gh` is
  authenticated and applicable workflows exist.
- Wait for the relevant runs to complete. Continue only after they succeed.
- If CI fails, report the commit SHA, run URL, failing job, and available log
  evidence. Stop before local refresh; do not revert or rewrite the push.
- If no relevant workflow exists, state that explicitly and continue without
  claiming CI passed.

## 5. Refresh and Verify Locally

1. Run `scripts/setup-codex-toolbox.sh` from the committed tree. If unrelated
   worktree changes remain, use a clean export of `HEAD` so they cannot enter
   local configuration.
2. Verify `codex plugin marketplace list --json` reports
   `jialuo-codex-toolbox` with `sourceType` equal to `git`, source
   `https://github.com/jialuohu/codex-toolbox.git`, and ref `main` when shown.
3. Verify `codex plugin list --marketplace jialuo-codex-toolbox --json` reports
   every affected plugin installed, enabled, and at its expected version.
4. Verify newly added skill files exist under the installed plugin source.
5. Require `codex mcp list` to succeed. If third-party marketplace management
   changed, verify those marketplace plugin lists too.

Do not remove a live runtime lock or terminate an active service to force setup.
Ask the user to close the owning task, then rerun setup from the same committed
SHA.

## Failure and Reinvocation Scenarios

- **Wrong branch:** Stop without staging, committing, pushing, or refreshing.
- **Behind or diverged:** Stop and report the counts; never repair history
  automatically.
- **Ambiguous mixed changes:** Stop and request an exact scope. Keep unrelated
  paths and hunks unstaged.
- **No-change refresh:** When `HEAD` equals `origin/main`, skip commit and push,
  then rerun setup and installed-state verification.
- **Push failed:** Keep the local commit. On reinvocation, validate and push
  that same ahead-only commit without an empty follow-up commit.
- **CI failed:** Report the published SHA and failure, withhold setup, and
  resume from CI verification after a task-scoped fix is published.
- **Post-push setup failed:** Report remote and CI success separately from the
  incomplete local refresh. On reinvocation, rerun setup and verification for
  the same SHA without committing again.
- **Privacy or test gate failed:** Stop before commit and identify the failing
  gate without bypassing it.

## Completion Receipt

Report the commit subject and SHA, push target, remote-SHA match, relevant CI
result and URL, setup result, affected installed plugin versions, Git-backed
marketplace evidence, MCP-list result, and any preserved unrelated changes or
remaining uncertainty.