@seanyao/roll 3.625.2 → 3.627.1

package/CHANGELOG.md

@@ -2,6 +2,62 @@
 
 ## Unreleased
 
+## v3.627.1 — 2026-06-27
+
+### 上手引导
+
+- **新拆的卡会带验收契约**：`roll design` 现在把预期证据和评分重点写进 story，交付和评审看同一份标准。(US-SKILL-030) `[skill-ecosystem]`
+  <!-- evidence: .roll/features/skill-ecosystem/US-SKILL-030/2026-06-27T02-11-16/US-SKILL-030-report.html -->
+- **`roll init` 会先分清项目类型**：PRD、空项目、已有代码库、partial Roll、旧布局和已就绪项目都会走不同下一步。(US-INIT-004, US-INIT-005, US-INIT-006a, US-INIT-009) `[legacy-onboard]`
+  <!-- evidence: .roll/features/init-onboard/US-INIT-004/latest/US-INIT-004-report.html -->
+  <!-- evidence: .roll/features/init-onboard/US-INIT-005/latest/US-INIT-005-report.html -->
+  <!-- evidence: .roll/features/init-onboard/US-INIT-006a/latest/US-INIT-006a-report.html -->
+- **已有代码库先诊断再应用**：`roll init` 先产诊断和计划，确认后再 `roll init --apply`，不会一上来改你的仓库。(US-INIT-006b, US-INIT-006c, US-INIT-006d) `[legacy-onboard]`
+  <!-- evidence: .roll/features/init-onboard/US-INIT-006b/latest/US-INIT-006b-report.html -->
+  <!-- evidence: .roll/features/init-onboard/US-INIT-006c/latest/US-INIT-006c-report.html -->
+  <!-- evidence: .roll/features/init-onboard/US-INIT-006d/latest/US-INIT-006d-report.html -->
+- **`roll init --apply` 可以放心重跑和退出**：重复执行会复用变更账本，`roll offboard` 只移除 Roll 管理的内容。(US-INIT-006e, US-INIT-006f) `[legacy-onboard]`
+  <!-- evidence: .roll/features/init-onboard/US-INIT-006e/latest/US-INIT-006e-report.html -->
+  <!-- evidence: .roll/features/init-onboard/US-INIT-006f/latest/US-INIT-006f-report.html -->
+- **`roll next` 成了上手流程的继续按钮**：init、onboard、repair、migrate、design 和下一张 Todo 都会收束到一个显然下一步。(US-INIT-007) `[legacy-onboard]`
+  <!-- evidence: .roll/features/init-onboard/US-INIT-007/latest/US-INIT-007-report.html -->
+- **文档、CLI help 和站点图现在讲同一条路**：README、指南、skill contract 和 `$roll-onboard` 图都改成“已有代码库”视角。(US-INIT-008) `[legacy-onboard]`
+  <!-- evidence: .roll/features/init-onboard/US-INIT-008/latest/US-INIT-008-report.html -->
+
+### 稳定性
+
+- **验收截图不再能伪造现场**：CLI 用 Terminal.app，站点图用真实浏览器窗口；无 GUI 或无权限时诚实跳过。(US-INIT-003d, US-INIT-008) `[acceptance-evidence]`
+  <!-- evidence: .roll/features/init-onboard/US-INIT-003d/latest/US-INIT-003d-report.html -->
+  <!-- evidence: .roll/features/init-onboard/US-INIT-008/latest/US-INIT-008-report.html -->
+
+## 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,47 @@ 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 next           # continue with design, apply, repair, migrate, loop, or status
 roll loop on        # let AI work through the backlog (optional)
 ```
 
-`roll init` detects legacy code and routes you to `$roll-onboard` when appropriate.
+`roll init` first diagnoses the current directory. Complete Roll projects get
+`Already initialized` and `Next: roll status`; partial Roll projects get
+`roll init --repair`, while pre-2.0 layouts get migration guidance without writing files. Existing codebases route to
+`$roll-onboard`. PRD/docs-only workspaces are treated as new projects: Roll writes
+`.roll/brief.md` from the detected document and points to `roll design --from-file`.
+Empty directories ask what you are building in an interactive terminal; in scripts
+and CI, plain `roll init` is read-only and `roll init --auto` writes a placeholder
+brief before pointing to `roll design`.
+For existing-codebase grafts, `roll init --apply` validates the generated
+artifacts, prints a review checkpoint with every planned file operation, and
+waits for owner confirmation before writing. Automation must use
+`roll init --apply --auto` after that review.
+After any init path, `roll next` is the continuation button: it reads the same
+brief, onboard plan, backlog, and Roll markers, then prints one best next
+command instead of a menu.
 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 |
@@ -52,14 +86,16 @@ First time through? Start with [Getting started](guide/en/getting-started.md).
 | `roll loop alert [list\|ack\|resolve\|log]` | View / clear loop alerts |
 | `roll status` | Verdict-first truth summary read from the ONE snapshot — LOOP · CYCLE · RELEASE · STORY, with the STORY line's attest-coverage % (`done ≡ merged ∧ attested`) — then convention/AI-client sync health |
 | `roll pulse [--json]` | Today's delivery pulse: cycles in window, merged count, attested count, plus an ASCII sparkline from the story spectrum. Bilingual EN/中. `--json` for machine-readable output |
-| `roll doctor [skills]` | Environment + install diagnosis (agents, skill catalog, plists, launchd lanes) |
+| `roll doctor [skills\|--tools]` | Environment + install diagnosis; `roll doctor --tools` shows focused tool and screenshot readiness, including Terminal.app Screen Recording |
 | `roll daemon <start\|stop\|status>` | Opt-in read-only observability daemon for the live console; defaults to `127.0.0.1:7077`, records `.roll/loop/daemon.pid`, and is never auto-started by the loop |
 | `roll tune [reset]` | Suggest-only self-tuning from loop trends — read-only, never auto-applies |
 | **Cards & evidence** | |
 | `roll idea "<one-sentence description>"` | Capture a card: auto-classify, number, lint, infer epic, mint the full story folder — the one user entry for adding cards |
 | `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 init` | Diagnose this directory and route to fresh scaffold, PRD/design handoff, existing-codebase onboard, repair, migration, or `roll status` |
+| `roll next` | Continue the init/onboard journey with one best next command: design, apply, repair, migrate, loop, or status |
+| `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) |