claude-code-workflow 7.2.27 → 7.2.28

package/.codex/skills/ship/phases/02-code-review.md

@@ -0,0 +1,228 @@
+# Phase 2: Code Review
+
+> **COMPACT PROTECTION**: This is a core execution phase. If context compression has occurred and this file is only a summary, **MUST `Read` this file again before executing any Step**. Do not execute from memory.
+
+Automated AI-powered code review of changes since the base branch, with risk assessment.
+
+## Objective
+
+- Detect the merge base between current branch and target branch
+- Generate diff for review
+- Assess high-risk indicators before AI review
+- Run AI-powered code review via inline subagent
+- Flag high-risk changes (large diffs, sensitive files, breaking changes)
+
+## Input
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| Phase 1 gate result | Yes | overall: "pass" — must have passed |
+| Repository git history | Yes | Commit log, diff data |
+
+## Execution Steps
+
+### Step 1: Detect Merge Base
+
+Determine the target branch and find the common ancestor commit.
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| origin/main exists | Use main as target branch |
+| origin/main not found | Fall back to master as target branch |
+| Current branch is main or master | Use last tag as merge base |
+| Current branch is main/master and no tags exist | Use initial commit as merge base |
+| Current branch is feature branch | Use `git merge-base origin/<target> HEAD` |
+
+```bash
+# Determine target branch (default: main, fallback: master)
+target_branch="main"
+if ! git rev-parse --verify "origin/$target_branch" &>/dev/null; then
+  target_branch="master"
+fi
+
+# Find merge base
+merge_base=$(git merge-base "origin/$target_branch" HEAD)
+echo "Merge base: $merge_base"
+
+# If on main/master directly, compare against last tag
+current_branch=$(git branch --show-current)
+if [ "$current_branch" = "main" ] || [ "$current_branch" = "master" ]; then
+  last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+  if [ -n "$last_tag" ]; then
+    merge_base="$last_tag"
+    echo "On main — using last tag as base: $last_tag"
+  else
+    # Use first commit if no tags exist
+    merge_base=$(git rev-list --max-parents=0 HEAD | head -1)
+    echo "No tags found — using initial commit as base"
+  fi
+fi
+```
+
+---
+
+### Step 2: Generate Diff Summary
+
+Collect statistics and full diff content.
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| Diff command succeeds | Record files_changed, lines_added, lines_removed |
+| No changes found | WARN — nothing to review; ask user whether to proceed |
+
+```bash
+# File-level summary
+git diff --stat "$merge_base"...HEAD
+
+# Full diff for review
+git diff "$merge_base"...HEAD > /tmp/ship-review-diff.txt
+
+# Count changes for risk assessment
+files_changed=$(git diff --name-only "$merge_base"...HEAD | wc -l)
+lines_added=$(git diff --numstat "$merge_base"...HEAD | awk '{s+=$1} END {print s}')
+lines_removed=$(git diff --numstat "$merge_base"...HEAD | awk '{s+=$2} END {print s}')
+```
+
+---
+
+### Step 3: Risk Assessment
+
+Flag high-risk indicators before AI review.
+
+**Risk Factor Table**:
+
+| Risk Factor | Threshold | Risk Level |
+|-------------|-----------|------------|
+| Files changed | > 50 | High |
+| Lines changed | > 1000 | High |
+| Sensitive files modified | Any of: `.env*`, `*secret*`, `*credential*`, `*auth*`, `*.key`, `*.pem` | High |
+| Config files modified | `package.json`, `pyproject.toml`, `tsconfig.json`, `Dockerfile` | Medium |
+| Migration files | `*migration*`, `*migrate*` | Medium |
+
+```bash
+# Check for sensitive file changes
+sensitive_files=$(git diff --name-only "$merge_base"...HEAD | grep -iE '\.(env|key|pem)|secret|credential' || true)
+if [ -n "$sensitive_files" ]; then
+  echo "HIGH RISK: Sensitive files modified:"
+  echo "$sensitive_files"
+fi
+```
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| Sensitive files detected | Set risk_level = high, add to risk_factors |
+| files_changed > 50 | Set risk_level = high, add to risk_factors |
+| lines changed > 1000 | Set risk_level = high, add to risk_factors |
+| Config or migration files detected | Set risk_level = medium (if not already high) |
+| No risk factors | Set risk_level = low |
+
+---
+
+### Step 4: AI Code Review via Inline Subagent
+
+Spawn inline-code-review subagent for AI analysis. Replace the ccw cli call from the original with this inline subagent:
+
+```
+spawn_agent({
+  task_name: "inline-code-review",
+  fork_context: false,
+  model: "haiku",
+  reasoning_effort: "medium",
+  message: `### MANDATORY FIRST STEPS
+1. Read: ~/.codex/agents/cli-explore-agent.md
+
+Goal: Review code changes for release readiness
+Context: Diff from <merge_base> to HEAD (<files_changed> files, +<lines_added>/-<lines_removed> lines)
+
+Task:
+- Review diff for bugs and correctness issues
+- Check for breaking changes (API, config, schema)
+- Identify security concerns
+- Assess test coverage gaps
+- Flag formatting-only changes to exclude from critical issues
+
+Expected: Risk level (low/medium/high), list of issues with severity and file:line reference, release recommendation (ship|hold|fix-first)
+Constraints: Focus on correctness and security | Flag breaking API changes | Ignore formatting-only changes`
+})
+const result = wait_agent({ targets: ["inline-code-review"], timeout_ms: 300000 })
+close_agent({ target: "inline-code-review" })
+```
+
+**Note**: Wait for the subagent to complete before proceeding. Do not advance to Step 5 while review is running.
+
+---
+
+### Step 5: Evaluate Review Results
+
+Based on the inline subagent output, apply gate logic.
+
+**Review Result Decision Table**:
+
+| Review Result | Action |
+|---------------|--------|
+| recommendation: "ship", no critical issues | Gate = pass — proceed to Phase 3 |
+| recommendation: "hold" or critical issues present | Gate = fail — report BLOCKED, list issues |
+| recommendation: "fix-first" | Gate = fail — report BLOCKED, list issues with file:line |
+| Warnings only, recommendation: "ship" | Gate = warn — proceed with DONE_WITH_CONCERNS note |
+| Review subagent failed or timed out | Ask user whether to proceed or retry |
+
+---
+
+## Output
+
+| Artifact | Format | Description |
+|----------|--------|-------------|
+| Review summary | JSON | Risk level, risk factors, AI review recommendation, critical issues, warnings |
+
+```json
+{
+  "phase": "code-review",
+  "merge_base": "commit-sha",
+  "stats": {
+    "files_changed": 0,
+    "lines_added": 0,
+    "lines_removed": 0
+  },
+  "risk_level": "low|medium|high",
+  "risk_factors": [],
+  "ai_review": {
+    "recommendation": "ship|hold|fix-first",
+    "critical_issues": [],
+    "warnings": []
+  },
+  "overall": "pass|fail|warn"
+}
+```
+
+## Success Criteria
+
+| Criterion | Validation Method |
+|-----------|-------------------|
+| Merge base detected | merge_base SHA present in output |
+| Diff statistics collected | files_changed, lines_added, lines_removed populated |
+| Risk assessment completed | risk_level set (low/medium/high), risk_factors populated |
+| AI review completed | ai_review.recommendation present |
+| Gate condition evaluated | overall set to pass/fail/warn |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| origin/main and origin/master both missing | Use HEAD~1 as merge base, warn user |
+| No commits in diff | WARN — nothing to review; ask user whether to proceed |
+| Inline subagent timeout | Log warning, ask user whether to proceed without AI review |
+| Inline subagent error | Log error, ask user whether to proceed |
+| Critical issues found | BLOCKED — report full issues list with severity and file:line |
+
+## Next Phase
+
+-> [Phase 3: Version Bump](03-version-bump.md)
+
+If review passes (overall: "pass" or "warn"), proceed to Phase 3.
+If critical issues found (overall: "fail"), report BLOCKED status with review summary. Do not proceed.

package/.codex/skills/ship/phases/03-version-bump.md

@@ -0,0 +1,259 @@
+# Phase 3: Version Bump
+
+> **COMPACT PROTECTION**: This is a core execution phase. If context compression has occurred and this file is only a summary, **MUST `Read` this file again before executing any Step**. Do not execute from memory.
+
+Detect the current version, determine the bump type, and update the version file.
+
+## Objective
+
+- Detect which version file the project uses
+- Read the current version
+- Determine bump type (patch/minor/major) from commit messages or user input
+- Update the version file
+- Record the version change
+
+## Input
+
+| Source | Required | Description |
+|--------|----------|-------------|
+| Phase 2 gate result | Yes | overall: "pass" or "warn" — must have passed |
+| package.json / pyproject.toml / VERSION | Conditional | One must exist; used for version detection |
+| Git history | Yes | Commit messages for bump type auto-detection |
+
+## Execution Steps
+
+### Step 1: Detect Version File
+
+Search for version file in priority order.
+
+**Version File Detection Priority Table**:
+
+| Priority | File | Read Method |
+|----------|------|-------------|
+| 1 | `package.json` | `jq -r .version package.json` |
+| 2 | `pyproject.toml` | `grep -oP 'version\s*=\s*"\K[^"]+' pyproject.toml` |
+| 3 | `VERSION` | `cat VERSION` |
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| package.json found | Set version_file = package.json, read version with node/jq |
+| pyproject.toml found (no package.json) | Set version_file = pyproject.toml, read with grep -oP |
+| VERSION found (no others) | Set version_file = VERSION, read with cat |
+| No version file found | NEEDS_CONTEXT — ask user which file to use or create |
+
+```bash
+if [ -f "package.json" ]; then
+  version_file="package.json"
+  current_version=$(node -p "require('./package.json').version" 2>/dev/null || jq -r .version package.json)
+elif [ -f "pyproject.toml" ]; then
+  version_file="pyproject.toml"
+  current_version=$(grep -oP 'version\s*=\s*"\K[^"]+' pyproject.toml | head -1)
+elif [ -f "VERSION" ]; then
+  version_file="VERSION"
+  current_version=$(cat VERSION | tr -d '[:space:]')
+else
+  echo "NEEDS_CONTEXT: No version file found"
+  echo "Expected one of: package.json, pyproject.toml, VERSION"
+  # Ask user which file to use or create
+fi
+
+echo "Version file: $version_file"
+echo "Current version: $current_version"
+```
+
+---
+
+### Step 2: Determine Bump Type
+
+Auto-detect from commit messages, then confirm with user for major bumps.
+
+**Bump Type Auto-Detection from Conventional Commits**:
+
+```bash
+# Get commits since last tag
+last_tag=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
+if [ -n "$last_tag" ]; then
+  commits=$(git log "$last_tag"..HEAD --oneline)
+else
+  commits=$(git log --oneline -20)
+fi
+
+# Scan for conventional commit prefixes
+has_breaking=$(echo "$commits" | grep -iE '(BREAKING CHANGE|!:)' || true)
+has_feat=$(echo "$commits" | grep -iE '^[a-f0-9]+ feat' || true)
+has_fix=$(echo "$commits" | grep -iE '^[a-f0-9]+ fix' || true)
+
+if [ -n "$has_breaking" ]; then
+  suggested_bump="major"
+elif [ -n "$has_feat" ]; then
+  suggested_bump="minor"
+else
+  suggested_bump="patch"
+fi
+
+echo "Suggested bump: $suggested_bump"
+```
+
+**User Confirmation Decision Table**:
+
+| Bump Type | Action |
+|-----------|--------|
+| patch | Proceed with suggested bump, inform user |
+| minor | Proceed with suggested bump, inform user |
+| major | Always ask user to confirm before proceeding |
+| User overrides suggestion | Use user-specified bump type |
+| User declines major bump | BLOCKED — halt, user must re-trigger with explicit bump type |
+
+---
+
+### Step 3: Calculate New Version
+
+Apply semver arithmetic to derive new version.
+
+**Decision Table**:
+
+| Bump Type | Calculation |
+|-----------|-------------|
+| major | `(major+1).0.0` |
+| minor | `major.(minor+1).0` |
+| patch | `major.minor.(patch+1)` |
+
+```bash
+# Parse semver components
+IFS='.' read -r major minor patch <<< "$current_version"
+
+case "$bump_type" in
+  major)
+    new_version="$((major + 1)).0.0"
+    ;;
+  minor)
+    new_version="${major}.$((minor + 1)).0"
+    ;;
+  patch)
+    new_version="${major}.${minor}.$((patch + 1))"
+    ;;
+esac
+
+echo "Version bump: $current_version -> $new_version"
+```
+
+---
+
+### Step 4: Update Version File
+
+Write new version to the appropriate file using the correct method for each format.
+
+**Decision Table**:
+
+| Version File | Update Method |
+|--------------|---------------|
+| package.json | `jq --arg v "<new_version>" '.version = $v'` + update package-lock.json if present |
+| pyproject.toml | `sed -i "s/^version\s*=\s*\".*\"/version = \"<new_version>\"/"` |
+| VERSION | `echo "<new_version>" > VERSION` |
+
+```bash
+case "$version_file" in
+  package.json)
+    # Use node/jq for safe JSON update
+    jq --arg v "$new_version" '.version = $v' package.json > tmp.json && mv tmp.json package.json
+    # Also update package-lock.json if it exists
+    if [ -f "package-lock.json" ]; then
+      jq --arg v "$new_version" '.version = $v | .packages[""].version = $v' package-lock.json > tmp.json && mv tmp.json package-lock.json
+    fi
+    ;;
+  pyproject.toml)
+    # Use sed for TOML update (version line in [project] or [tool.poetry])
+    sed -i "s/^version\s*=\s*\".*\"/version = \"$new_version\"/" pyproject.toml
+    ;;
+  VERSION)
+    echo "$new_version" > VERSION
+    ;;
+esac
+
+echo "Updated $version_file: $current_version -> $new_version"
+```
+
+---
+
+### Step 5: Verify Update
+
+Re-read version file to confirm the update was applied correctly.
+
+**Decision Table**:
+
+| Condition | Action |
+|-----------|--------|
+| Re-read version equals new_version | PASS — gate satisfied |
+| Re-read version does not match | FAIL — report mismatch, BLOCKED |
+
+```bash
+# Re-read to confirm
+case "$version_file" in
+  package.json)
+    verified=$(node -p "require('./package.json').version" 2>/dev/null || jq -r .version package.json)
+    ;;
+  pyproject.toml)
+    verified=$(grep -oP 'version\s*=\s*"\K[^"]+' pyproject.toml | head -1)
+    ;;
+  VERSION)
+    verified=$(cat VERSION | tr -d '[:space:]')
+    ;;
+esac
+
+if [ "$verified" = "$new_version" ]; then
+  echo "PASS: Version verified as $new_version"
+else
+  echo "FAIL: Version mismatch — expected $new_version, got $verified"
+fi
+```
+
+---
+
+## Output
+
+| Artifact | Format | Description |
+|----------|--------|-------------|
+| Version change record | JSON | version_file, previous_version, new_version, bump_type, bump_source |
+
+```json
+{
+  "phase": "version-bump",
+  "version_file": "package.json",
+  "previous_version": "1.2.3",
+  "new_version": "1.3.0",
+  "bump_type": "minor",
+  "bump_source": "auto-detected|user-specified",
+  "overall": "pass|fail"
+}
+```
+
+## Success Criteria
+
+| Criterion | Validation Method |
+|-----------|-------------------|
+| Version file detected | version_file field populated |
+| Current version read | current_version field populated |
+| Bump type determined | bump_type set to patch/minor/major |
+| Version file updated | Write/edit operation succeeded |
+| Update verified | Re-read matches new_version |
+| overall = "pass" | All steps completed without error |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| No version file found | NEEDS_CONTEXT — ask user which file to create or use |
+| Version parse error (malformed semver) | NEEDS_CONTEXT — report current value, ask user for correction |
+| jq not available | Fall back to node for package.json; report error for others |
+| sed fails on pyproject.toml | Try Write tool to rewrite the file; report on failure |
+| User declines major bump | BLOCKED — halt, user must re-trigger with explicit bump type |
+| Version mismatch after update | BLOCKED — report expected vs actual, suggest manual fix |
+
+## Next Phase
+
+-> [Phase 4: Changelog & Commit](04-changelog-commit.md)
+
+If version updated successfully (overall: "pass"), proceed to Phase 4.
+If update fails or context needed, report BLOCKED / NEEDS_CONTEXT. Do not proceed.