@seanyao/roll 3.625.2 → 3.626.2

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## Unreleased
 
+## v3.626.2 — 2026-06-26
+
+### 自动化流水线
+
+- **调高 spec 里的 `est_min` 现在真能把卡送进更硬的档位了**：文档一直说「在故事 spec 里 bump `est_min` 就能升档（easy ≤8 / default 8–20 / hard >20）」，但路由器只读了 backlog 行上的 `est_min`，spec frontmatter 里的从没被喂进分档器——于是 `est_min: 24` 的卡始终落在 default 档。现在分档以 spec frontmatter 的 `est_min` 为准（spec 没写才回退到 backlog 行），文档承诺的升档手段终于生效。
+  Bumping `est_min` in a story spec now actually escalates it to a harder tier. The router only read the backlog row's `est_min` and ignored the spec frontmatter, so an `est_min: 24` card kept running on `default`. Tier selection now reads the spec frontmatter `est_min` first (falling back to the backlog row), so the documented escalation lever works. (FIX-1026) `[loop-engine]`
+- **loop 不再因为没开 VPN 就停摆**：纯国产工作流（kimi/pi/reasonix via DeepSeek、Bailian/DashScope embeddings）所有服务本就直连可达，但 loop/release 的连通性预检探的是固定海外主机（github.com），VPN 一关就误判「断网」并 halt——实测掉线后停摆过约 11 小时、零周期。现在可用 `loop_safety.probe_url` 把探测指向你真正需要的主机，或 `loop_safety.skip_network_check: true` 直接跳过预检；原来的 `proxy_enable_cmd` 恢复路径保留。
+  The loop no longer stalls just because the VPN is off. The loop/release connectivity precheck probed a fixed foreign host (github.com), so a dropped VPN was misread as "no network" and halted the loop (~11h of dead cycles observed) even though every configured domestic provider was directly reachable. Point the probe at a host you actually need via `loop_safety.probe_url`, or opt out with `loop_safety.skip_network_check: true`. (FIX-1025) `[loop-engine]`
+
+## v3.626.1 — 2026-06-26
+
+### 自动化流水线
+
+- **loop 再也不会弹 macOS 录屏授权了**：以前无人值守跑 loop 时会反复弹「请求录屏」授权框（甚至堆成一摞挡住屏幕），根因是判断「是否无人值守」用的 isTTY 被 loop 的 PTY（script+tmux）包装骗过了。现在 loop 在每个子进程显式关掉截屏探测，探测和真截屏两条路都认这个开关——你自己在终端跑 `roll attest --capture-web` 截图不受影响。(FIX-1022) `[loop-engine]`
+- **评分/配对只用你配置里允许的国产代理**：以前会自动启用机器上探测到的 codex/claude 来评分配对，既违反纯国产约束又白白失败。现在只认 `.roll/agents.yaml` 里声明的代理。(FIX-935) `[loop-engine]`
+- **loop 跳过有未发布本地改动的卡**：一张卡若本地还有没提交/没发布的工作，loop 先跳过它，不再覆盖或重复劳动。(FIX-1018) `[loop-engine]`
+- **推送前先体检仓库可推性**：加了仓库可推送性预检 + 暂停闸，推不动时不再硬来、空转。(FIX-1019) `[loop-engine]`
+- **`roll loop --help` 讲清三态**：help 里写明 ACTIVE / DORMANT / PAUSED 三态、休眠含义、三种唤醒方式。(US-LOOP-079m) `[loop-engine]`
+
+### 上手引导
+
+- **`roll init` 之后知道下一步该干嘛了**：当你手头有需求文档（PRD 之类）但 backlog 还是空的时候，`roll init` 收尾、`roll status`、`roll doctor` 三处都会提醒你去把需求变成可执行的 backlog——先做设计、再开 loop。(US-ONBOARD-NUDGE-002, US-ONBOARD-NUDGE-003) `[legacy-onboard]`
+- **一条命令就能开始设计**：敲 `roll design` 直接在你的 AI agent 里拉起交互式设计会话，把需求聊成 INVEST 故事写进 backlog。不用再自己记着「先去 agent 里加载哪个 skill」。(US-ONBOARD-NUDGE-004) `[legacy-onboard]`
+- **装完就能选默认 agent**：`roll setup` 不再静默替你选第一个 agent——如果你的机器装了多个 AI agent，setup 会问你用哪个当默认（非交互环境则按注册表顺序选第一个，确定性不出错）。选完存进 `primary_agent`，以后 `roll design`、`roll agent use` 这些交互入口默认就用它，不用每次都再选。重跑 setup 不再打扰——已有默认就静默跳过；想换默认用 `roll setup --reselect` 或 `roll agent use`。(US-ONBOARD-NUDGE-006) `[legacy-onboard]`
+- **文档收尾**：init→design 引导流程、`roll design` 命令入口、默认 agent 选择都已写进中英文档，不用再靠「本来就知道」。(US-ONBOARD-NUDGE-005) `[legacy-onboard]`
+- **新项目上手更清晰**：新项目流程改成「先建仓库、再 `roll init`」，并给出 epic 提示，少走弯路。(FIX-1020) `[legacy-onboard]`
+- **`roll init` 收尾有总结/确认，支持 `--auto`**：init 完成时给出「做了什么」的总结 + 确认；加 `--auto` 可非交互一把梭完成。(FIX-1021) `[legacy-onboard]`
+
 ## v3.625.2 — 2026-06-25
 
 ### 自动化流水线

package/README.md

@@ -32,13 +32,34 @@ Requirements: Node.js ≥ 22. Roll is a self-contained TypeScript CLI — no run
 
 ```bash
 cd your-project
-roll init           # set up Roll here
+roll init           # set up Roll here (interactive confirmation)
 roll loop on        # let AI work through the backlog (optional)
 ```
 
 `roll init` detects legacy code and routes you to `$roll-onboard` when appropriate.
+For a fresh project, it prints a project-type summary and asks for confirmation
+before creating files; pass `--auto` to skip the prompt in scripts and CI.
 First time through? Start with [Getting started](guide/en/getting-started.md).
 
+## Quick start for new projects
+
+A new project needs a remote before the loop can push branches and open PRs:
+
+```bash
+cd your-project
+roll init
+# 1. Create a GitHub repository for the project and add it as `origin`
+# 2. Push the current branch so the loop has somewhere to land work
+git push -u origin main
+# 3. Start the autonomous loop
+roll loop on
+```
+
+The loop will fail fast with an alert if the repository is missing or
+unreachable, so it never burns agent tokens against a broken push target.  If
+you need to stop the loop, `roll loop pause` persists a pause marker; resume
+with `roll loop resume` when ready.
+
 ## Commands
 
 | Command | Description |
@@ -60,6 +81,7 @@ First time through? Start with [Getting started](guide/en/getting-started.md).
 | `roll story new <ID> --title <t> [--epic <e>] [--no-index]` | The one minting entry agents/skills use: card folder + backlog row + index refresh (`--no-index` for batches) |
 | **Project · per repo** | |
 | `roll init` | Set up Roll in this project (agent-driven onboarding for legacy code) |
+| `roll design [--agent <name>]` | Launch `$roll-design` interactively to turn requirements into a domain model + INVEST backlog |
 | `roll offboard` | Remove Roll from this project |
 | `roll test [--where] [--reset]` | Run the test suite (routes through the isolation adapter; unknown types fail loud) |
 | `roll daemon <start\|stop\|status>` | Manage the read-only observability daemon (OPT-IN only; never auto-started) |