ship-changes

name	ship-changes
description	Audit uncommitted changes for missing documentation updates, then commit, push, and open a pull request. Use when the user says "ship this", "commit and push", "open a PR", or any variation that means "wrap up the current working state into a published PR."

Ship changes

Wraps a tested working tree into a published PR. Three phases — audit, commit + push, open PR. Each phase has hard checks; if any fail, stop and report instead of pushing forward.

Phase 1 — audit the diff

Inspect what's about to ship and decide whether documentation needs to move with it.

1. Run the inspection commands in parallel (single tool message, multiple Bash calls):

   • git status — uncommitted files
   • git diff --stat — scope at a glance
   • git diff (and git diff --cached if there's staged content) — actual changes
   • git log -10 --oneline — recent commit-message style for this repo
   • git branch --show-current — branch you're shipping from

2. Refuse to proceed if:

   • Working tree is clean (nothing to ship — say so and stop).
   • Files that look sensitive are staged (.env, .env.* other than .env.sample, *credentials*, *.pem, *.key, anything matching **/secrets/**). Surface the path and ask the user before continuing. Note: INTERNAL_API_KEY and E2E_DATABASE_URL live in .env — never paste their values into commit messages, PR bodies, or the audit report; reference them by name only.
   • The diff edits generated/specs/**, plans/**, or generated/manifest.json directly. These are agent-owned (generator, planner) and npm run manifest; manual edits get overwritten on the next /regen. Tell the user; if the intent was a refresh, run /regen <stem> or /regen-all instead of committing the manual edit.
   • The diff edits src/env/anchors.*.json by hand. These are generated by npm run seed:anchors <env> and validated against the live API by npm run validate:anchors. Manual edits drift from reality and break CI. Tell the user; if the intent was a refresh, run npm run reset:e2e (or npm run seed:anchors e2e) and commit the regenerated JSON.

3. Generated-chain check — if any of the following paths are in the diff, run npm run typecheck && npm run check:all and confirm 0 issues before proceeding:

   • scenarios/**/*.md (excluding READMEs)
   • plans/**/*.plan.md
   • generated/specs/**
   • src/** (includes src/env/*, src/db/*, src/fixtures/*, src/global/* — anchor/wipe/cleanup chain typechecks through here)
   • scripts/authoring/validate-*.ts, scripts/specs/lint-generated.ts, scripts/specs/check-manifest.ts, scripts/specs/update-manifest.ts
   • config/playwright.config.ts
   • src/env/seed-manifest.*.json (validate:manifest is part of check:all and hits the live API — needs STAGING_API_URL/E2E_API_URL in .env; if the env isn't reachable, surface that and ask the user before skipping)

   If check:all fails with sourceHash drift or manifest out-of-sync, stop and tell the user to run /regen <stem> (or /regen-all if multiple stems are affected). Do not commit through a broken hash chain — CI will reject it anyway. If validate:manifest fails with a "run: npm run reset:e2e" message, tell the user — don't commit a broken manifest.

4. Documentation audit — walk the diff for these signals and report each finding:

   Signal in diff	Doc that probably needs updating
   New / changed action in src/actions/*.actions.ts	agents/coding-rules.md (action conventions); agents/selector-rules.md if it introduces a new page-object getter
   New / changed page object in src/pages/*.page.ts	agents/selector-rules.md (Linkby Quasar cookbook)
   New / changed named assertion in src/assertions/*.assertions.ts	agents/coding-rules.md §"Assertions"; mention in README.md only if it adds a new pattern (compound vs. inline)
   TestEnv union or env-URL keys changed in src/env/api-urls.ts or src/env/urls.ts	.env.sample, config/playwright.config.ts, .github/workflows/e2e.yml, TEST_DATA_STRATEGY.md, TEST_DATA_IMPLEMENTATION_PLAN.md
   New env var added or removed	.env.sample, .github/workflows/e2e.yml, README.md if user-visible
   New field in src/seed/manifest.types.ts (SeedManifest)	src/env/seed-manifest.e2e.json regenerated via npm run reset:e2e; src/seed/seeder.ts updated to write the new field; docs/seed.md if author-facing
   New entity type or default in src/seed/ (loader.ts, creators/*.ts, defaults.ts)	docs/seed.md schema reference; one example in scenarios/<name>/seed.yaml; mention in PR body if it changes auto-defaulting rules
   Schema list changed in src/db/wipe-runner.ts	TEST_DATA_STRATEGY.md (the four hard-coded schemas); scripts/local-env/setup-local-e2e-db.sh grants list; provisioning notes in TEST_DATA_IMPLEMENTATION_PLAN.md PR 4
   Change to scripts/seed/** (wipe-e2e.ts, seed-scenarios.ts, seed-lookups.sh, validate-manifest.ts, lookup-data.sql) or src/seed/**	docs/seed.md if author-facing; TEST_DATA_STRATEGY.md matching section; .env.sample if a new env var is read; ARCHITECTURE.md §"npm scripts" if the public CLI surface changes
   Change to scripts/local-env/setup-local-e2e-db.sh, scripts/local-env/start-local-e2e-api.sh	TEST_DATA_IMPLEMENTATION_PLAN.md PR 4 "Verified locally" block; README.md / QUICK_START.md local-dev section if user-visible
   New top-level folder under src/ (e.g. src/db/)	README.md repo-structure section, ARCHITECTURE.md §"Who edits what"
   New npm script in package.json	ARCHITECTURE.md §"npm scripts" cheatsheet
   New / changed slash command in .claude/commands/	ARCHITECTURE.md §"Slash commands" cheatsheet; README.md if user-visible
   New / changed subagent in .claude/agents/	ARCHITECTURE.md §"Who edits what"; verify agents/coding-rules.md / agents/selector-rules.md references stay accurate
   Validator rule added in scripts/authoring/validate-scenarios.ts or scripts/authoring/validate-plans.ts	scenarios/README.md "Common mistakes" table; README.md if author-facing
   Lint rule added in scripts/specs/lint-generated.ts	README.md §"Generated specs" discipline list; agents/coding-rules.md §"Spec format"
   New scenario in scenarios/	matching plan + spec must exist — run /regen <stem> if missing; generated/manifest.json regenerated
   New Owner: value introduced in a scenario	agents/owner-routing.json; ARCHITECTURE.md §"Owner field" if routing semantics change
   Test-data fixture change in src/fixtures/*.ts (test-data.fixture.ts, cleanup-ledger.ts, extract-ids-from-signup.ts) that affects lifecycle	TEST_DATA_STRATEGY.md (hygiene + factory section); scenario ## Data blocks if fixture fields changed; TEST_DATA_IMPLEMENTATION_PLAN.md PR 2 reframe if ledger semantics shift
   Cleanup / teardown change in src/global/*.ts (teardown.ts, cleanup-runner.ts) or scripts/cleanup/*.ts	TEST_DATA_STRATEGY.md "What's already shipped" / "Trade-offs"; TEST_DATA_IMPLEMENTATION_PLAN.md PR 2/3 reframe; ARCHITECTURE.md §"npm scripts" if cleanup:retry/cleanup:status surface changes
   New top-level doc file (*.md in repo root)	README.md and ARCHITECTURE.md links section; NEXT_STEPS.md if it captures deferred work
   package.json dep added	nothing required, but flag the new dep in the PR body
   CI workflow change in .github/workflows/	README.md, ARCHITECTURE.md §"CI pipeline"; TEST_DATA_IMPLEMENTATION_PLAN.md if it touches the test-data lifecycle

   For each finding, check whether the doc already reflects it — grep the doc for the changed identifier / config key / signature. If it does, note "doc already covers it" and move on. If it doesn't, stop and tell the user before committing. List the missing doc updates as a punch list; let the user decide whether to update them now, defer, or proceed without.

5. After reporting findings, ask the user for permission to proceed to Phase 2. Use AskUserQuestion with options:

   • Proceed (commit + push + PR as-is)
   • Update docs first (pause for the user to drive doc edits, then re-run)
   • Cancel

Phase 2 — commit + push

Only run after the user approves Phase 1.

1. Decide commit scope. Default to one commit per logical change; if the diff is cohesive, one commit is fine. If it bundles unrelated work (e.g. refactor + scenario addition + dep bump), ask whether to split.
2. Draft a commit message that matches git log style — recent commits in this repo use sentence-case imperative titles (e.g. "Inject REVIEW.md (from main) as Claude PR review prompt"), no conventional-commit prefix, with the body explaining the why. Title under 70 chars. Reference issues/PRs only when the user has already mentioned them — don't invent links.
3. Stage with explicit paths (git add path1 path2 …) — never git add -A or git add . (catches sensitive files and unrelated noise).
4. Commit using a HEREDOC so newlines survive:

   git commit -m "$(cat <<'EOF'
   <title>
   
   <body — wrapped at ~72 cols>
   
   EOF
   )"
   

5. If a pre-commit hook fails: fix the root cause, re-stage, and commit again as a new commit. Do not use --amend, --no-verify, or --no-gpg-sign unless the user explicitly asked for it.
6. Check the upstream:
   • git status -sb to see ahead/behind counts.
   • If the branch has no upstream, push with -u origin <branch>.
   • Otherwise plain git push.
7. If a git push is rejected (non-fast-forward, hook denial), stop and report — never force-push without explicit user instruction, and never force-push to main/master.

Phase 3 — open the PR

1. Check whether a PR already exists for this branch: gh pr view --json url,state 2>/dev/null (the command exits non-zero if no PR — that's fine).
   • If a PR exists and is open, push was enough. Print its URL and stop.
   • If a PR exists and is closed/merged, ask the user before opening a new one.
2. Otherwise, draft a PR body from the commits on this branch (not just the last commit):
   • git log <base>..HEAD --oneline and git diff <base>...HEAD where <base> is the default base (usually main).
   • Title: a single concise summary, ≤70 chars.
   • Body template:

     ## Summary
     - <1–3 bullets covering the user-visible change>
     
     ## Test plan
     - [ ] <tests / manual checks that verify this>
     
     🤖 Generated with [Claude Code](https://claude.com/claude-code)
     

3. Create the PR with gh pr create and a HEREDOC body:

   gh pr create --title "<title>" --body "$(cat <<'EOF'
   ## Summary
   - …
   
   ## Test plan
   - [ ] …
   
   🤖 Generated with [Claude Code](https://claude.com/claude-code)
   EOF
   )"
   

4. Print the PR URL the command returned. Done.

Non-negotiable safety rules

• Never run git push --force, git reset --hard, git checkout ., or similar destructive commands unless the user explicitly requested them in this conversation.
• Never modify .git/config or global git config.
• Never bypass hooks (--no-verify) or signing (--no-gpg-sign, -c commit.gpgsign=false) unless asked.
• Never commit files matching the sensitive-path patterns in Phase 1 step 2.
• Never directly edit + commit generated/specs/**, plans/**, or generated/manifest.json — these are agent-owned. Regenerate via /regen <stem> or /regen-all, then commit the regenerated artifacts.
• Never hand-edit + commit src/env/anchors.*.json — these are generated by npm run seed:anchors <env> against the live api-cf. Regenerate (e.g. npm run reset:e2e) and commit the resulting JSON.
• Never paste secret values (INTERNAL_API_KEY, DB passwords from E2E_DATABASE_URL, anchor-credential passwords) into commit messages, PR bodies, or audit reports. Reference them by env-var name only.
• If a hook fails twice in a row on the same change, stop and ask the user — don't keep guessing fixes.