gem-contribute 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ba185bef64e34f7c11bce3b56e18dc85f9a937a597db98615977b8b29d0306a
-  data.tar.gz: f1f2c4b77dca2e77da8eaa188a3a2db6d87d4c62eef471c3e9e8d13faff3ecc5
+  metadata.gz: 642744289b8e25b5109868d7ef71fbb33e7067d79d8fb9c6580e8a88b566dea6
+  data.tar.gz: d2e5cca3a504bd75de537e9b38ba22a0ff2f2b6915162cb9d37f5d065933cc72
 SHA512:
-  metadata.gz: 6a52e54602d58024cc94db5cd353556b0f0d18ea6b07a5647a918a96c748547b692531a53ee1f6a1fd7e7a887b9cf30650edce9568a84a76d993245b68d35661
-  data.tar.gz: 9c4b75036cb2091312b1405797ebea50fe9ab1103ae793081834c03a5e18a1151c006f127e84f160b234a8ab6b8037e243bf3d09feea962daeb8854f96c3770b
+  metadata.gz: a2600e3b0ee2adf44fcadab52639e446aae0d15f7d4843c111d68d86b3fd726bed20d72ad62063c72230656cdf8c62a52d7fc1507b7e5fb85032678f77ae99a7
+  data.tar.gz: 1f208fe93824d839c8ca78cf842a5cc0fcbebcf3c9b4f89cf8d9fcdd1c403ce19b9b1f0c1e664b1a3b5d681e45f80559e8c333d3ba752111e64726b633491ed9

data/.github/PULL_REQUEST_TEMPLATE.md

@@ -2,21 +2,27 @@
 
 <!-- One or two sentences. What changes, and why. The "why" is the part that's hard to recover later. -->
 
-## Review preference
+## Linked issue / ADR
 
-Lowering friction is the whole point of this project. Pick whichever fits — defaults to the first if you don't tick anything.
+<!--
+Issue # this closes (or "none — drive-by fix").
+For non-trivial changes: which ADR(s) does this touch? If you skipped that step, write "no ADR" plus a one-line reason.
+-->
 
-- [ ] **Ship it.** Review for correctness, tests, and design fit. Skip style nits unless they're load-bearing.
-- [ ] **Full review, please.** Feedback on style, naming, idioms, and alternative designs welcome. I want the deep version, whether to learn the Ruby way or to stress-test a pattern I'm trying.
-
-## Working agreement check
+## Working agreement
 
 - [ ] Single concern (multi-concern PRs get bounced — see [CLAUDE.md](../CLAUDE.md))
-- [ ] ADRs touched: <!-- list ADR numbers, or "none" -->
 - [ ] `bin/rubocop` and `bin/rspec` pass locally
 - [ ] New behavior has a test; bug fix has a regression test
 - [ ] Async work goes through Rooibos Commands (no direct threads / `Async` / synchronous shellouts)
 
+## Test plan
+
+<!--
+How was this verified? Spec output, manual smoke, screenshots — whatever applies.
+"`bin/rspec` passes" is the floor, not a test plan.
+-->
+
 ## Notes for reviewer
 
-<!-- Tradeoffs, open questions, follow-ups — anything not obvious from the diff. -->
+<!-- Tradeoffs, open questions, follow-ups — anything not obvious from the diff. Delete the section if there's nothing to add. -->

data/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: Specs and Rubocop
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2"
+          bundler-cache: true
+
+      - name: Run specs
+        run: bin/rspec
+
+      - name: Run rubocop
+        run: bin/rubocop

data/.github/workflows/pr-template-check.yml

@@ -0,0 +1,100 @@
+name: PR template check
+
+# Verifies that PR descriptions include all required sections from
+# .github/PULL_REQUEST_TEMPLATE.md. Posts (or updates) a single comment
+# listing what's missing, and fails the check until the body is fixed.
+#
+# Security note: pull_request_target gives us write access to comment
+# back on the PR. We never check out PR HEAD; the body is read via the
+# event payload (data, not code).
+
+on:
+  pull_request_target:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  template-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Verify required sections
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+          PR_BODY: ${{ github.event.pull_request.body }}
+        run: |
+          set -euo pipefail
+
+          MARKER="<!-- pr-template-check -->"
+
+          # Required headings — must appear verbatim somewhere in the body.
+          required=(
+            "## Summary"
+            "## Linked issue / ADR"
+            "## Working agreement"
+            "## Test plan"
+          )
+          # "## Notes for reviewer" is intentionally optional — the template
+          # tells contributors to delete it when there's nothing to add.
+
+          missing=()
+          for heading in "${required[@]}"; do
+            if ! grep -Fq "$heading" <<< "${PR_BODY:-}"; then
+              missing+=("$heading")
+            fi
+          done
+
+          # Strip HTML comments and template placeholder text, then check
+          # the body has *some* substance. Catches PRs filed with the raw
+          # unmodified template.
+          stripped=$(printf '%s' "${PR_BODY:-}" | perl -0777 -pe 's/<!--.*?-->//gs')
+          # Drop heading lines and checklist scaffolding; what's left should
+          # be the contributor's own prose.
+          prose=$(printf '%s' "$stripped" | grep -Ev '^\s*(##|- \[[ x]\]|$)' || true)
+          prose_chars=$(printf '%s' "$prose" | tr -d '[:space:]' | wc -c | tr -d ' ')
+
+          # Find any prior bot comment so we can edit instead of stacking.
+          prior_id=$(gh api "repos/$REPO/issues/$PR_NUMBER/comments" \
+            --jq ".[] | select(.user.login == \"github-actions[bot]\" and (.body | contains(\"$MARKER\"))) | .id" \
+            | head -n1)
+
+          if [ ${#missing[@]} -eq 0 ] && [ "$prose_chars" -ge 40 ]; then
+            echo "PR body looks good."
+            if [ -n "$prior_id" ]; then
+              gh api -X PATCH "repos/$REPO/issues/comments/$prior_id" \
+                -f body="$MARKER
+✅ PR template check passed. Thanks for filling out the template."
+            fi
+            exit 0
+          fi
+
+          {
+            echo "$MARKER"
+            echo "👋 This PR is missing pieces from the [PR template](https://github.com/$REPO/blob/main/.github/PULL_REQUEST_TEMPLATE.md):"
+            echo ""
+            if [ ${#missing[@]} -gt 0 ]; then
+              echo "**Missing sections:**"
+              for m in "${missing[@]}"; do
+                echo "- \`$m\`"
+              done
+              echo ""
+            fi
+            if [ "$prose_chars" -lt 40 ]; then
+              echo "**Body looks unfilled** — the template comments are still there but no actual content has been written. Please fill in at least the Summary and Test plan."
+              echo ""
+            fi
+            echo "Edit the PR description (no new commit needed) and the check will re-run automatically. See [CLAUDE.md](https://github.com/$REPO/blob/main/CLAUDE.md) for why these sections matter."
+          } > /tmp/comment.md
+
+          if [ -n "$prior_id" ]; then
+            gh api -X PATCH "repos/$REPO/issues/comments/$prior_id" \
+              -F body=@/tmp/comment.md
+          else
+            gh pr comment "$PR_NUMBER" --repo "$REPO" --body-file /tmp/comment.md
+          fi
+
+          echo "::error::PR template is incomplete — see the bot comment on the PR."
+          exit 1

data/.github/workflows/release.yml

@@ -0,0 +1,71 @@
+name: Release
+
+# Triggers on `v*` tag pushes (e.g. `v0.4.0`). Verifies the tag matches
+# `GemContribute::VERSION` and that CHANGELOG.md has a dated section for
+# it, then runs rubocop + rspec as a final gate and publishes to
+# rubygems.org via Trusted Publishing (OIDC). No `RUBYGEMS_API_KEY`
+# secret — the rubygems.org-side trusted-publisher entry mints a
+# short-lived token from the GitHub Actions OIDC claim. Compatible with
+# `rubygems_mfa_required = true`, which the gemspec already sets.
+#
+# First-run setup (one-time, before the first tag push): see
+# MAINTAINER.md → "Cutting a release". The rubygems.org Trusted
+# Publisher entry must exist before this workflow can succeed.
+#
+# The `release` environment scopes the OIDC claim — only workflow runs
+# in that environment can authenticate to rubygems.org. Configure it at
+# Settings → Environments in the GitHub repo (no secrets, no protection
+# rules required, but adding a "required reviewer" gives a manual
+# approval gate before publishes).
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write   # create the GitHub release with auto-generated notes
+  id-token: write   # request OIDC token for Trusted Publishing
+
+jobs:
+  release:
+    name: Build, test, and publish
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2"
+          bundler-cache: true
+
+      - name: Verify tag matches gemspec version and CHANGELOG section
+        env:
+          REF_NAME: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          tag_version="${REF_NAME#v}"
+          gem_version=$(ruby -r./lib/gem_contribute/version -e 'print GemContribute::VERSION')
+
+          if [ "$tag_version" != "$gem_version" ]; then
+            echo "::error::Tag $REF_NAME does not match GemContribute::VERSION ($gem_version)."
+            echo "Bump lib/gem_contribute/version.rb or retag, then push."
+            exit 1
+          fi
+
+          if ! grep -Fq "## [$gem_version]" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md is missing a '## [$gem_version]' section."
+            echo "Add a dated section before tagging — see existing entries for the shape."
+            exit 1
+          fi
+
+      - name: rubocop
+        run: bin/rubocop
+
+      - name: rspec
+        run: bin/rspec
+
+      - name: Publish to rubygems.org via Trusted Publishing
+        uses: rubygems/release-gem@v1

data/CHANGELOG.md

@@ -4,6 +4,44 @@ All notable changes to this project will be documented here. The format is based
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-05-04
+
+### Added
+
+- Release workflow (`.github/workflows/release.yml`) — `v*` tag push triggers a publish to rubygems.org via [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) (OIDC). No `RUBYGEMS_API_KEY` secret involved; rubygems.org issues a short-lived token from the GitHub Actions OIDC claim. The workflow verifies the tag matches `GemContribute::VERSION` and that `CHANGELOG.md` has a dated section for it before running rubocop, rspec, and the publish step. First-time setup (rubygems.org pending-trusted-publisher entry, `release` GitHub Environment) is documented in `MAINTAINER.md` (closes [#44](https://github.com/cdhagmann/gem-contribute/issues/44)).
+
+### Fixed
+
+- `Gemfile.lock` regenerated to match `GemContribute::VERSION` after the 0.3.0 bump (commit `077eadb`) updated `version.rb` without running `bundle install`. CI runs bundler in deployment mode and was failing on the lockfile/gemspec mismatch. The MAINTAINER.md per-release checklist now calls out `bundle install` as an explicit step so the next bump doesn't repeat this.
+
+## [0.3.0] - 2026-05-04
+
+### Added
+
+- `gem-contribute fork <gem>` — the look-around-first counterpart to `fix`: fork the gem's repo, clone it, leave you on the default branch with no issue-tied work yet. Same `-e` / `-a` flags. Use this when you want to read the code before deciding whether to commit to a specific issue (closes [#12](https://github.com/cdhagmann/gem-contribute/issues/12)).
+- `gem-contribute fix -e` opens your editor in the clone directory after fork/clone/branch. Uses the new `editor` config key, falling back to `$EDITOR` (closes [#14](https://github.com/cdhagmann/gem-contribute/issues/14)).
+- `gem-contribute fix -a` launches your configured AI coding tool (new `ai_tool` config key) with the clone directory as cwd. Combine with `-e` to open both — editor first, AI tool second (closes [#14](https://github.com/cdhagmann/gem-contribute/issues/14)).
+- `gem-contribute fix` posts a "👋 I've started working on this" comment to the issue by default so other contributors don't double up on the same work. Opt out per-invocation with `--no-comment`, globally with `comment_on_fix: false` in config, or per-repo via `comment_on_fix_overrides` (YAML-only). Posting is soft-fail — the fork/clone/branch part still succeeds even if the comment can't be posted (closes [#18](https://github.com/cdhagmann/gem-contribute/issues/18)).
+- `scan` appends `· N claimed` to project lines whose open issues have already been claimed via the working-on-this marker, so you can spot already-in-progress work at a glance (closes [#20](https://github.com/cdhagmann/gem-contribute/issues/20)).
+- `issues <gem|all>` prefixes claimed issues with `[claimed]` for the same reason (closes [#20](https://github.com/cdhagmann/gem-contribute/issues/20)).
+- Long-running CLI operations (`fix`'s fork → clone → branch pipeline; `submit`'s `git push`) now show a tty-spinner in interactive terminals. Non-TTY contexts (CI, piped output, redirected stderr) fall back to plain status lines — no behavior change for scripted use (closes [#30](https://github.com/cdhagmann/gem-contribute/issues/30)).
+
+### Changed
+
+- `gem-contribute init` reads input through `tty-prompt`. Cosmetic side effect: default values are now displayed in parens — `(~/code/oss)` — instead of brackets — `[~/code/oss]` — matching tty-prompt's convention. Y/n parsing is now built-in instead of hand-rolled (closes [#31](https://github.com/cdhagmann/gem-contribute/issues/31)).
+- Internal class `ForkCloneBranch` renamed to `Fix` (the long name was cumbersome and didn't mirror the `fix` CLI verb). User-facing CLI surface unchanged.
+- Internal architecture: `HostAdapter` now owns every host-API verb (`fork`, `comment`, `pull_request_url`) plus host-specific URL templating (`clone_url`, `repo_url`); the new `Operations::Fork` / `Operations::Clone` primitives compose those with `Git`; `CLI::Fork` and `CLI::Fix` are thin compositions on top. The fork-readiness polling moved into the adapter — multi-host adapters can model readiness however the host actually works. See [ADR-0011](docs/adr/0011-host-adapter-owns-host-verbs.md). User-facing CLI surface unchanged.
+- Internal architecture (ADR-0012 Phase 1): `Operations::*` classes are now output-free and return `dry-monads` `Success` / `Failure` `Result` types; new `Operations::Branch` and `Operations::Announce` primitives; `Operations::FixPipeline` composes Fork → Clone → Branch → Announce via `dry-operation`; `Workflow#build_adapter` returns a `Result` and the old `with_workflow_rescues` rescue chain is gone; `CLI::Fork` / `CLI::Fix` initializers use `dry-initializer`. See [ADR-0012](docs/adr/0012-output-free-service-objects-three-interface-architecture.md). User-facing CLI surface unchanged.
+- Internal architecture (ADR-0012 Phase 2): every CLI verb writes through a semantic `Output::Standard` (or `Output::Null` in tests) abstraction — `#info`, `#progress`, `#warn`, `#error` — instead of raw `@stdout.puts` / `@stderr.puts`. `#progress` accepts an optional block and wraps a `tty-spinner` in TTY contexts. Existing constructors still accept `stdout:` / `stderr:` and auto-wrap them, so test suites injecting StringIO streams keep working unchanged. New deps: `tty-spinner ~> 0.9`, `tty-prompt ~> 0.23` (both pure-Ruby) (closes [#29](https://github.com/cdhagmann/gem-contribute/issues/29)).
+
+### Removed
+
+- The `fork-clone-branch` CLI alias has been removed. Use `gem-contribute fix` instead — same behavior, shorter to type.
+
+### Fixed
+
+- `gem-contribute fork` no longer prints `cd <path> && explore` — `explore` was meant as English but read as a (non-existent) shell command, so a copy-paste produced `command not found`. The "Next:" hint is now conditional on `-e` / `-a`: with neither flag it suggests `cd <path> && $EDITOR .`; with either flag it skips the directory step (you're already in your editor) and just points at the `fix` command.
+
 ## [0.2.0] - 2026-05-02
 
 ### Added

data/CLAUDE.md

@@ -4,7 +4,7 @@ This file is read by Claude Code when working in this repository. Treat it as th
 
 ## Project shape
 
-`gem-contribute` is a terminal UI that reads a project's `Gemfile.lock`, surfaces open contributable issues from the gems' source repositories, and offers one-keystroke fork-clone-branch.
+`gem-contribute` is a terminal UI that reads a project's `Gemfile.lock`, surfaces open contributable issues from the gems' source repositories, and offers a one-keystroke `fix` flow.
 
 Read `docs/design.md` and the ADRs in `docs/adr/` before making non-trivial changes. The design doc describes the architecture and the ADRs explain why specific decisions were made. If a change conflicts with an ADR, propose updating the ADR first; don't silently violate it.
 

data/CONTRIBUTING.md

@@ -6,11 +6,17 @@ Thanks for considering a contribution. This project is *about* lowering the fric
 
 ```
 gem install gem-contribute
-gem-contribute init                       # set clone_root and auth with GitHub
-gem-contribute fix gem-contribute/issue-5
+gem-contribute init                          # set clone_root and auth with GitHub
+gem-contribute fork gem-contribute           # fork + clone; lands on the default branch
 bundle install
-bin/rspec               # tests should pass on a clean checkout
-bin/gem-contribute      # tool should run against this repo's own Gemfile.lock
+bin/rspec                                    # tests should pass on a clean checkout
+bin/gem-contribute                           # tool should run against this repo's own Gemfile.lock
+```
+
+Once you've picked an issue to work on, branch off the default with `fix`:
+
+```
+gem-contribute fix gem-contribute/<issue#>   # creates gem-contribute/issue-<N> off the default branch
 ```
 
 ## What we welcome

data/MAINTAINER.md

@@ -86,7 +86,124 @@ older gem versions continue to work.
 
 ## Cutting a release
 
-(Stub — fill in when we cut v0.1.0 to RubyGems. Notes will live here:
-gemspec metadata checks, `bundle exec rake release` flow, signing, etc.)
+Releases publish to rubygems.org via [Trusted Publishing][gh-trusted-pub]
+(OIDC) — there is no `RUBYGEMS_API_KEY` secret and no manual `gem push`.
+A `v*` tag push triggers `.github/workflows/release.yml`, which verifies
+the tag matches `GemContribute::VERSION`, checks that `CHANGELOG.md` has a
+dated section for the version, runs rubocop and rspec, and then publishes.
+
+### One-time setup (before the first automated release)
+
+The rubygems.org Trusted Publisher entry must exist before any tag push
+can succeed. For an unclaimed gem name, use the **pending publisher**
+flow:
+
+1. Sign in at <https://rubygems.org>.
+
+2. Go to <https://rubygems.org/profile/me/oidc/pending_trusted_publishers/new>.
+
+3. Fill in the form:
+
+   | Field             | Value                |
+   |-------------------|----------------------|
+   | Gem name          | `gem-contribute`     |
+   | Repository owner  | `cdhagmann`          |
+   | Repository name   | `gem-contribute`     |
+   | Workflow filename | `release.yml`        |
+   | Environment       | `release`            |
+
+   The "Environment" value matches `environment: release` in the
+   workflow. Leave blank if you removed that line; otherwise both must
+   match exactly.
+
+4. Submit. The publisher entry is now "pending" — it has no gem attached
+   yet. The first successful publish from this workflow claims the name
+   and promotes the entry to a regular trusted publisher.
+
+After the gem is published, you can add additional trusted publishers
+(e.g. for a fork or replacement workflow) from the gem's settings page on
+rubygems.org instead of the pending-publisher flow.
+
+### Configure the GitHub environment (one-time)
+
+The workflow runs in an `environment: release` job. Create the environment
+in the repo so the OIDC claim carries the correct value:
+
+1. GitHub repo → Settings → Environments → **New environment**.
+2. Name it `release`.
+3. (Optional) Add yourself as a **Required reviewer** for a manual
+   approval gate before each publish. Recommended for the first few
+   releases until you trust the workflow.
+4. No secrets to configure. Trusted publishing replaces secrets entirely.
+
+### Per-release checklist
+
+When cutting a new version:
+
+1. **Bump the version.** Edit `lib/gem_contribute/version.rb` to the new
+   `MAJOR.MINOR.PATCH`. Follow [SemVer](https://semver.org/).
+
+2. **Regenerate `Gemfile.lock`.** Run `bundle install`. The lockfile's
+   `gem-contribute (X.Y.Z)` line must match the new version in both the
+   PATH spec at the top and the CHECKSUMS section near the bottom. CI
+   runs bundler in deployment/`--frozen` mode and refuses to install if
+   the lockfile is out of sync with the gemspec.
+
+3. **Update CHANGELOG.md.** Move the contents of `[Unreleased]` into a
+   new dated section: `## [X.Y.Z] - YYYY-MM-DD`. Leave `[Unreleased]`
+   empty for the next cycle. The release workflow refuses to publish if
+   it can't find a `## [X.Y.Z]` section matching the tag.
+
+4. **Commit on `main`.** Bump version.rb, the regenerated Gemfile.lock,
+   and CHANGELOG.md all in the same commit. Conventional message:
+   `Bump gem-contribute to X.Y.Z`.
+
+5. **Tag and push.**
+
+   ```sh
+   git tag -a vX.Y.Z -m "X.Y.Z"
+   git push origin main vX.Y.Z
+   ```
+
+6. **Watch the Actions tab.** The workflow will:
+   - verify the tag/version/CHANGELOG match
+   - run rubocop and rspec
+   - request an OIDC token, exchange it for a short-lived rubygems API
+     key, and publish the gem
+   - create a draft GitHub release with auto-generated notes
+
+   If the environment has a required-reviewer protection rule, the
+   workflow will pause for your manual approval before the publish step.
+
+7. **Sanity check.** After publish, `gem info gem-contribute` should show
+   the new version. The draft GitHub release is yours to edit and publish
+   when ready.
+
+### Troubleshooting
+
+- **"Tag … does not match GemContribute::VERSION"** — version.rb is out of
+  sync with the tag. Either delete the tag and bump version.rb, or
+  re-tag at the right SHA after fixing version.rb.
+- **"CHANGELOG.md is missing a section for …"** — add the dated section,
+  amend the bump commit, force-push, delete the old tag, retag, push.
+  (Force-push is fine on the bump commit before the publish has
+  succeeded.)
+- **OIDC failure / "no trusted publisher matches"** — check the
+  rubygems.org publisher entry: gem name, repo owner, repo name,
+  workflow filename (`release.yml`, not the full path), and environment
+  must all match. The workflow filename is the basename only, no
+  `.github/workflows/` prefix.
+- **`gem push` fails with `multifactor authentication required`** —
+  trusted publishing satisfies MFA. If you see this error, the workflow
+  fell back to a non-OIDC path; verify `permissions.id-token: write` is
+  set on the job.
+
+### Yanking a release
+
+Yanks happen via the rubygems.org web UI or `gem yank gem-contribute -v
+X.Y.Z`. There is no automated yank flow — by design. If you need to yank,
+also delete the corresponding `vX.Y.Z` tag and GitHub release so the
+record on GitHub matches what's available on rubygems.org.
 
 [gh-device-flow]: https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow
+[gh-trusted-pub]: https://guides.rubygems.org/trusted-publishing/

data/README.md

@@ -1,5 +1,7 @@
 # gem-contribute
 
+[![CI](https://github.com/cdhagmann/gem-contribute/actions/workflows/ci.yml/badge.svg)](https://github.com/cdhagmann/gem-contribute/actions/workflows/ci.yml)
+
 Find contributable issues in the gems your project already depends on.
 
 ```
@@ -39,7 +41,8 @@ gem-contribute init                   One-time interactive setup (sets clone_roo
 gem-contribute scan [path]            Summarize the contributable surface of a Gemfile.lock.
 gem-contribute issues <gem|all>       List "good first issue" issues for one gem (or all).
 gem-contribute auth login             Authenticate with GitHub via OAuth device flow.
-gem-contribute fix <gem>/<issue#>     Fork the gem's repo, clone the fork, branch from main.
+gem-contribute fork <gem|owner/repo>  Fork and clone any GitHub repo, land on the default branch.
+gem-contribute fix <gem>/<issue#>     Fork, clone, and branch from main for a specific issue.
 gem-contribute submit                 Push the branch and open a pre-filled PR in the browser.
 gem-contribute config set <key> <val> Persist user preferences (e.g. clone_root).
 ```
@@ -56,6 +59,15 @@ $ cd ~/code/oss/rubocop/rubocop          # whatever clone_root you set during in
 $ gem-contribute submit                  # push + open the PR compare page in your browser
 ```
 
+Or, when you want to look around a project before picking an issue, use `fork`:
+
+```sh
+$ gem-contribute fork rubocop                       # fork-and-clone a gem by name
+$ gem-contribute fork rubyevents/rubyevents -e      # fork-and-clone any GitHub repo and open your editor
+```
+
+`fork` does the same fork-clone-upstream sequence as `fix` but stops on the default branch — no issue branch, no comment. Handy for "build it locally and decide what to fix later." When you've picked an issue, `gem-contribute fix <gem>/<issue#>` branches off cleanly.
+
 The auth step (run automatically by `init`, or directly via `gem-contribute auth login`) opens GitHub's device-flow page in your browser and copies the one-time code to your clipboard — same UX as `gh auth login`, no token paste, no client secret. Tokens cache at `~/.config/gem-contribute/auth.json` (mode 0600).
 
 ## Configuration

data/docs/OPEN_QUESTIONS.md

@@ -0,0 +1,167 @@
+# Open Questions — Roadmap to v1
+
+Working list of unresolved planning questions for the v1 roadmap (TUI + CLI + `bundle contribute` + `gem contribute`). Walked through one at a time with the maintainer; each gets crossed off and folded into the ROADMAP / ADRs as it's answered.
+
+Order is rough priority — top items block downstream design, bottom items are polish.
+
+---
+
+## Q1. ~~What is the "world map view"?~~ — ANSWERED 2026-05-03
+
+A near-easter-egg view showing the locations of people who've kicked the tires on `gem-contribute`. Tracked as [issue #5](https://github.com/cdhagmann/gem-contribute/issues/5). Not a primary fragment — a hidden/discoverable view.
+
+**Implications this surfaces:**
+- Requires some form of opt-in usage reporting (the tool has to phone home with *something* to populate the map). New component: a tire-kicker reporting backend.
+- Privacy/consent UX needs to live somewhere — likely first-run prompt or `init` flow.
+- Backend service is itself a v1 dependency *if* the map ships in v1.
+
+→ See **Q1a** below.
+
+---
+
+## Q1a. ~~Does the world map ship in v1?~~ — ANSWERED 2026-05-03
+
+No. Preserving the option by choosing Rooibos now; tire-kicker map waits until there's enough adoption to make the data interesting. No backend work in v1 scope.
+
+**ADR-0013 reasoning lock-in:**
+1. Workshop onboarding cost — the main argument for bubbletea — is no longer a constraint (workshop ended 2026-05-02)
+2. Preserving the world map view (issue #5) as a future option
+3. ADR-0008's original technical reasoning still stands (Command primitives matched our verbs, snapshot test helpers, fractal Router architecture)
+4. Bubbletea-ruby's testing story was unverified per ADR-0010; Rooibos shipped tested helpers
+
+---
+
+## Q2. ~~Packaging shape~~ — ANSWERED 2026-05-03
+
+One gem. `gem-contribute` ships the standalone CLI, the Bundler plugin hooks, and the RubyGems plugin hooks all together. ADR-0012's mention of a future `rubygems-contribute` gem is overridden by ADR-0014 (the new plugin ADR).
+
+---
+
+## Q3. ~~What do `bundle contribute` / `gem contribute` do?~~ — ANSWERED 2026-05-03
+
+CLI only — no TUI from the plugins. Reasoning: Bundler and RubyGems plugins aren't typically interactive; they're CLI subcommands. The TUI is a property of the standalone `gem-contribute` binary.
+
+- `gem-contribute` (no args) → TUI
+- `bundle contribute` (no args) → CLI default (`scan` or `list all` — see **Q3a**)
+- `gem contribute` (no args) → CLI default (same)
+- `<any>` `<verb>` → CLI verb
+
+**Architectural consequence:** the plugin entry points never need to load Rooibos. Keeps plugin install lightweight.
+
+---
+
+## Q3a. Bare-call default for the plugins: `scan` or `list all`?
+
+User flagged as undecided. Both are read-only summary actions; difference is granularity and verbosity.
+
+- **`scan`** — current verb; prints the summary table (`47 gems · 44 on github.com · 2 on gitlab.com · …`) plus top contributable projects by issue count. Hits the network for the issue counts (cached).
+- **`list all`** — would presumably print every gem with its resolved source. Less network, more data, less curated.
+
+No urgency to pick — can be deferred to Phase 4. Worth deciding alongside the verb taxonomy review (does `list` exist as a separate verb? sub-verbs of `list`?).
+
+---
+
+## Q4. ~~Default behavior of bare `gem-contribute`~~ — ANSWERED 2026-05-03
+
+Packwerk-style launcher: `gem-contribute` (no args) opens a mini TUI that lists subcommands; arrow keys + enter pick one. `gem-contribute <verb>` runs the verb directly with no TUI in the way.
+
+→ See **Q4a**: this reframes what the "full TUI" is.
+
+---
+
+## Q4a. ~~What happens to the design.md "full TUI"?~~ — ANSWERED 2026-05-03
+
+Bare `gem-contribute` launches the design.md four-fragment TUI (ProjectList → IssueList → IssueDetail → ContributingViewer + AuthOverlay + the eventual WorldMap). The packwerk reference was establishing "yes, raw command launches a TUI" as precedent — not a directive to mirror packwerk's exact subcommand-picker shape. Subcommands stay CLI.
+
+Phase 3 of ROADMAP doesn't need rewriting; just confirm the entry-point wiring in `cli.rb` (no-arg → launch TUI vs print USAGE).
+
+---
+
+## Q5. ~~Multi-host adapters in v1?~~ — ANSWERED 2026-05-03
+
+GitHub-only at v1.0. v1.x point releases will add adapters (GitLab, Codeberg, etc.). ADR-0011's architecture is the bet that paying off.
+
+---
+
+## Q6. ~~Does ADR-0012's dry-rb adoption survive the framework revert?~~ — ANSWERED 2026-05-03
+
+Yes. We need both a CLI and a TUI; output-free service objects with `Result` returns are what lets both consume the same service layer. ADR-0013 (Rooibos revert) doesn't touch ADR-0012.
+
+Sub-question on `dry-cli` adoption is **deferred to Phase 4/5** when the plugin entry points get wired — easier to decide once the plugin shape is concrete.
+
+---
+
+## Q7. Rooibos 0.7.x verification — ASSIGNED TO ME
+
+Pre-Phase-3 task (no user decision needed): confirm Rooibos's current version on rubygems.org, verify Command primitives still exist, verify snapshot test helpers still ship. Folded into ROADMAP Phase 3.
+
+---
+
+## Q8. ~~Workshop docs disposition~~ — MY CALL: archive
+
+Moving workshop-era docs (`workshop.md`, `talk/`, `workshop-issues/`, `prep-plan.md`) to `docs/archive/` in Phase 6. Preserves history without polluting the active doc surface. Flag if you'd rather delete or keep them in place.
+
+---
+
+## Q9. ~~Test framework + cassette policy~~ — MY CALL: keep design.md's strategy as-is
+
+RSpec, VCR cassettes committed, no formal coverage target (just "every public method, every Update branch"). Snapshot helpers come from Rooibos — verified in Q7. Flag if you want a different testing posture for v1.
+
+---
+
+## Q10. ~~v1 out-of-scope confirmation~~ — MY CALL: existing exclusions stand
+
+All ADR-mandated out-of-scope items remain out for v1.0:
+- Private repos / `repo` OAuth scope
+- PR creation from inside the TUI (browser-based stays per ADR-0011)
+- AI-anything
+- Label normalization
+- CONTRIBUTING parsing
+- Multi-host adapters (per Q5; v1.x territory)
+- World map view (per Q1a; post-v1)
+
+Flag if anything moves into v1.
+
+---
+
+## Q11. Branding / homepage — DEFER
+
+Pre-release polish; revisit during Phase 6.
+
+---
+
+## Q12. CHANGELOG.md / CONTRIBUTING.md / MAINTAINER.md — task list, not decision
+
+Folded into ROADMAP Phase 6. No decision needed.
+
+---
+
+## Q13. ~~OAuth App identity for v1 release~~ — ANSWERED 2026-05-03
+
+Stay on the personal-account OAuth App for v1.0. Migrate to a dedicated identity when rate limits actually bite. Pragmatic — fits the rest of the v1 scope (don't pay for problems we don't have yet).
+
+---
+
+## Q14. ~~CI / release automation~~ — ANSWERED 2026-05-03
+
+GitHub Actions, two workflows:
+
+**CI (`ci.yml`)** — runs on push/PR:
+- rubocop
+- rspec
+- integration tests gated behind `GEM_CONTRIBUTE_INTEGRATION=1` (off by default)
+- smoke test: `bundle plugin install` + `gem install` on a clean Ruby image, verify both plugin entry points dispatch a verb
+
+**Release (`release.yml`)** — runs on `v*` tag push:
+- **Trusted Publishing via OIDC.** No API key stored as a secret; rubygems.org issues a short-lived token from the GitHub Actions OIDC claim. Compatible with `rubygems_mfa_required = true` (which the gemspec already sets).
+- Setup: configure a trusted publisher entry on rubygems.org (gem name + repo + workflow filename) before the first automated release.
+
+Multi-Ruby matrix and signed gems are post-v1.0 unless they become a real ask.
+
+---
+
+## Notes / parking lot
+
+- `docs/ideas.md` has one stray idea: "Make sure it respects PR templates" — file as a v1 issue.
+- `docs/index.md` and `docs/_config.yml` suggest a Jekyll site; not yet investigated.
+- `docs/claude-code-prompt.md` — not yet investigated.