Add shared shell helpers, test framework, and shellcheck config

- Add .shellcheckrc with SC1091 global suppression
- Add actions_helpers.sh with shared GitHub Actions helpers
  (log_error, log_warning, log_notice, set_output, etc.)
- Add test_helpers.sh with run_test framework for bash tests
- Add tests for actions_helpers and autotag-from-changelog
- Update test.sh to discover *_test.sh files automatically
- Update CLAUDE.md with project conventions

Co-Authored-By: roachdev-claude <[email protected]>

Author: fantapop

.shellcheckrc

@@ -0,0 +1,5 @@
+# All source calls use dynamic $SCRIPT_DIR paths that shellcheck cannot resolve.
+disable=SC1091
+# Allow following sourced files and resolve relative paths from the script's directory.
+external-sources=true
+source-path=SCRIPTDIR

CHANGELOG.md

@@ -10,5 +10,13 @@ Breaking changes are prefixed with "Breaking Change: ".
 
 ### Added
 
+- `autosolve/assess` action: evaluate tasks for automated resolution suitability
+  using Claude in read-only mode.
+- `autosolve/implement` action: autonomously implement solutions, validate
+  security, push to fork, and create PRs using Claude.
+- `github-issue-autosolve` reusable workflow: turnkey GitHub Issues
+  integration with issue comments and label management.
+- `jira-autosolve` reusable workflow: turnkey Jira integration composing
+  autosolve/assess + autosolve/implement with ticket comments and transitions.
 - `autotag-from-changelog` action: tag and push from CHANGELOG.md version
   change.

CLAUDE.md

@@ -35,5 +35,48 @@ scripts that set up temporary git repos and validate behavior.
   syntax highlighting and testability.
 - update CHANGELOG.md with each change.  If it's a breaking change, prefix
   with "Breaking Change: ". Try to keep change descriptions focused on user
-  outcome.
+  outcome. New entries go above older ones (the changelog grows upward).
 - CI runs on PRs: `test.yml` runs `./test.sh`, `actionlint.yml` lints workflow YAML files
+- Every shellcheck suppression (`disable`, `source`, etc.) must include a short
+  comment explaining why the suppression is needed. SC1091 (can't follow
+  sourced file) is disabled globally in `.shellcheckrc` since all sources use
+  dynamic `$SCRIPT_DIR` paths.
+- In test files, prefer `cd "$(dirname "${BASH_SOURCE[0]}")"` at the top and then use literal
+  relative paths for `source` (e.g., `source ../../actions_helpers.sh`). This
+  enables IDE go-to-definition via `source-path=SCRIPTDIR` in `.shellcheckrc`
+  without needing `# shellcheck source=` directives. In production scripts that
+  cannot `cd`, use `SCRIPT_DIR` with `# shellcheck source=` directives for
+  navigation.
+- `actions_helpers.sh` at the repo root provides shared helpers (`log_error`, `log_warning`,
+  `log_notice`, `set_output`, `set_output_multiline`). Scripts source it via
+  a relative path after `cd`-ing to their own directory.
+- Autosolve scripts (`assess.sh`, `implement.sh`, `github_issues.sh`, `shared.sh`) source their
+  own dependencies via `BASH_SOURCE`-relative paths. No caller needs to source the
+  chain — just source the script you need. Re-sourcing is idempotent.
+- In shell scripts, prefer long options over short flags for readability
+  (e.g., `grep --quiet --fixed-strings` instead of `grep -qF`,
+  `curl --silent --output /dev/null` instead of `curl -s -o /dev/null`).
+  Exceptions: flags with no long form (e.g., `git checkout -b`) and
+  universally understood short forms in test helpers (e.g., `rm -rf`).
+- Never discard stderr (e.g., `2>/dev/null`) in shell scripts or action
+  steps. Suppressing stderr hides real errors and makes debugging harder.
+  Using `2>&1` to merge stderr into stdout is acceptable in test helpers
+  that need to capture all output for assertion, but avoid it in
+  production scripts. Run each command on its own line so that `bash -e`
+  (the default for GitHub Actions `run` steps) halts on failure and the
+  return code is checked automatically.
+- In workflow YAML files, always use the latest major version of built-in
+  GitHub Actions (e.g., `actions/checkout@v5`, `actions/upload-artifact@v4`).
+- In autosolve workflows, install the Claude CLI (npm) BEFORE any cloud
+  authentication step, and move credential files out of the workspace
+  immediately after authentication. npm post-install scripts run with the
+  job's full environment, so installing after auth exposes credentials
+  (e.g., the OIDC bearer token in `gha-creds-*.json`) to arbitrary code.
+  The correct step order is: checkout → install CLI → authenticate →
+  move credentials → run autosolve action.
+- Do not silently swallow errors. In shell scripts, avoid `|| return 0`,
+  `|| true`, or `|| :` to suppress failures without logging — use
+  `log_warning` to surface what went wrong. In Go code, avoid `return nil`
+  on error paths without logging or returning the error. If ignoring an
+  error is genuinely correct (e.g., best-effort cleanup), add a comment
+  explaining why it's safe to ignore.

README.md

@@ -29,6 +29,170 @@ permissions:
   contents: write
 ```
 
+### autosolve
+
+Uses Claude Code to autonomously assess and implement solutions for tasks.
+Organized as two composite actions that can be used independently or together,
+plus reusable workflows for common integrations.
+
+#### Actions
+
+**`autosolve/assess`** — Runs Claude in read-only mode to evaluate whether a
+task is suitable for automated resolution.
+
+```yaml
+- uses: cockroachdb/actions/autosolve/assess@v1
+  id: assess
+  with:
+    prompt: "Fix the login bug described in issue #42"
+```
+
+| Input | Default | Description |
+|---|---|---|
+| `prompt` | | Task description for Claude to assess |
+| `skill` | | Path to a skill/prompt file relative to the repo root |
+| `additional_instructions` | | Extra context appended after the task prompt |
+| `assessment_criteria` | *(built-in)* | Custom criteria for PROCEED/SKIP decision |
+| `model` | `claude-opus-4-6` | Claude model ID |
+| `blocked_paths` | `.github/workflows/` | Comma-separated path prefixes that cannot be modified |
+
+| Output | Description |
+|---|---|
+| `assessment` | `PROCEED` or `SKIP` |
+| `summary` | Human-readable assessment reasoning |
+| `result` | Full Claude result text |
+
+**`autosolve/implement`** — Runs Claude to implement a solution, validates
+changes against blocked paths, pushes to a fork, and creates a PR.
+
+```yaml
+- uses: cockroachdb/actions/autosolve/implement@v1
+  if: steps.assess.outputs.assessment == 'PROCEED'
+  with:
+    prompt: "Fix the login bug described in issue #42"
+    fork_owner: my-bot
+    fork_repo: my-repo
+    fork_push_token: ${{ secrets.FORK_PUSH_TOKEN }}
+    pr_create_token: ${{ secrets.PR_CREATE_TOKEN }}
+```
+
+| Input | Default | Description |
+|---|---|---|
+| `prompt` | | Task description for Claude to implement |
+| `skill` | | Path to a skill/prompt file relative to the repo root |
+| `additional_instructions` | | Extra instructions appended after the task prompt |
+| `allowed_tools` | *(read/write/git tools)* | Claude `--allowedTools` string |
+| `model` | `claude-opus-4-6` | Claude model ID |
+| `max_retries` | `3` | Maximum implementation attempts |
+| `timeout_minutes` | `60` | Maximum wall-clock time |
+| `create_pr` | `true` | Whether to create a PR from the changes |
+| `pr_base_branch` | *(repo default)* | Base branch for the PR |
+| `pr_labels` | `autosolve` | Comma-separated labels to apply |
+| `pr_draft` | `true` | Whether to create as a draft PR |
+| `pr_title` | *(from commit)* | PR title |
+| `pr_body_template` | *(built-in)* | Template with `{{SUMMARY}}`, `{{STATS}}`, `{{BRANCH}}` placeholders |
+| `fork_owner` | | GitHub user/org that owns the fork |
+| `fork_repo` | | Fork repository name |
+| `fork_push_token` | | PAT with push access to the fork |
+| `pr_create_token` | | PAT with PR create access on upstream |
+| `blocked_paths` | `.github/workflows/` | Comma-separated blocked path prefixes |
+| `git_user_name` | `autosolve[bot]` | Git author/committer name |
+| `git_user_email` | `autosolve[bot]@users.noreply.github.com` | Git author/committer email |
+| `branch_suffix` | *(timestamp)* | Suffix for branch name (`autosolve/<suffix>`) |
+
+| Output | Description |
+|---|---|
+| `status` | `SUCCESS` or `FAILED` |
+| `pr_url` | URL of the created PR |
+| `summary` | Human-readable summary |
+| `result` | Full Claude result text |
+| `branch_name` | Branch pushed to the fork |
+
+#### Reusable Workflows
+
+**Jira Autosolve** — Composes assess + implement with Jira comments and ticket
+transitions. Triggered via `workflow_call`.
+
+```yaml
+jobs:
+  solve:
+    uses: cockroachdb/actions/.github/workflows/jira-autosolve.yml@v1
+    with:
+      ticket_id: PROJ-123
+      title: ${{ needs.parse.outputs.title }}
+      description: ${{ needs.parse.outputs.description }}
+      jira_base_url: https://yourcompany.atlassian.net
+      fork_owner: my-bot
+      fork_repo: my-repo
+    secrets:
+      jira_token: ${{ secrets.JIRA_TOKEN }}
+      fork_push_token: ${{ secrets.FORK_PUSH_TOKEN }}
+      pr_create_token: ${{ secrets.PR_CREATE_TOKEN }}
+```
+
+**GitHub Issue Autosolve** — Composes assess + implement with GitHub issue
+comments and label management. Triggered via `workflow_call`.
+
+```yaml
+jobs:
+  solve:
+    uses: cockroachdb/actions/.github/workflows/github-issue-autosolve.yml@v1
+    with:
+      issue_number: ${{ github.event.issue.number }}
+      issue_title: ${{ github.event.issue.title }}
+      issue_body: ${{ github.event.issue.body }}
+      fork_owner: my-bot
+      fork_repo: my-repo
+    secrets:
+      fork_push_token: ${{ secrets.FORK_PUSH_TOKEN }}
+      pr_create_token: ${{ secrets.PR_CREATE_TOKEN }}
+```
+
+#### Authentication
+
+**Reusable workflows** accept `auth_mode` as an input (`vertex`, `bedrock`, or
+omit for API key) and handle env var setup internally.
+
+**Direct composite action usage** requires the caller to set up auth and pass
+the env vars on each action step:
+
+```yaml
+# Example: Vertex AI auth for direct action usage
+- uses: google-github-actions/auth@v3
+  with:
+    project_id: my-project
+    service_account: [email protected]
+    workload_identity_provider: projects/.../providers/...
+
+- uses: cockroachdb/actions/autosolve/assess@v1
+  env:
+    CLAUDE_CODE_USE_VERTEX: "1"
+    ANTHROPIC_VERTEX_PROJECT_ID: my-project
+    CLOUD_ML_REGION: us-east5
+  with:
+    prompt: "Fix the bug"
+```
+
+Alternatively, set `ANTHROPIC_API_KEY` in the environment for direct API
+access, or configure Bedrock with `CLAUDE_CODE_USE_BEDROCK=1` and `AWS_REGION`.
+
+#### Caller checkout
+
+When using `workflow_dispatch`, `actions/checkout` defaults to the branch that
+triggered the workflow. This can include unrelated commits from that branch in
+the autosolve PR. Always check out the PR base branch explicitly:
+
+```yaml
+- uses: actions/checkout@v5
+  with:
+    ref: main  # checkout the PR base branch, not the trigger ref
+    fetch-depth: 0
+    persist-credentials: false  # prevent checkout's credential helper from interfering with fork push
+```
+
+The `issues: [labeled]` trigger doesn't have this problem since it always runs
+on the default branch.
+
 ## Development
 
 Run all tests locally:

actions_helpers.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Shared shell helpers for all GitHub Actions in this repo.
+
+# GitHub Actions log commands — emit structured annotations via stdout.
+log_error()   { echo "::error::$*"; }
+log_warning() { echo "::warning::$*"; }
+log_notice()  { echo "::notice::$*"; }
+
+# Write a single-line output: set_output key value
+set_output() {
+  echo "$1=$2" >> "${GITHUB_OUTPUT:-/dev/null}"
+}
+
+# Write a multiline output: set_output_multiline key value
+set_output_multiline() {
+  local delim
+  delim="GHEOF_$$_$(date +%s)"
+  {
+    echo "$1<<$delim"
+    echo "$2"
+    echo "$delim"
+  } >> "${GITHUB_OUTPUT:-/dev/null}"
+}
+
+# Verify a command is on PATH: require_command <name>
+require_command() {
+  command -v "$1" >/dev/null || { log_error "$1 not found on PATH"; return 1; }
+}
+
+# Truncate text to a maximum number of lines, appending a notice if truncated.
+# Usage: truncate_output <max_lines> <text>
+truncate_output() {
+  local max_lines="$1"
+  local text="$2"
+  local line_count
+  line_count="$(echo "$text" | wc -l | tr -d ' ')"
+  if [ "$line_count" -gt "$max_lines" ]; then
+    echo "$text" | head -"$max_lines"
+    echo "[... truncated ($line_count lines total, showing first $max_lines)]"
+  else
+    echo "$text"
+  fi
+}
+
+# Append content to the GitHub Actions step summary.
+# Usage: write_step_summary <<EOF ... EOF
+write_step_summary() {
+  cat >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
+}