CWS-94: Harden PR Scripts — Implementation Plan

git checkout main && git pull --ff-only origin main

gt create cws/94-phase-removal-governance-fix -m "chore: PR 1 — phase removal + governance fix + rename"

git branch --show-current

git add .codex/rollout/active-plan.yaml
git commit -m "chore(cws-94): add exempt_branch_patterns to active-plan.yaml"

cd scripts && ruby tests/rollout_governance_test.rb

cd scripts && ruby tests/rollout_governance_test.rb

git add scripts/validate-rollout-governance.rb scripts/tests/rollout_governance_test.rb
git commit -m "feat(cws-94): add exempt branch pattern support to governance validator"

bash -n scripts/create-pr.sh

git add scripts/create-pr.sh
git commit -m "fix(cws-94): remove phase logic from create-pr.sh"

bash -n scripts/finalize-merge.sh

cd scripts && ruby tests/finalize_merge_workflow_test.rb

git add scripts/finalize-merge.sh scripts/tests/finalize_merge_workflow_test.rb
git commit -m "fix(cws-94): remove phase logic from finalize-merge.sh"

git mv scripts/run-codex-checks.sh scripts/run-workflow-checks.sh

git add scripts/run-workflow-checks.sh scripts/tests/repo_ruby_activation_test.rb
git commit -m "refactor(cws-94): rename run-codex-checks.sh to run-workflow-checks.sh, fix backtick interpolation"

run_step "Validating Codex skills, prompts, and docs" make codex-check

run_step "Validating workflow skills, prompts, and docs" make workflow-check

git add Makefile .github/workflows/ scripts/run-local-qa.sh scripts/site-audit.sh .codex/docs/tooling.md .codex/docs/multi-agent-orchestration.md .codex/docs/multi-agent-rollout-checklist.md
git commit -m "refactor(cws-94): rename codex-check to workflow-check across all references, bump actions/checkout to v6"

make qa-local

git add .codex/rollout/evidence/cws-94-phase-removal-governance-fix.md
git commit -m "docs(cws-94): add PR 1 evidence file"

gt create cws/94-fallback-and-flags -m "chore: PR 2 — fallback, non-interactive, stack merge, dynamic body"

#!/usr/bin/env bash
# Shared GitHub API functions with gh CLI primary + curl fallback.
# Source this file: . "$repo_root/scripts/lib/github-api.sh"
set -euo pipefail

# Resolve GitHub API token.
# Order: (1) GITHUB_TOKEN env, (2) gh auth token, (3) fail.
_github_resolve_token() {
  if [[ -n "${GITHUB_TOKEN:-}" ]]; then
    printf '%s' "$GITHUB_TOKEN"
    return 0
  fi
  if command -v gh >/dev/null 2>&1; then
    local token
    token="$(gh auth token 2>/dev/null || true)"
    if [[ -n "$token" ]]; then
      printf '%s' "$token"
      return 0
    fi
  fi
  echo "error: no GitHub token available. Set GITHUB_TOKEN or run: gh auth login" >&2
  return 1
}

# Resolve OWNER/REPO from git remote.
_github_resolve_repo() {
  local remote_url
  remote_url="$(git remote get-url origin 2>/dev/null || true)"
  if [[ -z "$remote_url" ]]; then
    echo "error: cannot determine repository from git remote" >&2
    return 1
  fi
  # Handle SSH (git@github.com:owner/repo.git) and HTTPS (https://github.com/owner/repo.git)
  printf '%s' "$remote_url" | sed -E 's#^(https?://github\.com/|git@github\.com:)##; s#\.git$##'
}

# Check if gh CLI is available and authenticated.
_gh_available() {
  command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1
}

# GET request to GitHub API.
# Usage: github_api_get <endpoint>
# Example: github_api_get "/repos/owner/repo/pulls/123"
github_api_get() {
  local endpoint="$1"
  if _gh_available; then
    gh api "$endpoint" 2>/dev/null && return 0
  fi
  local token
  token="$(_github_resolve_token)" || return 1
  curl -fsSL \
    -H "Authorization: token $token" \
    -H "Accept: application/vnd.github+json" \
    "https://api.github.com${endpoint}"
}

# POST/PATCH request to GitHub API.
# Usage: github_api_post <method> <endpoint> <json_body>
# Example: github_api_post POST "/repos/owner/repo/pulls" '{"title":"..."}'
github_api_post() {
  local method="$1" endpoint="$2" body="$3"
  if _gh_available; then
    gh api "$endpoint" --method "$method" --input - <<<"$body" 2>/dev/null && return 0
  fi
  local token
  token="$(_github_resolve_token)" || return 1
  curl -fsSL \
    -X "$method" \
    -H "Authorization: token $token" \
    -H "Accept: application/vnd.github+json" \
    -H "Content-Type: application/json" \
    -d "$body" \
    "https://api.github.com${endpoint}"
}

# View PR details by branch name or PR number.
# Usage: gh_or_curl_pr_view <branch_or_number>
# Returns JSON with number, state, url, headRefName, baseRefName, isDraft, statusCheckRollup.
gh_or_curl_pr_view() {
  local ref="$1"
  if _gh_available; then
    gh pr view "$ref" --json number,state,url,headRefName,baseRefName,isDraft,statusCheckRollup,mergedAt 2>/dev/null && return 0
  fi
  local repo
  repo="$(_github_resolve_repo)" || return 1
  # If ref is a number, fetch by number; otherwise search by head branch
  if [[ "$ref" =~ ^[0-9]+$ ]]; then
    github_api_get "/repos/${repo}/pulls/${ref}"
  else
    github_api_get "/repos/${repo}/pulls?head=${repo%%/*}:${ref}&state=open" | ruby -rjson -e '
      prs = JSON.parse(STDIN.read)
      if prs.empty?
        warn "error: no open PR found for branch #{ARGV[0]}"
        exit 1
      end
      puts JSON.generate(prs.first)
    ' "$ref"
  fi
}

# Create a PR.
# Usage: gh_or_curl_pr_create <base> <head> <title> <body_file>
gh_or_curl_pr_create() {
  local base="$1" head="$2" title="$3" body_file="$4"
  if _gh_available; then
    gh pr create --base "$base" --head "$head" --title "$title" --body-file "$body_file" 2>/dev/null && return 0
  fi
  local repo body
  repo="$(_github_resolve_repo)" || return 1
  body="$(cat "$body_file")"
  local json
  json="$(ruby -rjson -e 'puts JSON.generate({title: ARGV[0], body: ARGV[1], head: ARGV[2], base: ARGV[3]})' "$title" "$body" "$head" "$base")"
  github_api_post POST "/repos/${repo}/pulls" "$json"
}

# Edit PR title and body.
# Usage: gh_or_curl_pr_edit <pr_number_or_branch> <title> <body_file>
gh_or_curl_pr_edit() {
  local pr="$1" title="$2" body_file="$3"
  if _gh_available; then
    gh pr edit "$pr" --title "$title" --body-file "$body_file" 2>/dev/null && return 0
  fi
  local repo body pr_number
  repo="$(_github_resolve_repo)" || return 1
  body="$(cat "$body_file")"
  # Resolve PR number if given a branch name
  if [[ ! "$pr" =~ ^[0-9]+$ ]]; then
    pr_number="$(gh_or_curl_pr_view "$pr" | ruby -rjson -e 'puts JSON.parse(STDIN.read)["number"]')"
  else
    pr_number="$pr"
  fi
  local json
  json="$(ruby -rjson -e 'puts JSON.generate({title: ARGV[0], body: ARGV[1]})' "$title" "$body")"
  github_api_post PATCH "/repos/${repo}/pulls/${pr_number}" "$json"
}

# Merge a PR.
# Usage: gh_or_curl_pr_merge <pr_number_or_branch> <method>
# method: rebase, squash, or merge
gh_or_curl_pr_merge() {
  local pr="$1" method="${2:-rebase}"
  if _gh_available; then
    gh pr merge "$pr" --"$method" --delete-branch 2>/dev/null && return 0
  fi
  local repo pr_number
  repo="$(_github_resolve_repo)" || return 1
  if [[ ! "$pr" =~ ^[0-9]+$ ]]; then
    pr_number="$(gh_or_curl_pr_view "$pr" | ruby -rjson -e 'puts JSON.parse(STDIN.read)["number"]')"
  else
    pr_number="$pr"
  fi
  local json
  json="$(ruby -rjson -e 'puts JSON.generate({merge_method: ARGV[0]})' "$method")"
  github_api_post PUT "/repos/${repo}/pulls/${pr_number}/merge" "$json"
}

chmod +x scripts/lib/github-api.sh
git add scripts/lib/github-api.sh
git commit -m "feat(cws-94): add github-api.sh shared gh/curl fallback library"

# shellcheck disable=SC1091
. "$repo_root/scripts/lib/github-api.sh"

if ! gh auth status >/dev/null 2>&1; then
  echo "error: GitHub CLI authentication is invalid. Run: gh auth login -h github.com" >&2
  exit 1
fi

if ! _gh_available; then
  if ! _github_resolve_token >/dev/null 2>&1; then
    echo "error: no GitHub authentication. Run: gh auth login, or set GITHUB_TOKEN" >&2
    exit 1
  fi
fi

commit_summary="$(git log --oneline "${base_branch}...HEAD" | head -20)"
if [[ -z "$commit_summary" ]]; then
  commit_summary="(no commits on branch)"
fi

# Auto-check traceability items
check_branch="[x]"
check_title="[ ]"
check_task_file="[ ]"
check_agent_context="[ ]"
check_linear_link="[ ]"

if [[ -n "$issue_id" ]]; then
  issue_id_lower="$(printf '%s' "$issue_id" | tr '[:upper:]' '[:lower:]')"
  if [[ "$title" == *"${issue_id}"* || "$title" == *"${issue_id_lower}"* ]]; then
    check_title="[x]"
  fi
  if [[ -f "$repo_root/docs/tasks/${issue_id}.md" ]]; then
    check_task_file="[x]"
  fi
  if [[ -n "$linear_issue_link" ]]; then
    check_linear_link="[x]"
  fi
fi

cat > "$body_file" <<EOF
## Branch And Title Convention

- Branch: \`$branch\`
- Task-branch PR title must include matching issue token (\`${issue_id:-n/a}\`)
- Linear issue link: ${linear_issue_link:-"(not available)"}

## Traceability Checklist

- ${check_branch} Branch name matches approved pattern
- ${check_title} PR title contains matching issue token (\`${issue_id:-n/a}\`)
- ${check_task_file} \`docs/tasks/${issue_id:-CWS-XX}.md\` exists and is committed
- ${check_agent_context} \`docs/agent-context.md\` is fresh (not stale)
- ${check_linear_link} Linear issue link is present in this PR

## Summary

${commit_summary}

## Why

- ${title#"$type: "}

## Linear Traceability

- Parent issue: \`(see Linear)\`
- This issue: ${linear_issue_link:-"(not available)"}

## Validation

- \`make qa-local\`

## Affected Files

\`\`\`text
$affected_files
\`\`\`

## Affected URLs

\`\`\`text
$affected_urls
\`\`\`

## Self-review Notes

- Risk assessment: standard workflow changes
- Backward compatibility notes: phase workflow removed (already deprecated)
EOF

if ! gh pr view "$branch" >/dev/null 2>&1; then
  gh pr create \
    --base "$base_branch" \
    --head "$branch" \
    --title "$title" \
    --body-file "$body_file"
fi

gh pr edit "$branch" --title "$title" --body-file "$body_file"

if [[ "$(gh pr view "$branch" --json isDraft --jq '.isDraft')" == "true" ]]; then
  gh pr ready "$branch"
fi

if ! gh_or_curl_pr_view "$branch" >/dev/null 2>&1; then
  gh_or_curl_pr_create "$base_branch" "$branch" "$title" "$body_file"
fi

gh_or_curl_pr_edit "$branch" "$title" "$body_file"

# Mark PR ready if draft (gh-only, best-effort)
if _gh_available; then
  if [[ "$(gh pr view "$branch" --json isDraft --jq '.isDraft' 2>/dev/null)" == "true" ]]; then
    gh pr ready "$branch" 2>/dev/null || true
  fi
fi

bash -n scripts/create-pr.sh

git add scripts/create-pr.sh
git commit -m "feat(cws-94): integrate fallback lib and template-driven PR body in create-pr.sh"

# shellcheck disable=SC1091
. "$repo_root/scripts/lib/github-api.sh"

non_interactive="${YES:-}"
stack_mode="${STACK:-}"

while [[ $# -gt 0 ]]; do
  case "$1" in
    --yes|--no-interactive) non_interactive=1; shift ;;
    --stack) stack_mode=1; shift ;;
    *) break ;;
  esac
done

pr="${PR:-${1:-}}"

if ! gh auth status >/dev/null 2>&1; then
  echo "error: GitHub CLI authentication is invalid. Run: gh auth login -h github.com" >&2
  exit 1
fi

if ! _gh_available; then
  if ! _github_resolve_token >/dev/null 2>&1; then
    echo "error: no GitHub authentication. Run: gh auth login, or set GITHUB_TOKEN" >&2
    exit 1
  fi
fi

pr_state="$(gh pr view "$pr" --json number,statusCheckRollup,isDraft,url,baseRefName,headRefName,state)"

pr_state="$(gh_or_curl_pr_view "$pr")"

printf 'Integrate this PR into %s via GitHub rebase merge (single PR only)? [y/N] ' "$base_ref_name"
read -r confirm
if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
  echo "integration cancelled"
  exit 1
fi

if [[ -n "$non_interactive" ]]; then
  echo "non-interactive mode: proceeding with merge"
else
  printf 'Integrate this PR into %s via GitHub rebase merge (single PR only)? [y/N] ' "$base_ref_name"
  read -r confirm
  if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
    echo "integration cancelled"
    exit 1
  fi
fi

if [[ -n "$stack_mode" ]]; then
  echo "stack merge mode"
  if command -v gt >/dev/null 2>&1; then
    if gt merge 2>/dev/null; then
      echo "stack merged via gt merge"
    else
      echo "warning: gt merge failed; falling back to single PR merge" >&2
      gh_or_curl_pr_merge "$pr" rebase
    fi
  else
    echo "warning: gt not available; falling back to single PR merge" >&2
    gh_or_curl_pr_merge "$pr" rebase
  fi
else
  gh_or_curl_pr_merge "$pr" rebase
fi

rebase_allowed="$(gh repo view --json rebaseMergeAllowed --jq '.rebaseMergeAllowed')"

repo_slug="$(_github_resolve_repo)"
rebase_allowed="$(github_api_get "/repos/${repo_slug}" | ruby -rjson -e 'puts JSON.parse(STDIN.read)["allow_rebase_merge"]' 2>/dev/null || echo "true")"

bash -n scripts/finalize-merge.sh

git add scripts/finalize-merge.sh
git commit -m "feat(cws-94): add --yes, --stack flags and gh/curl fallback to finalize-merge.sh"

git add Makefile
git commit -m "feat(cws-94): add YES and STACK variables to finalize-merge Makefile target"

make qa-local

git add .codex/rollout/evidence/cws-94-fallback-and-flags.md
git commit -m "docs(cws-94): add PR 2 evidence file"

gt create cws/94-staleness-and-skill -m "chore: PR 3 — staleness mechanism + repo-flow skill update"

#!/usr/bin/env bash
# SessionStart hook: warn if docs/agent-context.md is stale.
# Registered in .claude/settings.json under hooks.SessionStart.
# Fail-closed: exit 2 on error (block execution), never fail-open.
set -euo pipefail

repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
agent_context="$repo_root/docs/agent-context.md"

if [[ ! -f "$agent_context" ]]; then
  echo "error: docs/agent-context.md not found" >&2
  exit 2
fi

# Extract the stale-after timestamp from the "## Stale After" section.
stale_ts="$(ruby -e '
  content = File.read(ARGV[0])
  section = content.match(/^## Stale After\s*$\n+((?:- .*\n)+)/m)
  if section.nil?
    warn "error: cannot find Stale After section in agent-context.md"
    exit 2
  end
  ts_line = section[1].lines.find { |l| l.match?(/^\s*-\s*`[^`]+`\s*$/) }
  if ts_line.nil?
    warn "error: cannot find timestamp in Stale After section"
    exit 2
  end
  puts ts_line[/`([^`]+)`/, 1]
' "$agent_context" 2>&1)" || exit 2

if [[ -z "$stale_ts" ]]; then
  echo "error: empty stale timestamp in agent-context.md" >&2
  exit 2
fi

# Compare timestamps
is_stale="$(ruby -e '
  require "time"
  ts = Time.parse(ARGV[0]) rescue nil
  if ts.nil?
    warn "error: cannot parse timestamp: #{ARGV[0]}"
    exit 2
  end
  puts Time.now > ts ? "stale" : "fresh"
' "$stale_ts" 2>&1)" || exit 2

if [[ "$is_stale" == "stale" ]]; then
  cat <<EOF
WARNING: docs/agent-context.md is STALE (stale_after=$stale_ts).
Run a Linear sync before executing tasks. The cached context may not reflect
current issue states, priorities, or cycle assignments.
EOF
fi

chmod +x .claude/hooks/check-agent-context-staleness.sh

git add .claude/hooks/check-agent-context-staleness.sh
git commit -m "feat(cws-94): add SessionStart staleness hook for agent-context.md"

# Update agent-context.md staleness timestamp (D7)
agent_context="$repo_root/docs/agent-context.md"
if [[ -f "$agent_context" ]]; then
  new_stale_ts="$(ruby -e '
    require "time"
    puts (Time.now + 86400).strftime("%Y-%m-%d %H:%M:%S %Z")
  ')"
  ruby -e '
    path = ARGV[0]
    new_ts = ARGV[1]
    content = File.read(path)
    updated = content.sub(/^(## Stale After\s*\n+- )`[^`]+`/, "\\1`#{new_ts}`")
    if updated == content
      warn "warning: could not update stale timestamp in agent-context.md"
    else
      File.write(path, updated)
    end
  ' "$agent_context" "$new_stale_ts"

  if ! git diff --quiet "$agent_context" 2>/dev/null; then
    git add "$agent_context"
    git commit -m "chore: bump agent-context staleness timestamp to $new_stale_ts"
  fi
fi

bash -n scripts/finalize-merge.sh

git add scripts/finalize-merge.sh
git commit -m "feat(cws-94): add post-merge staleness timestamp bump to finalize-merge.sh"

git add .agents/skills/repo-flow/SKILL.md .agents/skills/repo-flow/references/branch-pr-merge.md
git commit -m "docs(cws-94): rewrite repo-flow skill for task-only + stack + fallback workflow"

make qa-local

git add docs/tasks/CWS-94.md .codex/rollout/evidence/cws-94-staleness-and-skill.md
git commit -m "docs(cws-94): add task file and PR 3 evidence"

gt submit --stack --no-interactive --publish

gt stack