@nlaprell/shipit 1.0.0

package/_system/behaviors/DO_RELEASE.md

@@ -0,0 +1,371 @@
+# Release Execution Guide
+
+**Purpose:** This document provides step-by-step instructions for executing a release after preparation is complete. Follow these steps in order, validating each step before proceeding.
+
+**When to use:** After completing all steps in `PREPARE_RELEASE.md`.
+
+## Scope and Safety
+
+- This document covers execution only (commit, tag, push, release).
+- Do NOT modify product/code files here. Only commit the release prep files.
+- If any step requires edits beyond release prep files, stop and report.
+- If you are not on the release branch, stop and switch to the correct branch.
+
+**Prerequisites:**
+
+- All preparation steps from `PREPARE_RELEASE.md` are complete
+- Version consistency verified across all files
+- All release preparation changes are ready to commit
+- No uncommitted changes except release preparation files
+
+## Release Version (required)
+
+- Define `VERSION=X.Y.Z` before starting.
+- Use this exact `VERSION` in all commands below.
+- If the version changes mid-process, stop and restart from Step 1.
+
+**Important:** This process will commit changes, create tags, push to GitHub, and create a GitHub release. Ensure you have proper permissions and are ready to publish.
+
+---
+
+## Step 1: Commit Release Preparation
+
+**Objective:** Commit all release preparation changes.
+
+**Actions:**
+
+1. Confirm correct branch: `git branch --show-current`
+   - **Verify:** You are on the intended release branch (usually `main` or `master`)
+2. Confirm only release prep files are modified: `git status --porcelain`
+   - **Verify:** Only `CHANGELOG.md`, `package.json`, `README.md` appear
+   - **If other files:** Stop and revert or stash unrelated changes
+3. Stage release prep files only:
+   - `git add CHANGELOG.md package.json README.md`
+4. Review staged changes: `git diff --cached`
+   - **Verify:** Only the release prep files are staged
+5. Commit with message: `git commit -m "chore: prepare release vX.Y.Z"`
+6. Verify commit: `git log -1 --stat`
+
+**Commit Message Format:**
+
+```
+chore: prepare release vX.Y.Z
+
+- Update CHANGELOG.md with vX.Y.Z changes
+- Bump version to X.Y.Z in package.json
+- Update README.md version badge and history
+```
+
+**Validation:**
+
+- All release prep files are committed
+- Commit message follows conventional commit format
+- No uncommitted changes remain
+- Commit is on correct branch (main/master)
+
+**Rule:** Release preparation commits should be separate from feature commits.
+
+**If validation fails:** Fix issues before proceeding. Do not create tag with uncommitted changes.
+
+**STOP GATE:** If any validation fails, stop and fix before moving to Step 2.
+
+---
+
+## Step 2: Create Git Tag
+
+**Objective:** Create an annotated git tag for the release.
+
+**Actions:**
+
+1. Confirm `VERSION` matches `package.json` before tagging
+2. Create annotated tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z: Brief description"`
+3. Verify tag: `git tag -l "v*" | tail -1`
+4. Show tag message: `git show vX.Y.Z`
+
+**Tag Message Format:**
+
+```
+Release vX.Y.Z: Brief Description
+
+Key highlights:
+- Feature 1
+- Feature 2
+- Improvement 1
+
+See CHANGELOG.md for full details.
+```
+
+**Tag Message Best Practices:**
+
+- Use the version section from CHANGELOG.md as reference
+- Include 2-4 key highlights
+- Reference CHANGELOG.md for full details
+- Keep it concise but informative
+
+**Validation:**
+
+- Tag name matches version (e.g., `v0.2.0`)
+- Tag is annotated (not lightweight) - verify with `git show vX.Y.Z` shows tag message
+- Tag message is descriptive and includes key highlights
+- Tag points to the commit just created (verify with `git log --oneline --decorate`)
+
+**Rule:** Always use annotated tags for releases (not lightweight tags). Use `-a` flag.
+
+**If validation fails:** Delete tag with `git tag -d vX.Y.Z`, fix issues, then recreate tag.
+
+**STOP GATE:** If tag validation fails, stop and fix before moving to Step 3.
+
+---
+
+## Step 3: Push to Remote
+
+**Objective:** Push commits and tags to GitHub.
+
+**Actions:**
+
+1. Determine branch name: `git branch --show-current`
+2. Push commits first: `git push origin <branch-name>`
+   - **Example:** `git push origin main`
+3. Verify commits pushed: Check GitHub repository
+4. Push tag: `git push origin vX.Y.Z`
+5. Verify tag pushed: Check GitHub tags page or releases page
+
+**Validation:**
+
+- Commits pushed successfully (no errors)
+- Tag pushed successfully (no errors)
+- Tag visible on GitHub releases/tags page
+- Tag points to correct commit on GitHub
+
+**Rule:** Push commits before tags to ensure tag references exist on remote.
+
+**If validation fails:**
+
+- If commit push fails: Fix branch/remote issues, then retry
+- If tag push fails: Verify tag exists locally, check remote permissions, then retry
+- Do not proceed to GitHub release until tag is visible on GitHub
+
+**STOP GATE:** If the tag is not visible on GitHub, stop and resolve before moving to Step 4.
+
+---
+
+## Step 4: Create GitHub Release
+
+**Objective:** Create a GitHub release with release notes. **This step is REQUIRED, not optional.**
+
+**Actions:**
+
+1. Navigate to GitHub repository releases page:
+   - URL format: `https://github.com/<owner>/<repo>/releases`
+   - Or: Repository → Releases → "Draft a new release"
+2. Click "Draft a new release" button
+3. Select tag: Choose `vX.Y.Z` from dropdown
+   - **Verify:** Tag exists and is correct version
+4. Set release title: `Release vX.Y.Z: Brief Description`
+   - Use same description from tag message
+5. Set release description:
+   - Copy entire version section from CHANGELOG.md
+   - Include all categories (Added, Changed, Fixed, Removed)
+   - Keep markdown formatting
+   - Add links to issues if applicable (e.g., `[#123](https://github.com/owner/repo/issues/123)`)
+6. Mark as "Latest release" checkbox:
+   - **Check this** if this is the newest release
+   - **Uncheck** if releasing an older version
+7. Click "Publish release" button
+8. Verify release is published:
+   - Release appears on releases page
+   - Release notes are complete
+   - Release is marked as latest (if checked)
+
+**Release Notes Format:**
+Copy the version section from CHANGELOG.md, for example:
+
+```markdown
+## [0.2.0] - 2026-01-27
+
+### Added
+
+- Intent validation and auto-fix (`/fix` command)
+- Output verification system with automatic generator chaining
+- Unified status dashboard (`/status` command)
+
+### Changed
+
+- Enhanced `/scope-project` with batched prompts
+- Enhanced `/generate-release-plan` with validation warnings
+
+### Fixed
+
+- Fixed numeric validation in dependency ordering checks
+- Fixed temp file cleanup in fix-intents.sh
+```
+
+**Validation:**
+
+- Release is published on GitHub (not draft)
+- Release notes are complete and accurate
+- Release notes match CHANGELOG.md version section
+- Release is marked as latest (if appropriate)
+- Release tag matches the tag that was pushed
+- Release is accessible via repository releases page
+
+**Rule:** GitHub release creation is MANDATORY. Do not skip this step.
+
+**If validation fails:**
+
+- If release creation fails: Check GitHub permissions, verify tag exists, then retry
+- If release notes are incomplete: Edit release and update notes
+- If release is draft: Click "Publish release" to make it public
+
+**STOP GATE:** If the release is not published and verified, stop and fix before final verification.
+
+---
+
+## Step 5: Publish to npm (optional)
+
+**Objective:** Publish the ShipIt CLI package to npm so users can install with `npm install -g @nlaprell/shipit`. Skip if not publishing to npm for this release.
+
+**Actions:**
+
+1. Ensure `package.json` version matches the release (e.g. `X.Y.Z` for tag `vX.Y.Z`).
+2. Run tests: `pnpm test && pnpm test:cli && pnpm test:shipit`.
+3. Preview: `npm pack` then inspect tarball if desired.
+4. Publish: `npm publish` (requires `npm login` and 2FA).
+5. Verify at https://www.npmjs.com/package/shipit.
+
+**If using CI:** A workflow may publish on release creation when `NODE_AUTH_TOKEN` (or `NPM_TOKEN`) is set. See `docs/PUBLISHING.md`.
+
+**Validation:**
+
+- Package version on npm matches GitHub release tag.
+- `npm install -g @nlaprell/shipit` works and `shipit --help` runs.
+
+---
+
+## Final Verification
+
+**Objective:** Verify the complete release process was successful.
+
+**Checklist:**
+
+- [ ] Release preparation commit created and pushed
+- [ ] Git tag created and pushed to GitHub
+- [ ] GitHub release created and published
+- [ ] (Optional) npm package published; version matches release
+- [ ] Release notes match CHANGELOG.md
+- [ ] Release is marked as latest (if appropriate)
+- [ ] Version badge on README.md links to correct release
+- [ ] All validation steps passed
+
+**Verification Commands:**
+
+```bash
+# Verify tag exists locally and remotely
+git tag -l "v*" | tail -1
+git ls-remote --tags origin | grep "vX.Y.Z"
+
+# Verify release commit
+git log --oneline -1
+git show HEAD --stat
+
+# Verify version consistency (should still match)
+CURRENT_VERSION=$(grep '"version"' package.json | cut -d'"' -f4)
+echo "Current version: $CURRENT_VERSION"
+```
+
+**Manual Verification:**
+
+1. Visit GitHub releases page: `https://github.com/<owner>/<repo>/releases`
+2. Verify release `vX.Y.Z` exists and is published
+3. Verify release notes are complete
+4. Verify README.md badge links to correct release
+5. Verify tag exists and points to correct commit
+
+**If any verification fails:** Fix issues immediately. If release was published incorrectly, you may need to:
+
+- Delete and recreate the GitHub release
+- Delete and recreate the tag (if necessary)
+- Fix any documentation issues
+
+---
+
+## Rules and Constraints
+
+### Mandatory Rules:
+
+1. **GitHub release is required** - Do not skip Step 4. Every release must have a GitHub release.
+2. **Tags must be annotated** - Always use `-a` flag when creating tags
+3. **Push commits before tags** - Ensure commits exist on remote before pushing tags
+4. **Release notes must match CHANGELOG.md** - Keep them synchronized
+5. **Verify before proceeding** - Validate each step before moving to next
+6. **No uncommitted changes** - All changes must be committed before tagging
+7. **No file edits in this phase** - Only commit the prepared files; do not modify other files
+
+### Best Practices:
+
+1. **Review before committing** - Review `git diff --cached` before committing
+2. **Descriptive tag messages** - Include key highlights in tag message
+3. **Complete release notes** - Copy full version section from CHANGELOG.md
+4. **Mark as latest** - Check "Latest release" if this is the newest version
+5. **Test tag locally** - Verify tag before pushing to remote
+
+### Error Handling:
+
+- **If commit fails:** Fix issues, then retry commit
+- **If tag creation fails:** Check for existing tag, delete if needed, then recreate
+- **If push fails:** Check remote permissions and branch protection rules
+- **If GitHub release fails:** Verify tag exists on GitHub, check permissions, then retry
+- **If any step fails:** Stop immediately, fix the issue, then restart from the failed step
+
+---
+
+## Quick Reference Checklist
+
+Use this checklist when executing a release:
+
+```
+[ ] Step 1: Commit release preparation
+[ ] Step 2: Create git tag (annotated)
+[ ] Step 3: Push commits and tag to GitHub
+[ ] Step 4: Create GitHub release (REQUIRED)
+[ ] Step 5: Publish to npm (optional)
+[ ] Final verification: All steps completed successfully
+```
+
+---
+
+## Automation Notes
+
+**For AI Agents:**
+
+- Execute steps sequentially
+- Validate each step before proceeding
+- Use provided validation commands
+- Stop on any error
+- Report progress clearly
+- Document any deviations
+- **Do not skip GitHub release creation** - it is mandatory
+
+**For Human Review:**
+
+- Review commit changes before committing
+- Verify tag message is appropriate
+- Check release notes match CHANGELOG.md
+- Confirm release is marked as latest (if appropriate)
+- Verify release is accessible on GitHub
+
+---
+
+## Post-Release Tasks
+
+After completing the release, consider:
+
+1. **Announce release** - Notify stakeholders if applicable
+2. **Update documentation** - Ensure all docs reference new version
+3. **Monitor issues** - Watch for any issues reported with new release
+4. **Plan next release** - Start tracking changes for next version in CHANGELOG.md [Unreleased]
+
+---
+
+**Last Updated:** 2026-01-27  
+**Version:** 1.0

package/_system/behaviors/DO_RELEASE_AI.md

@@ -0,0 +1,329 @@
+# AI Release Execution Guide
+
+**Purpose:** Deterministic, agent-safe execution flow for publishing a release. This is the AI-native alternative to `DO_RELEASE.md`.
+
+**When to use:** After completing all steps in `PREPARE_RELEASE_AI.md` (or `PREPARE_RELEASE.md`).
+
+## Scope and Safety
+
+- Execution only (commit, tag, push, release).
+- Do NOT modify product/code files here.
+- Only commit the release prep files: `CHANGELOG.md`, `package.json`, `README.md`.
+- Execute steps sequentially. Stop on any failure.
+- Require explicit user approval to proceed (from the prep summary handoff).
+
+---
+
+## Confirmation (required)
+
+**Objective:** Ensure the user explicitly approves execution.
+
+**Check:**
+
+- The user responded "yes" (or equivalent) to the prep handoff question.
+
+**STOP GATE:** If approval is missing or ambiguous, stop and ask for confirmation.
+
+---
+
+## Step 0.5: Carry-Forward Summary (required)
+
+**Objective:** Anchor execution to the prep summary for auditability.
+
+**Record (copy from prep summary):**
+
+```
+Release Status: READY | BLOCKED
+Version: X.Y.Z
+Prepared by: <agent or user>
+Notes: <short status note>
+Approval: <yes/no + who approved>
+```
+
+**STOP GATE:** If any field is missing, stop and request the missing detail.
+
+---
+
+## Step 0: Preflight Gate (single command)
+
+**Objective:** Fail fast if prereqs are not met.
+
+**Command:**
+
+```bash
+BRANCH=$(git branch --show-current)
+STATUS=$(git status --porcelain)
+echo "$BRANCH"
+echo "$STATUS"
+
+# Fail if not on intended release branch
+if [ "$BRANCH" != "main" ] && [ "$BRANCH" != "master" ]; then
+  echo "✗ Wrong branch: $BRANCH"
+  exit 1
+fi
+
+# Fail if any file other than allowed prep files is modified
+ALLOWED="CHANGELOG.md|package.json|README.md"
+if echo "$STATUS" | grep -vE "^[ MADRCU?!]{1,2} ($ALLOWED)$" >/dev/null; then
+  echo "✗ Non-release-prep files modified"
+  echo "$STATUS"
+  exit 1
+fi
+```
+
+**Validation:**
+
+- Branch is the intended release branch (usually `main` or `master`).
+- Only release prep files appear in status.
+- User explicitly approved execution after prep summary.
+
+**STOP GATE:** If any validation fails, stop and report.
+
+---
+
+## Step 1: Lock VERSION
+
+**Objective:** Use one version string for the entire execution.
+
+**Actions:**
+
+1. Set `VERSION=X.Y.Z` and export it.
+2. Validate it matches `package.json`.
+
+**Command:**
+
+```bash
+export VERSION="X.Y.Z"
+CURRENT_VERSION=$(grep '"version"' package.json | cut -d'"' -f4)
+if [ "$VERSION" != "$CURRENT_VERSION" ]; then
+  echo "✗ VERSION mismatch: package.json=$CURRENT_VERSION, VERSION=$VERSION"
+  exit 1
+fi
+```
+
+**STOP GATE:** If `VERSION` does not match `package.json`, stop.
+
+---
+
+## Step 2: Commit Release Preparation
+
+**Objective:** Commit only the release prep changes.
+
+**Commands:**
+
+```bash
+git add CHANGELOG.md package.json README.md
+git diff --cached
+
+# Fail if staged files include anything else
+if git diff --cached --name-only | grep -vE "^(CHANGELOG.md|package.json|README.md)$" >/dev/null; then
+  echo "✗ Staged non-release-prep files"
+  git diff --cached --name-only
+  exit 1
+fi
+
+git commit -m "chore: prepare release v$VERSION" \
+  -m "- Update CHANGELOG.md with v$VERSION changes" \
+  -m "- Bump version to $VERSION in package.json" \
+  -m "- Update README.md version badge and history"
+git log -1 --stat
+```
+
+**Validation:**
+
+- Only prep files are staged and committed.
+- Commit message follows the required format.
+
+**STOP GATE:** If validation fails, stop and fix.
+
+---
+
+## Step 3: Create Annotated Tag
+
+**Objective:** Create a descriptive annotated tag.
+
+**Actions:**
+
+1. Extract 2–4 highlights from the `CHANGELOG.md` section for `VERSION`.
+2. Create an annotated tag using those highlights.
+
+**Extraction (deterministic):**
+
+```bash
+# Pull first 4 bullet lines from the VERSION section (any category)
+HIGHLIGHTS=$(awk -v v="## [$VERSION]" '
+  $0 ~ v {in=1; next}
+  in && /^## \\[/ {exit}
+  in && /^- / {print; c++}
+  c==4 {exit}
+' CHANGELOG.md)
+```
+
+**Command (template):**
+
+```bash
+git tag -a "v$VERSION" -m "Release v$VERSION: <Brief Description>" \
+  -m "Key highlights:" \
+  -m "$(echo "$HIGHLIGHTS" | sed -n '1p')" \
+  -m "$(echo "$HIGHLIGHTS" | sed -n '2p')" \
+  -m "$(echo "$HIGHLIGHTS" | sed -n '3p')" \
+  -m "" \
+  -m "See CHANGELOG.md for full details."
+git tag -l "v*" | tail -1
+git show "v$VERSION"
+```
+
+**STOP GATE:** If tag is not annotated or does not point at the commit just created, stop and fix.
+
+---
+
+## Step 4: Push Commit and Tag
+
+**Objective:** Push to GitHub in correct order.
+
+**Commands:**
+
+```bash
+BRANCH=$(git branch --show-current)
+git push origin "$BRANCH"
+git push origin "v$VERSION"
+```
+
+**STOP GATE:** If either push fails, stop and resolve before proceeding.
+
+---
+
+## Step 5: Create GitHub Release (CLI)
+
+**Objective:** Publish the release using the exact changelog section.
+
+**Actions:**
+
+1. Extract the `CHANGELOG.md` section for `VERSION` into a temporary notes file.
+2. Use `gh release create` with the notes file to avoid shell expansion.
+
+**Commands (safe):**
+
+```bash
+# Extract the exact VERSION section into a notes file
+awk -v v="## [$VERSION]" '
+  $0 ~ v {in=1}
+  in {print}
+  in && /^## \\[/ && $0 !~ v {exit}
+' CHANGELOG.md > "/tmp/release_notes_$VERSION.md"
+
+gh release create "v$VERSION" \
+  --title "Release v$VERSION: <Brief Description>" \
+  --notes-file "/tmp/release_notes_$VERSION.md"
+```
+
+**STOP GATE:** If the release is not published or notes are incomplete, stop and fix.
+
+---
+
+## Step 5.5: Idempotency Guard
+
+**Objective:** Prevent collisions if a tag or release already exists.
+
+**Commands:**
+
+```bash
+if git rev-parse "v$VERSION" >/dev/null 2>&1; then
+  echo "✗ Tag v$VERSION already exists"
+  exit 1
+fi
+
+if gh release view "v$VERSION" >/dev/null 2>&1; then
+  echo "✗ GitHub release v$VERSION already exists"
+  exit 1
+fi
+```
+
+**STOP GATE:** If either exists, stop and decide whether to delete/recreate or abort.
+
+---
+
+## Step 6: Verification Bundle
+
+**Objective:** Verify release integrity end-to-end.
+
+**Commands:**
+
+```bash
+git tag -l "v*" | tail -1
+git ls-remote --tags origin | grep "v$VERSION"
+git log --oneline -1
+git show HEAD --stat
+gh release view "v$VERSION" --json name,tagName,url,isDraft,isPrerelease,publishedAt
+```
+
+**Validation:**
+
+- Tag exists locally and on remote.
+- GitHub release is published (not draft).
+- Release notes match the `CHANGELOG.md` section for `VERSION`.
+
+**STOP GATE:** If any check fails, stop and resolve before proceeding.
+
+---
+
+## Rollback (if needed)
+
+**Objective:** Provide a clean recovery path if a release was created incorrectly.
+
+**Commands:**
+
+```bash
+# Delete GitHub release (if created)
+gh release delete "v$VERSION" --yes
+
+# Delete local and remote tag
+git tag -d "v$VERSION"
+git push origin ":refs/tags/v$VERSION"
+```
+
+**STOP GATE:** After rollback, restart from Step 0.
+
+---
+
+## Step 7: Stop and Summarize (final step)
+
+**Objective:** End execution cleanly and report status.
+
+**Report Template (fill in):**
+
+```
+[x] Release prep commit created and pushed
+[x] Annotated tag vX.Y.Z created and pushed
+[x] GitHub release published
+[x] Release notes match CHANGELOG.md
+[x] All validation checks passed
+```
+
+**STOP GATE:** Do not proceed to any other steps here.
+
+---
+
+## Agent Output Guidance (recommended)
+
+**Objective:** Make the agent's logs easy to scan for humans.
+
+**Per-step output format:**
+
+```
+Step X: <Name>
+- Status: PASS | FAIL
+- Evidence: <command or artifact>
+- Notes: <short reason or error>
+```
+
+**Final summary (always print):**
+
+```
+Release Execution Summary
+- Version: X.Y.Z
+- Commit: <sha>
+- Tag: vX.Y.Z
+- Release URL: <url>
+- Gates passed: <count>/<count>
+```