@seanyao/roll 4.702.2 → 4.702.4

package/guide/en/loop.md

@@ -213,6 +213,14 @@ bricked by a limit you set days ago. Scope (`--epic`/`--cards`) and `--review`
 still persist when unspecified, because they are the goal's identity, not a
 per-run safety knob.
 
+Before the first builder cycle, `roll loop go` also has a fallback check for
+leftover uncommitted Roll bootstrap artifacts such as `AGENTS.md`, `.claude/`,
+or `.roll/` metadata. Current `roll init` should already commit and push those
+Roll-owned files; if a historical or manual path still leaves only those files
+dirty, the goal pauses with `bootstrap_artifacts_unconfirmed` and prints the
+files to confirm. Commit or clean them, then run `roll loop go` again. This
+preflight does not start a cycle and does not count as no-progress.
+
 `roll loop go` enforces safety only at cycle boundaries. `--budget <usd>` uses
 the effective run cost ledger and moves the goal to `budget_limited` when the
 budget is reached. An idle or aborted cycle that ran no agent counts as a known

package/guide/en/project-setup.md

@@ -45,6 +45,13 @@ and apply an onboard plan, repair partial markers, run the old-layout migration,
 start the loop on the next Todo card, or inspect status when nothing is
 actionable.
 
+When a path writes Roll-owned meta files inside a git worktree, `roll init`
+finishes by adding, committing, and pushing those files to `origin` when
+possible. The finalize step is scoped to Roll-owned paths such as `AGENTS.md`,
+`.claude/CLAUDE.md`, `.roll/**`, and Roll-managed `.gitignore` entries; product
+source, PRDs, and other user files are left alone. If commit or push cannot be
+completed, init prints the manual command to run.
+
 Upgrading from a pre-2.0 layout (`BACKLOG.md` at root or `docs/features/`)?
 Run `npx @seanyao/roll@2 migrate` first — see
 [migration-2.0.md](migration-2.0.md). `roll init` will refuse to scaffold on top

package/guide/zh/loop.md

@@ -198,6 +198,12 @@ unknown，这类行仍按保守侧停止，不当作 0。用量闸检查 5 小
 不会让会话无限停摆；超时后 Roll 记录 `usage_wait_timeout` 审计事件并让 goal 保持暂停。
 `--for <duration>` 是墙钟时间盒：当前 cycle 收尾后，goal 以 `timebox` 原因暂停。
 
+启动第一个 builder cycle 前，`roll loop go` 还会兜底检查遗留未提交的 Roll bootstrap 产物，
+例如 `AGENTS.md`、`.claude/` 或 `.roll/` 元数据。新版 `roll init` 应该已经把这些
+Roll-owned 文件提交并推送；如果历史版本或手工路径仍然只留下这些脏文件，goal 会以
+`bootstrap_artifacts_unconfirmed` 暂停，并打印待确认文件。提交或清理后，再重新运行
+`roll loop go`。这个 preflight 不会启动 cycle，也不会累加 no-progress。
+
 每次安全闸触发都会记录 `goal:gate_tripped`，`roll loop goal` 会显示最近一次安全闸读数。
 
 ### `roll loop goal` 字段含义

package/guide/zh/project-setup.md

@@ -38,6 +38,12 @@ roll init
 从 brief 进入设计、审阅并 apply onboard plan、修复 partial 标记、执行旧布局迁移、
 对下一张 Todo 开 loop，或在没有可执行项时查看 status。
 
+当某条路径在 git worktree 中写入 Roll-owned meta 文件时，`roll init` 会在收尾阶段尽力
+把这些文件 add、commit 并 push 到 `origin`。这个 finalize 只覆盖 Roll 管理的路径，例如
+`AGENTS.md`、`.claude/CLAUDE.md`、`.roll/**` 和 Roll 自己追加的 `.gitignore` 条目；
+产品源码、PRD 和其他用户文件不会被顺手提交。若 commit 或 push 无法完成，init 会打印需要
+手动执行的命令。
+
 正在从 2.0 之前的布局升级（`BACKLOG.md` 在根目录或 `docs/features/`）？
 先跑 `npx @seanyao/roll@2 migrate` —— 见
 [migration-2.0.md](migration-2.0.md)。`roll init` 会拒绝在迁移到一半的

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanyao/roll",
-  "version": "4.702.2",
+  "version": "4.702.4",
   "description": "Roll — Roll out features with AI agents",
   "packageManager": "pnpm@11.1.3",
   "scripts": {