chore(v0.5): roadmap section + ship gh auth token fallback (#281) (#289)

* fix(ship): fall back to gh auth token (parity with parsec doctor) (#281)

parsec ship 이 PARSEC_GITHUB_TOKEN / GITHUB_TOKEN / GH_TOKEN env var 모두 비어있을 때
PR 생성을 거부했지만 parsec doctor 와 tracker 레이어는 이미 `gh auth token` fallback
적용. parity 깨져 사용자가 수동 `gh pr create` 로 추가 작업 필요.

해결:
- src/env.rs: github_token() 의 4번째 우선순위로 gh_auth_token() 추가. 신규
  gh_auth_token() helper 는 `gh auth token` shell out — 실패 시 None (binary 없음 /
  exit code != 0 / non-UTF8 / 빈 출력 모두 graceful).
- src/github/mod.rs: resolve_github_token 의 env-var/gh fallback 을 GitHub host
  (github.com / *.ghe.com / *.github.* GHE) 에만 적용. 신규 is_github_host() helper.
  Bitbucket / GitLab remote 가 `gh auth login` 한 환경에서 GitHub 토큰을 잘못 픽업하지
  않도록 가드.
- src/cli/commands/doctor.rs: 중복 `gh auth token` shell-out 코드 제거 → env::gh_auth_token()
  공통 helper 호출. parity at the helper level.

신규 테스트 (src/env.rs): github_token_priority_order — PARSEC > GITHUB > GH 우선순위
+ 빈값 fallback 4 시나리오 sequential 검사. EnvGuard 로 process-wide env 보존+복원.
gh_auth_token_returns_option_string_or_none — gh binary 가용성에 무관하게 trim 보장.
github_token_returns_none_when_all_missing_and_gh_fails — env 모두 미설정 시 None
또는 valid Some 모두 허용 (CI 와 dev 환경 양립).

검증:
- cargo test: 79 tests PASS (env tests 6 + integration 73)
- cargo clippy --all-targets -- -D warnings: clean
- cargo fmt --check: clean
- bitbucket integration tests: 5/5 PASS (이전 발견된 host-gated 이슈 해결)

회귀 위험: 매우 낮음
- 환경에 gh CLI 미로그인 / 미설치 → 기존과 동일 (None 반환)
- 환경에 gh 로그인됨 + GitHub remote → 신규 fallback 활용 (issue #281 의도)
- 환경에 gh 로그인됨 + Bitbucket/GitLab remote → is_github_host 로 차단, 기존과 동일

Closes #281

* docs(v0.5): open roadmap milestone — visualization release vision

v0.5 마일스톤 공식 출발 마커. README 와 CHANGELOG 양쪽에 향후 비전 명시.

README.md (## Roadmap 섹션 신설, ## Why use it 과 ## Install 사이):
- vision tagline: "parsec = AI agents + human devs both — worktree-native git CLI"
- 4단계 milestone:
  · v0.4.0 ✅ Released (2026-05-04): Multi-forge + multi-tracker foundation
  · v0.5 🚧 Next — _The visualization release_:
    smartlog · TUI dashboard · speculative merge · parsec test · AI PR descriptions
  · v1.0 🔜 — _AI-Native Standard_:
    MCP server signature, Claude/Cursor/Copilot 가 parsec 을 first-class tool 로 invoke
  · v2.0+ 🔮 — _Ecosystem Hub_: plugins · VS Code extension · Linear tracker
- v0.5 milestone link (github.com/erishforG/git-parsec/milestone/3)

CHANGELOG.md (## [Unreleased] 확장):
- ### Added: v0.5 milestone opened, README Roadmap 참조
- ### Fixed: #281 ship gh auth token fallback 노트 (별 commit ae1a2d3 와 동일 entry)

회귀 위험: 0 (문서 변경만)

* fix(env): serialize env-touching tests via process-wide mutex (Windows CI)

PR #289 Windows CI 1건 fail. macOS / Ubuntu Test 통과, Windows Test 만 실패.

원인:
- env::tests 의 github_token_priority_order 와 github_token_returns_none_when_all_
  missing_and_gh_fails 가 cargo test 병렬 실행 시 process-wide env vars 를 race.
- priority_order 가 PARSEC=p / GITHUB=g / GH=h 셋업 후 assert 사이에 sibling 테스트의
  EnvGuard::new() 가 모든 env 를 clear → assert 가 PARSEC 못 보고 GH=h 반환.
- macOS/Ubuntu 는 timing 우연히 안전, Windows 는 다른 thread scheduling 으로 race
  발현 (Some("h") vs Some("p") at src/env.rs:205).

수정:
- std::sync::OnceLock<Mutex<()>> 의 env_lock() 신규 — env 만지는 테스트들 직렬화.
  std 만 사용 (외부 deps 추가 X 제약 준수).
- github_token_priority_order 와 github_token_returns_none_when_all_missing_and_gh_fails
  를 단일 함수 github_token_priority_order_and_fallback 로 통합 + env_lock() 의
  Mutex guard 획득. 5 시나리오 (PARSEC 우선 / GITHUB / GH / 빈값 / 모두 미설정) 직렬 실행.
- gh_auth_token_returns_option_string_or_none 은 env 미터치라 lock 불필요 — 그대로 유지.
- production 로직 (env::github_token / env::gh_auth_token) 변경 0.

검증:
- 로컬 cargo test 78 PASS (env tests 5 + integration 73), clippy clean, fmt clean.
- Windows CI 검증은 force-push 후 PR #289 워크플로우에서 확인.

Author: erishforG

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **v0.5 milestone opened** — see Roadmap in README. Themes: smartlog · TUI
+  dashboard · speculative merge · `parsec test` · AI PR descriptions.
+
+### Fixed
+- `parsec ship` falls back to `gh auth token` when `PARSEC_GITHUB_TOKEN` /
+  `GITHUB_TOKEN` / `GH_TOKEN` env vars are absent — parity with `parsec
+  doctor` and the tracker layer (#281). The fallback is restricted to
+  GitHub hosts so Bitbucket / GitLab remotes are unaffected.
+
 ## [0.4.0] - 2026-05-04
 
 ### Added

README.md

@@ -29,6 +29,21 @@ That's the whole loop. Plain `git worktree` doesn't track state, doesn't talk to
 
 ---
 
+## Roadmap
+
+> **Vision**: parsec = AI agents + human devs both — worktree-native git CLI.
+
+| Milestone | Status | Theme |
+|---|---|---|
+| **v0.4.0** | ✅ Released (2026-05-04) | Multi-forge + multi-tracker foundation (GitHub / GitLab / Bitbucket; Jira / Linear) |
+| **v0.5** — _The visualization release_ | 🚧 Next | smartlog · TUI dashboard · speculative merge · `parsec test` · AI PR descriptions |
+| **v1.0** — _AI-Native Standard_ | 🔜 | MCP server signature — Claude / Cursor / Copilot invoke parsec as a first-class tool |
+| **v2.0+** — _Ecosystem Hub_ | 🔮 | Plugins · VS Code extension · Linear-native tracker · org-scale workflows |
+
+Open issues for v0.5 are tracked under the [`v0.5` milestone](https://github.com/erishforG/git-parsec/milestone/3).
+
+---
+
 ## Install
 
 ```bash

src/cli/commands/doctor.rs

@@ -86,15 +86,14 @@ pub async fn doctor(repo: &Path, mode: Mode) -> Result<()> {
     // ------------------------------------------------------------------
     {
         let config_result = crate::config::ParsecConfig::load();
+        // issue #281: gh auth token fallback 은 lib (`crate::env::gh_auth_token`) 에서
+        // 단일 정의 — `ship` / tracker 와 parity. doctor 는 SOURCE 를 사람이 읽기 위한
+        // 진단 메시지로 분기하므로 별도 매핑 유지.
+        let from_gh = crate::env::gh_auth_token().is_some();
+        let from_env = std::env::var("GITHUB_TOKEN").is_ok();
         let github_token_found = match &config_result {
             Ok(cfg) => {
                 let from_config = cfg.github.values().any(|h| h.token.is_some());
-                let from_env = std::env::var("GITHUB_TOKEN").is_ok();
-                let from_gh = StdCommand::new("gh")
-                    .args(["auth", "token"])
-                    .output()
-                    .map(|o| o.status.success())
-                    .unwrap_or(false);
                 if from_config {
                     Some("config file")
                 } else if from_env {
@@ -106,12 +105,6 @@ pub async fn doctor(repo: &Path, mode: Mode) -> Result<()> {
                 }
             }
             Err(_) => {
-                let from_env = std::env::var("GITHUB_TOKEN").is_ok();
-                let from_gh = StdCommand::new("gh")
-                    .args(["auth", "token"])
-                    .output()
-                    .map(|o| o.status.success())
-                    .unwrap_or(false);
                 if from_env {
                     Some("GITHUB_TOKEN env var")
                 } else if from_gh {

src/env.rs

@@ -47,7 +47,12 @@ pub fn jira_token(config_token: Option<&str>) -> Option<String> {
         .map(|t| t.to_string())
 }
 
-/// Resolve GitHub token. Priority: PARSEC_GITHUB_TOKEN > GITHUB_TOKEN > GH_TOKEN
+/// Resolve GitHub token. Priority:
+/// 1. `PARSEC_GITHUB_TOKEN`
+/// 2. `GITHUB_TOKEN`
+/// 3. `GH_TOKEN`
+/// 4. `gh auth token` shell fallback (issue #281 — parity with `parsec doctor` /
+///    tracker layer; `parsec ship` previously rejected this path)
 pub fn github_token() -> Option<String> {
     for var in [PARSEC_GITHUB_TOKEN, GITHUB_TOKEN, GH_TOKEN] {
         if let Ok(token) = std::env::var(var) {
@@ -56,7 +61,30 @@ pub fn github_token() -> Option<String> {
             }
         }
     }
-    None
+    gh_auth_token()
+}
+
+/// Shell out to `gh auth token` and capture stdout. Returns `None` on failure:
+/// binary not found, exit code != 0, non-UTF8 stdout, or empty token.
+///
+/// Used as the final fallback in [`github_token`] (issue #281 — parity with
+/// `parsec doctor` and the tracker layer). Cross-platform: relies on `gh`
+/// being on PATH; failures are silent so callers present a unified "no token
+/// found" message.
+pub fn gh_auth_token() -> Option<String> {
+    let out = std::process::Command::new("gh")
+        .args(["auth", "token"])
+        .output()
+        .ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    let token = String::from_utf8(out.stdout).ok()?.trim().to_string();
+    if token.is_empty() {
+        None
+    } else {
+        Some(token)
+    }
 }
 
 /// Resolve GitLab token. Priority: PARSEC_GITLAB_TOKEN > GITLAB_TOKEN
@@ -113,3 +141,129 @@ pub fn is_offline() -> bool {
         .map(|v| v == "1" || v == "true")
         .unwrap_or(false)
 }
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::{Mutex, OnceLock};
+
+    /// Process-wide mutex to serialize env-touching tests. cargo test runs
+    /// tests in parallel by default, so any test that mutates env vars must
+    /// hold this lock — otherwise sibling tests racing through `set_var` /
+    /// `remove_var` clobber each other (Windows CI hit this with priority_order
+    /// reading PARSEC=p but seeing GH=h because another test cleared PARSEC
+    /// mid-assertion).
+    fn env_lock() -> &'static Mutex<()> {
+        static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+        LOCK.get_or_init(|| Mutex::new(()))
+    }
+
+    /// Helper: snapshot/clear env vars affecting github_token, then restore.
+    /// std::env::set_var/remove_var is unsafe in Rust 2024. Tests holding
+    /// `env_lock()` only run serially, so the snapshot+restore is sufficient.
+    struct EnvGuard {
+        orig: Vec<(&'static str, Option<String>)>,
+    }
+    impl EnvGuard {
+        fn new(vars: &[&'static str]) -> Self {
+            let orig = vars.iter().map(|v| (*v, std::env::var(v).ok())).collect();
+            for v in vars {
+                // SAFETY: tests run serially within a module by default in Rust 2024.
+                #[allow(unused_unsafe)]
+                unsafe {
+                    std::env::remove_var(v)
+                };
+            }
+            Self { orig }
+        }
+        fn set(&self, key: &str, val: &str) {
+            #[allow(unused_unsafe)]
+            unsafe {
+                std::env::set_var(key, val)
+            };
+        }
+    }
+    impl Drop for EnvGuard {
+        fn drop(&mut self) {
+            for (k, v) in &self.orig {
+                #[allow(unused_unsafe)]
+                unsafe {
+                    if let Some(val) = v {
+                        std::env::set_var(k, val);
+                    } else {
+                        std::env::remove_var(k);
+                    }
+                }
+            }
+        }
+    }
+
+    /// 우선순위 + 빈값 fallback + 모두 미설정 시나리오를 한 함수에서 sequential 검사.
+    /// `env_lock()` 으로 process-wide 직렬화 (cargo test 병렬 실행 환경에서 sibling
+    /// 테스트가 env 를 클로버하지 않도록). Windows CI 에서 race 발견 (#289).
+    #[test]
+    fn github_token_priority_order_and_fallback() {
+        let _guard = env_lock().lock().unwrap_or_else(|p| p.into_inner());
+        // 1. PARSEC_GITHUB_TOKEN 우선
+        {
+            let g = EnvGuard::new(&[PARSEC_GITHUB_TOKEN, GITHUB_TOKEN, GH_TOKEN]);
+            g.set(PARSEC_GITHUB_TOKEN, "p");
+            g.set(GITHUB_TOKEN, "g");
+            g.set(GH_TOKEN, "h");
+            assert_eq!(github_token().as_deref(), Some("p"));
+            drop(g);
+        }
+        // 2. PARSEC_GITHUB_TOKEN 미설정 → GITHUB_TOKEN
+        {
+            let g = EnvGuard::new(&[PARSEC_GITHUB_TOKEN, GITHUB_TOKEN, GH_TOKEN]);
+            g.set(GITHUB_TOKEN, "g");
+            g.set(GH_TOKEN, "h");
+            assert_eq!(github_token().as_deref(), Some("g"));
+            drop(g);
+        }
+        // 3. PARSEC_GITHUB_TOKEN / GITHUB_TOKEN 미설정 → GH_TOKEN
+        {
+            let g = EnvGuard::new(&[PARSEC_GITHUB_TOKEN, GITHUB_TOKEN, GH_TOKEN]);
+            g.set(GH_TOKEN, "h");
+            assert_eq!(github_token().as_deref(), Some("h"));
+            drop(g);
+        }
+        // 4. 빈 PARSEC_GITHUB_TOKEN 은 무시 → GITHUB_TOKEN
+        {
+            let g = EnvGuard::new(&[PARSEC_GITHUB_TOKEN, GITHUB_TOKEN, GH_TOKEN]);
+            g.set(PARSEC_GITHUB_TOKEN, "");
+            g.set(GITHUB_TOKEN, "g");
+            assert_eq!(github_token().as_deref(), Some("g"));
+            drop(g);
+        }
+        // 5. 모두 미설정 + gh 실패 → None. CI 환경 (gh 로그인 X) 이 일반.
+        //    local dev 에서 gh auth login 돼있으면 Some(token) 도 허용 (smoke).
+        {
+            let g = EnvGuard::new(&[PARSEC_GITHUB_TOKEN, GITHUB_TOKEN, GH_TOKEN]);
+            match github_token() {
+                None => {}
+                Some(t) => assert!(
+                    !t.is_empty(),
+                    "if gh auth token is available, it must not be empty"
+                ),
+            }
+            drop(g);
+        }
+    }
+
+    #[test]
+    fn gh_auth_token_returns_option_string_or_none() {
+        // 외부 gh binary 에 의존 — CI 환경 (로그인 X) 에서는 None 기대.
+        // local dev 에서 gh auth login 돼있으면 Some(token). 둘 다 허용 (smoke check only).
+        match gh_auth_token() {
+            None => {}
+            Some(t) => {
+                assert!(!t.is_empty());
+                assert!(!t.contains('\n'), "trimmed");
+            }
+        }
+    }
+}

src/github/mod.rs

@@ -190,14 +190,25 @@ pub fn parse_github_remote(url: &str) -> Option<GitHubRemote> {
     })
 }
 
+/// Returns true when `host` looks like a GitHub host. github.com and any host
+/// with `.github.` (GHE) substring qualifies. Used to gate env-var and
+/// `gh auth token` fallbacks so they don't leak into other forges.
+pub fn is_github_host(host: &str) -> bool {
+    let h = host.trim().to_ascii_lowercase();
+    h == "github.com" || h.contains(".github.") || h.ends_with(".ghe.com")
+}
+
 /// Resolve a GitHub token for the given host.
 ///
 /// Resolution priority:
-/// 1. `config.github.<host>.token` — host-specific config
-/// 2. `PARSEC_GITHUB_TOKEN` env var — explicit override
-/// 3. `GITHUB_TOKEN` / `GH_TOKEN` — generic fallback
+/// 1. `config.github.<host>.token` — host-specific config (any host)
+/// 2. `PARSEC_GITHUB_TOKEN` / `GITHUB_TOKEN` / `GH_TOKEN` env vars (GitHub host only)
+/// 3. `gh auth token` shell fallback (GitHub host only) — issue #281 parity
+///
+/// 2 & 3 are gated on host being a GitHub host so that bitbucket / gitlab remotes
+/// don't accidentally pick up a GitHub token via `gh auth login`.
 pub fn resolve_github_token(host: &str, config: &ParsecConfig) -> Option<String> {
-    // 1. Host-specific config token
+    // 1. Host-specific config token (any host — opt-in via config)
     if let Some(host_cfg) = config.github.get(host) {
         if let Some(ref token) = host_cfg.token {
             if !token.is_empty() {
@@ -206,12 +217,11 @@ pub fn resolve_github_token(host: &str, config: &ParsecConfig) -> Option<String>
         }
     }
 
-    // 2 & 3. Environment variables (PARSEC_GITHUB_TOKEN > GITHUB_TOKEN > GH_TOKEN)
-    if let Some(token) = crate::env::github_token() {
-        return Some(token);
+    // 2 & 3: env / gh CLI fallback — only for actual GitHub hosts.
+    if !is_github_host(host) {
+        return None;
     }
-
-    None
+    crate::env::github_token()
 }
 
 // ---------------------------------------------------------------------------