用途
gh-stack 用于借助 GitHub CLI 的 gh stack 扩展，管理 Cherry Studio 中呈线性依赖关系的堆叠分支与对应的堆叠式拉取请求。它关注分支拓扑与同步；而 PR 正文、Spec 审批、AC 覆盖、验证和 Agent Note 生命周期则由仓库的 gh-create-pr 技能处理。
可用性与前置条件
该公开技能记录在 .agents/skills/ 中并从仓库发现，开发者无需单独安装代理技能；pnpm skills:sync 维护 .claude/skills/ 的兼容符号链接。
任务中首次执行 gh stack 命令前需运行预检：确认已安装 GitHub CLI（否则提示 https://cli.github.com/ 并退出）、检查 gh auth status、若 gh stack --help 不可用则执行 gh extension install github/gh-stack，最后再次验证帮助命令。任一认证、安装或最终验证失败时应停止并报告失败命令，不得用临时分支比较猜测栈拓扑。初始化栈前可执行 git config rerere.enabled true 以避免扩展提示。存在多个远程时，应确定目标远程并在支持的命令上传入 --remote <name>，不得擅自修改 remote.pushDefault。
栈模型
栈是一条线性依赖链：最底部分支最接近主干，每个更高分支只包含依赖下一层的工作。例如 main -> spec -> implementation-core -> implementation-ui。创建分支前应先规划完整依赖顺序；新发现的底层改动应放在其所属分支上，再对上层分支执行 rebase，而不是隐藏在当前层。
代理安全命令
所有命令必须非交互：始终用 gh stack view --json（普通 view 会打开 TUI）；init、add、checkout 必须提供分支名；显式允许时才用 submit --auto；多远程时给 push、submit、sync、link 传 --remote；使用普通 git add 与 git commit -S --signoff 逐层暂存提交。常用命令包括：
- gh stack init --base main <bottom-branch> [<higher-branch>...]
- gh stack add <new-top-branch>
- gh stack view --json
- gh stack push --remote <remote>
- gh stack rebase --upstack --remote <remote>
- gh stack sync --remote <remote>
- gh stack checkout <branch-or-pr>
- gh stack link --remote <remote> <bottom-pr> <higher-pr> [...]
退出码处理
view --json 返回 2 仅表示当前检出无匹配的本地栈元数据，不证明已有 PR 在 GitHub 上是独立的；应在干净的一次性工作树中执行 gh stack checkout <pr-number-or-url> 发现远程拓扑后重跑 view --json，确认未关联 GitHub 栈后才判定为独立 PR。退出码 3 表示冲突，但恢复方式因命令而异：rebase 会留下活动恢复状态，解决冲突后运行 gh stack rebase --continue 或 --abort；sync 在返回前已回滚尝试的 rebase，需重新运行 gh stack rebase 解决冲突，除非有活动 rebase 否则不要用 --continue 或 --abort。退出码 9 表示仓库不可用 GitHub 堆叠 PR，应停止而非静默发布其他形态的 PR。
在 Cherry 中创建 PR
不要用 gh stack submit --auto 创建人工编写的 Cherry PR，因为它会在必需正文预览前创建 PR 并自动生成不符合仓库模板的正文。合规做法是自下而上：先用 gh stack push --remote <remote> 推送分支；对每层调用 gh-create-pr，以父分支为该层 base；所有 PR 标题与正文获批后，用 gh stack link --remote <remote> <bottom-pr> <higher-pr> [...] 关联已有 PR；最后用 gh stack view --json 验证拓扑。submit --auto 仅可用于明确授权、豁免人工 PR 模板的自动化流程。
修改现有栈
修改下层时：显式检出该分支，在其中完成并验证聚焦改动，运行 gh stack rebase --upstack --remote <remote>，再推送或同步栈。对每个被重写的在线 PR，重跑 pnpm change:scope --base <verified-parent-ref> 以及仅由该重写范围失效的检查。sync 后应检查输出并运行 view --json，命令成功本身不代表各 PR 的 base、范围或验证仍符合预期。
生命周期边界
Spec 审批与生命周期转换遵循 .agents/skills/agent-notes/SKILL.md。中间实现层保持 note 为 proposed；只有累积且实际运行的证据覆盖全部已批准 AC 的最终层，才能将双语 note 三元组移入 implemented/。
适用场景与限制
适用于使用 GitHub CLI 与 gh stack 扩展管理多层依赖分支和堆叠 PR 的开发流程。限制包括：需要已认证的 GitHub CLI 与可用扩展；仓库需支持 GitHub 堆叠 PR（否则退出码 9）；所有命令须非交互执行；Cherry 人工 PR 不可走 submit --auto 捷径。