@seanyao/roll 4.702.2 → 4.702.3

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## v4.702.3 — 2026-07-02
+
+### 稳定性
+- `roll init` 现在会负责提交并推送自己生成的项目约定文件，`roll loop go` 不再一开工就撞 dirty（FIX-1072）`[loop-engine]`
+- Builder 提交会被钉在 cycle worktree，不再把提交漏到主 checkout（FIX-1073）`[loop-engine]`
+- 状态面板给出的 AI client 修复命令现在可以直接执行，不再多带无效参数（FIX-1070）`[cli]`
+
+### 可见性
+- `roll loop watch` 不再把旧 cycle 的卡片和 agent 贴到新的空转或重试状态上（FIX-1074）`[loop-observability]`
+
 ## v4.702.2 — 2026-07-02
 
 ### Breaking changes

package/README.md

@@ -53,6 +53,10 @@ waits for owner confirmation before writing. Automation must use
 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.
+When `roll init` writes Roll-owned meta files inside a git worktree, it also
+adds, commits, and pushes those files to `origin` when possible, then prints the
+commit/push result. Product files you created yourself are not included in that
+finalization commit.
 First time through? Start with [Getting started](guide/en/getting-started.md).
 
 ## Language Surfaces
@@ -205,7 +209,7 @@ with `roll loop resume` when ready.
 | `roll loop <on\|off\|go\|watch\|runs\|cycles\|cycle\|alert\|…>` | Run, observe, and maintain the autonomous executor |
 | `roll next` | Continue init/onboard with one best next command |
 | `roll release [--dry-run\|--showcase]` | Release planning/flow plus golden-path showcase support |
-| `roll setup [skills\|offboard\|-f]` | Install/sync conventions or remove Roll-owned project artifacts |
+| `roll setup [-f\|--force] [--reselect]` / `roll setup skills\|offboard` | Install/sync conventions or remove Roll-owned project artifacts |
 | `roll status [ci\|pulse] [--json]` | Project health, CI state, and delivery pulse |
 | `roll test [--where] [--reset]` | Run tests through the isolation adapter |
 | `roll update` | Upgrade the global Roll install and re-sync conventions |

package/dist/roll.mjs

@@ -12475,6 +12475,12 @@ function signalLabel(ev) {
       return `pair ${clean2(ev.peer)} ${ev.cause}`;
     case "pair:excluded":
       return `pair ${clean2(ev.agent)} excluded ${ev.cause} (${ev.failures})`;
+    case "agent:retry":
+      return `retry ${clean2(ev.fromAgent)} \u2192 ${clean2(ev.toAgent)} (${clean2(ev.reason)})`;
+    case "goal:gate_tripped":
+      return `paused ${clean2(ev.reason)} (${ev.gate})`;
+    case "goal:state":
+      return `goal ${clean2(ev.to)} ${clean2(ev.reason)}`;
     default:
       return void 0;
   }
@@ -12486,6 +12492,20 @@ function summarizeWatchEvents(lines3, durableLookup, nowMs) {
   const summary = { tcrCount: 0, hasEnd: false };
   const events = [];
   let seen = false;
+  const resetCycleScope = (cycleId) => {
+    if (summary.cycleId === cycleId)
+      return;
+    summary.cycleId = cycleId;
+    summary.storyId = void 0;
+    summary.agent = void 0;
+    summary.phase = void 0;
+    summary.tcrCount = 0;
+    summary.outcome = void 0;
+    summary.hasEnd = false;
+    summary.acceptedScore = void 0;
+    summary.attest = void 0;
+    summary.lastPr = void 0;
+  };
   for (const line of lines3) {
     const ev = parseEventLine(line);
     if (ev === null)
@@ -12493,26 +12513,26 @@ function summarizeWatchEvents(lines3, durableLookup, nowMs) {
     events.push(ev);
     seen = true;
     if (ev.type === "cycle:start") {
-      summary.cycleId = ev.cycleId;
+      resetCycleScope(ev.cycleId);
       summary.storyId = ev.storyId;
       summary.agent = ev.agent;
-      summary.phase = void 0;
-      summary.tcrCount = 0;
-      summary.outcome = void 0;
-      summary.hasEnd = false;
-      summary.acceptedScore = void 0;
-      summary.attest = void 0;
-      summary.lastPr = void 0;
     } else if (ev.type === "cycle:phase") {
-      summary.cycleId = ev.cycleId;
+      resetCycleScope(ev.cycleId);
       summary.phase = ev.phase;
     } else if (ev.type === "cycle:tcr") {
-      summary.cycleId = ev.cycleId;
+      resetCycleScope(ev.cycleId);
       summary.tcrCount += 1;
-    } else if (ev.type === "cycle:end" || ev.type === "cycle:terminal") {
-      summary.cycleId = ev.cycleId;
+    } else if (ev.type === "cycle:end") {
+      resetCycleScope(ev.cycleId);
+      summary.outcome = ev.outcome;
+      summary.hasEnd = true;
+    } else if (ev.type === "cycle:terminal") {
+      resetCycleScope(ev.cycleId);
+      summary.storyId = ev.storyId;
+      summary.agent = ev.agent;
       summary.outcome = ev.outcome;
       summary.hasEnd = true;
+      summary.tcrCount = ev.tcr.present ? ev.tcr.value : 0;
     }
     if (ev.type === "pair:score") {
       summary.acceptedScore = { peer: ev.peer, score: ev.score, verdict: ev.verdict };
@@ -12584,7 +12604,7 @@ function renderWatchStatusSummary(summary, nowMs) {
   const story = summary.storyId !== void 0 && summary.storyId !== "" ? summary.storyId : "story unknown";
   const agent = summary.agent !== void 0 && summary.agent !== "" ? summary.agent : "agent unknown";
   const phase = summary.phase !== void 0 ? `phase ${summary.phase}` : "phase unknown";
-  const classification = summary.classification !== void 0 ? summary.classification : "active";
+  const classification = summary.classification !== void 0 ? summary.classification : summary.hasEnd ? "ended" : "active";
   const tcr = `${summary.tcrCount} TCR`;
   const parts = [`status  ${phase}`, classification, quietText(summary, nowMs), story, agent, cycle];
   if (summary.microStep !== void 0) {
@@ -12656,11 +12676,18 @@ function previousTransitionLine(previous) {
   return `  previous: ${parts.join(" \xB7 ")}`;
 }
 function nextTransitionLine(current, ctx) {
+  if (current.storyId === void 0 || current.storyId === "") {
+    const outcome = current.hasEnd ? current.outcome ?? "unknown" : "no active story";
+    return `  next:     no runnable work \xB7 ${outcome}`;
+  }
   const story = current.storyId !== void 0 && current.storyId !== "" ? current.storyId : "story unknown";
   const brief = current.storyId !== void 0 && current.storyId !== "" ? ctx?.storyBrief?.(current.storyId) ?? "brief unavailable" : "brief unavailable";
   return `  next:     ${story} \xB7 ${brief}`;
 }
 function builderTransitionLine(current, ctx) {
+  if (current.storyId === void 0 || current.storyId === "") {
+    return "  builder:  none \xB7 no story/agent selected";
+  }
   const route = current.storyId !== void 0 && current.storyId !== "" ? ctx?.routeReason?.(current.storyId) : void 0;
   if (route !== void 0) {
     return `  builder:  ${route.agent} \xB7 selected by ${route.reason}`;
@@ -18793,16 +18820,16 @@ async function crontabRead() {
   }
 }
 async function crontabWrite(text2) {
-  return new Promise((resolve11, reject) => {
+  return new Promise((resolve12, reject) => {
     const child = execFile4("crontab", ["-"], (err16) => {
       if (err16 === null) {
-        resolve11(0);
+        resolve12(0);
       } else if (typeof err16.code === "number") {
-        resolve11(err16.code);
+        resolve12(err16.code);
       } else if (err16.code === "ENOENT") {
         reject(err16);
       } else {
-        resolve11(1);
+        resolve12(1);
       }
     });
     child.stdin?.end(text2);
@@ -20846,14 +20873,14 @@ var init_mcp = __esm({
         child.on("exit", () => this.rejectAll(new Error("MCP server exited")));
       }
       static async open(child) {
-        await new Promise((resolve11, reject) => {
+        await new Promise((resolve12, reject) => {
           const onError = (cause) => {
             child.off("spawn", onSpawn);
             reject(cause);
           };
           const onSpawn = () => {
             child.off("error", onError);
-            resolve11();
+            resolve12();
           };
           child.once("error", onError);
           child.once("spawn", onSpawn);
@@ -20882,8 +20909,8 @@ var init_mcp = __esm({
         const id = this.nextId;
         this.nextId += 1;
         const message = { jsonrpc: "2.0", id, method, params };
-        return new Promise((resolve11, reject) => {
-          this.pending.set(id, { resolve: resolve11, reject });
+        return new Promise((resolve12, reject) => {
+          this.pending.set(id, { resolve: resolve12, reject });
           this.write(message);
         });
       }
@@ -20978,7 +21005,7 @@ async function requestWithRedirects(url, input, deps, timeoutMs, redirects, star
   return response;
 }
 function requestOnce(url, input, deps, timeoutMs, startedAt) {
-  return new Promise((resolve11, reject) => {
+  return new Promise((resolve12, reject) => {
     const proxy = proxyFor(url);
     const viaProxy = proxy !== void 0;
     const requestUrl = viaProxy ? proxy : url;
@@ -21000,7 +21027,7 @@ function requestOnce(url, input, deps, timeoutMs, startedAt) {
       });
       res.on("end", () => {
         clearTimeout(timer);
-        resolve11({
+        resolve12({
           statusCode: res.statusCode ?? 0,
           headers: normalizeHeaders(res.headers),
           body: deps.redact(Buffer.concat(chunks).toString("utf8")),
@@ -21054,7 +21081,7 @@ function isTimeout(cause) {
 function delay(ms) {
   if (ms <= 0)
     return Promise.resolve();
-  return new Promise((resolve11) => setTimeout(resolve11, ms));
+  return new Promise((resolve12) => setTimeout(resolve12, ms));
 }
 function failure5(invocation, startedAt, endedAt, code, message, retryable, detail, attempt) {
   return {
@@ -145685,7 +145712,7 @@ ${lanes.join("\n")}
           }
         }
         function createImportCallExpressionAMD(arg, containsLexicalThis) {
-          const resolve11 = factory2.createUniqueName("resolve");
+          const resolve12 = factory2.createUniqueName("resolve");
           const reject = factory2.createUniqueName("reject");
           const parameters = [
             factory2.createParameterDeclaration(
@@ -145694,7 +145721,7 @@ ${lanes.join("\n")}
               /*dotDotDotToken*/
               void 0,
               /*name*/
-              resolve11
+              resolve12
             ),
             factory2.createParameterDeclaration(
               /*modifiers*/
@@ -145711,7 +145738,7 @@ ${lanes.join("\n")}
                 factory2.createIdentifier("require"),
                 /*typeArguments*/
                 void 0,
-                [factory2.createArrayLiteralExpression([arg || factory2.createOmittedExpression()]), resolve11, reject]
+                [factory2.createArrayLiteralExpression([arg || factory2.createOmittedExpression()]), resolve12, reject]
               )
             )
           ]);
@@ -232642,8 +232669,8 @@ Additional information: BADCLIENT: Bad error code, ${badCode} not found in range
         installPackage(options) {
           this.packageInstallId++;
           const request = { kind: "installPackage", ...options, id: this.packageInstallId };
-          const promise = new Promise((resolve11, reject) => {
-            (this.packageInstalledPromise ?? (this.packageInstalledPromise = /* @__PURE__ */ new Map())).set(this.packageInstallId, { resolve: resolve11, reject });
+          const promise = new Promise((resolve12, reject) => {
+            (this.packageInstalledPromise ?? (this.packageInstalledPromise = /* @__PURE__ */ new Map())).set(this.packageInstallId, { resolve: resolve12, reject });
           });
           this.installer.send(request);
           return promise;
@@ -232936,10 +232963,10 @@ __export(structure_scan_exports, {
 });
 import { createHash as createHash5 } from "node:crypto";
 import { existsSync as existsSync63, readFileSync as readFileSync59 } from "node:fs";
-import { basename as basename13, dirname as dirname32, extname, join as join65, relative as relative5, resolve as resolve6, sep as sep4 } from "node:path";
+import { basename as basename13, dirname as dirname32, extname, join as join65, relative as relative5, resolve as resolve7, sep as sep4 } from "node:path";
 function buildStaticProjectGraph(input) {
-  const root = resolve6(input.root);
-  const tsconfigPaths = input.tsconfigPath ? [resolve6(root, input.tsconfigPath)] : findTsconfigs(root);
+  const root = resolve7(input.root);
+  const tsconfigPaths = input.tsconfigPath ? [resolve7(root, input.tsconfigPath)] : findTsconfigs(root);
   if (tsconfigPaths.length === 0) {
     return emptyGraph(root, "No tsconfig.json found for Dream structure scan");
   }
@@ -233086,7 +233113,7 @@ function createLanguageServiceHost(fileNames, options) {
   };
 }
 function normalizePath(root, path) {
-  return relative5(root, resolve6(path)).split(sep4).join("/");
+  return relative5(root, resolve7(path)).split(sep4).join("/");
 }
 function isExcluded(root, path) {
   const rel = normalizePath(root, path);
@@ -233200,7 +233227,7 @@ function importEdges(root, sourceFile) {
 function resolveModulePath(root, containingFile, specifier) {
   if (!specifier.startsWith("."))
     return void 0;
-  const base = resolve6(dirname32(containingFile), specifier);
+  const base = resolve7(dirname32(containingFile), specifier);
   for (const suffix of [".ts", ".tsx", ".mts", ".cts", "/index.ts"]) {
     const candidate = `${base}${suffix}`;
     if (existsSync63(candidate))
@@ -234138,7 +234165,7 @@ function networkNeeds(command, args) {
   }
 }
 function tcpConnect(host, port, timeoutMs) {
-  return new Promise((resolve11, reject) => {
+  return new Promise((resolve12, reject) => {
     const socket = createConnection({ host, port });
     let settled = false;
     const done = (err16) => {
@@ -234150,7 +234177,7 @@ function tcpConnect(host, port, timeoutMs) {
       if (err16)
         reject(err16);
       else
-        resolve11();
+        resolve12();
     };
     socket.setTimeout(timeoutMs, () => done(new Error("tcp timeout")));
     socket.once("connect", () => done());
@@ -234162,11 +234189,11 @@ async function networkReachable(probes = {}) {
     host: PROBE_HOST,
     port: PROBE_PORT
   };
-  const resolve11 = probes.resolve ?? ((h) => lookup(h));
+  const resolve12 = probes.resolve ?? ((h) => lookup(h));
   const tcpProbe2 = probes.tcpProbe ?? (() => tcpConnect(target.host, target.port, TCP_TIMEOUT_MS));
   try {
     await Promise.race([
-      resolve11(target.host),
+      resolve12(target.host),
       new Promise((_, rej) => {
         const timer = setTimeout(() => rej(new Error("dns timeout")), DNS_TIMEOUT_MS);
         if (typeof timer === "object")
@@ -234473,7 +234500,7 @@ init_dist2();
 import { spawn as spawn2 } from "node:child_process";
 import { existsSync as existsSync15, readFileSync as readFileSync12, realpathSync as realpathSync2, unlinkSync, writeFileSync as writeFileSync6 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
-import { join as join18 } from "node:path";
+import { join as join18, resolve as resolve5 } from "node:path";
 var liveAgents = /* @__PURE__ */ new Set();
 function killLiveAgents(signal = "SIGKILL") {
   let n = 0;
@@ -234799,12 +234826,28 @@ function evidenceFrameEnv(runDir) {
   };
 }
 var INHERITED_GIT_ENV_KEYS = ["GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", "GIT_INDEX_FILE"];
+function worktreeGitEnv(cwd) {
+  const gitPath = join18(cwd, ".git");
+  if (!existsSync15(gitPath))
+    return {};
+  try {
+    const text2 = readFileSync12(gitPath, "utf8");
+    const match = /^gitdir:\s*(.+)\s*$/m.exec(text2);
+    if (match?.[1] !== void 0 && match[1].trim() !== "") {
+      return { GIT_DIR: resolve5(cwd, match[1].trim()), GIT_WORK_TREE: cwd };
+    }
+  } catch {
+    return { GIT_DIR: gitPath, GIT_WORK_TREE: cwd };
+  }
+  return {};
+}
 function childEnv(opts) {
   const env = { ...opts.env ?? process.env };
   for (const key of INHERITED_GIT_ENV_KEYS)
     delete env[key];
   env.PWD = opts.cwd;
   delete env.OLDPWD;
+  Object.assign(env, worktreeGitEnv(opts.cwd));
   return opts.runDir !== void 0 && opts.runDir !== "" ? { ...env, ...evidenceFrameEnv(opts.runDir) } : env;
 }
 function withAgentProfileEnv(agent, opts) {
@@ -234820,7 +234863,7 @@ function withAgentProfileEnv(agent, opts) {
 function spawnAndWait(bin, args, opts, pty = false) {
   process.stderr.write(`[runner] spawn ${bin} argv=${JSON.stringify(args.map((a) => a.length > 80 ? `${a.slice(0, 77)}...` : a))}
 `);
-  return new Promise((resolve11) => {
+  return new Promise((resolve12) => {
     const child = spawn2(bin, args, {
       cwd: opts.cwd,
       env: childEnv(opts),
@@ -234863,7 +234906,7 @@ function spawnAndWait(bin, args, opts, pty = false) {
         opts.cleanup?.();
       } catch {
       }
-      resolve11(result);
+      resolve12(result);
     };
     child.on("error", (e) => {
       settle({ stdout, stderr: `${stderr}${String(e)}
@@ -234890,13 +234933,13 @@ function realDeps() {
     sharedRoot: () => process.env["ROLL_SHARED_ROOT"] || join19(homedir5(), ".shared", "roll"),
     launchdDir: () => join19(homedir5(), "Library", "LaunchAgents"),
     scheduler: createScheduler(process.platform, { uid: process.getuid?.() ?? 501 }),
-    execRunner: (runner) => new Promise((resolve11) => {
+    execRunner: (runner) => new Promise((resolve12) => {
       const child = spawn3("bash", [runner], {
         stdio: "inherit",
         env: { ...process.env, ROLL_LOOP_FORCE: "1" }
       });
-      child.on("exit", (code) => resolve11(code ?? 1));
-      child.on("error", () => resolve11(1));
+      child.on("exit", (code) => resolve12(code ?? 1));
+      child.on("error", () => resolve12(1));
     }),
     hasTmux: () => {
       try {
@@ -234907,7 +234950,7 @@ function realDeps() {
     },
     // The `loop now` inline observation: tail live.log while the cycle holds
     // the inner lock; Ctrl-C stops the TAIL only (the cycle lives in tmux).
-    observe: (rt) => new Promise((resolve11) => {
+    observe: (rt) => new Promise((resolve12) => {
       const lock = join19(rt, "inner.lock");
       const tail3 = spawn3("tail", ["-n", "+1", "-F", join19(rt, "live.log")], { stdio: "inherit" });
       let sawLock = false;
@@ -234918,7 +234961,7 @@ function realDeps() {
         } catch {
         }
         process.removeListener("SIGINT", finish);
-        resolve11();
+        resolve12();
       };
       const timer = setInterval(() => {
         if (existsSync16(lock))
@@ -249779,13 +249822,13 @@ function followSupervisorCollabStream(projectPath3, noColor2) {
   const tickLimit = envOptionalPositiveInt("ROLL_SUPERVISOR_COLLAB_WATCH_TICKS");
   let renderedCycles = 0;
   let ticks = 0;
-  return new Promise((resolve11) => {
+  return new Promise((resolve12) => {
     let timer;
     const stop = (code) => {
       if (timer !== void 0)
         clearInterval(timer);
       process.removeListener("SIGINT", onSigint);
-      resolve11(code);
+      resolve12(code);
     };
     const onSigint = () => stop(130);
     const tick = () => {
@@ -249876,7 +249919,7 @@ function unknownSupervisorLiveFlag(args) {
 function followSupervisorLiveBoard(projectPath3, intervalMs) {
   const tickLimit = envOptionalPositiveInt("ROLL_SUPERVISOR_LIVE_WATCH_TICKS");
   let ticks = 0;
-  return new Promise((resolve11) => {
+  return new Promise((resolve12) => {
     let timer;
     let stopped = false;
     const stop = (code) => {
@@ -249887,7 +249930,7 @@ function followSupervisorLiveBoard(projectPath3, intervalMs) {
         clearInterval(timer);
       process.removeListener("SIGINT", onSigint);
       process.stdout.write("\x1B[?25h");
-      resolve11(code);
+      resolve12(code);
     };
     const onSigint = () => stop(130);
     const tick = () => {
@@ -251053,7 +251096,7 @@ function spawnPeerReviewAgent(input) {
   const cmd = textAgentArgv(input.agent, input.prompt);
   if (cmd === null)
     return Promise.resolve({ status: "error", reason: "unsupported_reviewer", stdout: "" });
-  return new Promise((resolve11) => {
+  return new Promise((resolve12) => {
     let stdout = "";
     let stderr = "";
     let timedOut = false;
@@ -251071,7 +251114,7 @@ function spawnPeerReviewAgent(input) {
       settled = true;
       if (timer !== void 0)
         clearTimeout(timer);
-      resolve11(result);
+      resolve12(result);
     };
     timer = setTimeout(() => {
       timedOut = true;
@@ -251681,7 +251724,7 @@ function realDeps5() {
     startTmux: startGoTmux,
     followFeed: followGoLiveFeed,
     runOnce: realRunOnce,
-    sleep: (ms) => new Promise((resolve11) => setTimeout(resolve11, ms)),
+    sleep: (ms) => new Promise((resolve12) => setTimeout(resolve12, ms)),
     externalTools: guideExternalToolSetup,
     preinstallChromium: () => {
       silentPreinstallChromium();
@@ -251726,6 +251769,59 @@ function eventsPath(projectPath3) {
 function runsPath2(projectPath3) {
   return join55(runtimeDir5(projectPath3), "runs.jsonl");
 }
+function parsePorcelainPath(line) {
+  const raw = line.length > 3 ? line.slice(3).trim() : line.trim();
+  const target = raw.includes(" -> ") ? raw.split(" -> ").at(-1) ?? raw : raw;
+  return target.replace(/^"|"$/g, "").replace(/\/$/, "");
+}
+function gitDirtyPaths(projectPath3) {
+  const result = spawnSync8("git", ["status", "--porcelain", "--untracked-files=all"], {
+    cwd: projectPath3,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  if (result.status !== 0)
+    return [];
+  return String(result.stdout ?? "").split("\n").map((line) => line.trimEnd()).filter((line) => line.trim() !== "").map(parsePorcelainPath).filter((path) => path !== ".roll/loop" && !path.startsWith(".roll/loop/")).slice(0, 50);
+}
+function isBootstrapArtifactPath(path) {
+  if (path === "AGENTS.md" || path === "CLAUDE.md" || path === ".cursor-rules" || path === "project_rules.md")
+    return true;
+  if (path === ".roll" || path.startsWith(".roll/"))
+    return true;
+  if (path === ".claude" || path.startsWith(".claude/"))
+    return true;
+  return false;
+}
+function classifyBootstrapArtifacts(paths) {
+  const files = paths.filter((path) => path.trim() !== "");
+  if (files.length === 0)
+    return { kind: "none", files: [] };
+  return files.every(isBootstrapArtifactPath) ? { kind: "bootstrap_only", files } : { kind: "mixed", files };
+}
+function bootstrapArtifactsMessage(files) {
+  const shown = files.slice(0, 12).join(", ");
+  const more = files.length > 12 ? `, ... +${files.length - 12} more` : "";
+  return [
+    "roll loop go: bootstrap_artifacts_unconfirmed",
+    `  files: ${shown}${more}`,
+    "  These files define project conventions/backlog metadata. Confirm their ownership before running builders:",
+    "  - commit them to the product repo if they are product truth",
+    "  - commit private Roll metadata inside .roll/roll-meta when applicable",
+    "  - ignore/externalize them by project policy",
+    "  - or clean them up and re-run init/design",
+    "  Then rerun: roll loop go",
+    "",
+    "roll loop go: bootstrap_artifacts_unconfirmed",
+    "  \u8FD9\u4E9B\u6587\u4EF6\u5B9A\u4E49\u9879\u76EE\u7EA6\u5B9A/backlog \u5143\u6570\u636E\u3002\u5148\u786E\u8BA4\u5F52\u5C5E\uFF0C\u518D\u542F\u52A8 builder\uFF1A",
+    "  - \u5C5E\u4E8E\u4EA7\u54C1\u4E8B\u5B9E\u5C31\u63D0\u4EA4\u5230\u4EA7\u54C1\u4ED3",
+    "  - \u5C5E\u4E8E\u79C1\u6709 Roll \u5143\u6570\u636E\u5C31\u63D0\u4EA4\u5230 .roll/roll-meta",
+    "  - \u6309\u9879\u76EE\u7EA6\u5B9A ignore/\u5916\u7F6E",
+    "  - \u6216\u6E05\u7406\u540E\u91CD\u8DD1 init/design",
+    "  \u7136\u540E\u518D\u8FD0\u884C\uFF1Aroll loop go",
+    ""
+  ].join("\n");
+}
 function parseOptions(args) {
   let scope = { kind: "all" };
   let maxCycles;
@@ -251958,7 +252054,7 @@ function startGoTmux(input) {
   }
 }
 function followGoLiveFeed(projectPath3, rollBin4) {
-  return new Promise((resolve11) => {
+  return new Promise((resolve12) => {
     const cmd = rollBin4.endsWith(".js") || rollBin4.endsWith(".mjs") ? process.execPath : rollBin4;
     const args = rollBin4.endsWith(".js") || rollBin4.endsWith(".mjs") ? [rollBin4, "loop", "watch", "--since", "all"] : ["loop", "watch", "--since", "all"];
     const watch = spawn7(cmd, args, { cwd: projectPath3, stdio: ["ignore", "inherit", "inherit"] });
@@ -251968,7 +252064,7 @@ function followGoLiveFeed(projectPath3, rollBin4) {
       } catch {
       }
       process.removeListener("SIGINT", finish);
-      resolve11();
+      resolve12();
     };
     process.on("SIGINT", finish);
     watch.on("exit", finish);
@@ -251979,7 +252075,7 @@ function realRunOnce(input) {
   const bin = rollBin();
   const cmd = bin.endsWith(".js") || bin.endsWith(".mjs") ? process.execPath : bin;
   const args = cmd === process.execPath ? [bin, "loop", "run-once"] : ["loop", "run-once"];
-  return new Promise((resolve11) => {
+  return new Promise((resolve12) => {
     const child = spawn7(cmd, args, {
       cwd: input.projectPath,
       detached: true,
@@ -251993,8 +252089,8 @@ function realRunOnce(input) {
       },
       stdio: "inherit"
     });
-    child.on("exit", (code) => resolve11(code ?? 1));
-    child.on("error", () => resolve11(1));
+    child.on("exit", (code) => resolve12(code ?? 1));
+    child.on("error", () => resolve12(1));
   });
 }
 function writeGoal(path, goal) {
@@ -252822,6 +252918,14 @@ async function runGoWorker(id, opts, deps) {
         stopReason2 = preProgressGate.reason;
         break;
       }
+      const bootstrap = classifyBootstrapArtifacts(gitDirtyPaths(id.path));
+      if (bootstrap.kind === "bootstrap_only") {
+        stopReason2 = "bootstrap_artifacts_unconfirmed";
+        appendGoalGate(bus, evPath, sid, "progress", "paused", stopReason2, { files: bootstrap.files.join(", "), count: bootstrap.files.length }, deps.nowSec());
+        process.stdout.write(bootstrapArtifactsMessage(bootstrap.files));
+        goal = pauseGoal(id.path, bus, stopReason2, deps.nowIso(), deps.nowSec()) ?? goal;
+        break;
+      }
       const allowedCards = allowedCardsForScope(id.path, goal, progress);
       if (allScopeCardsSkipped(id.path, goal, progress)) {
         stopReason2 = "no_progress_on_all_cards";
@@ -253975,7 +254079,7 @@ function renderDesignNudge(lang10) {
 init_dist2();
 init_dist();
 import { existsSync as existsSync59, readdirSync as readdirSync24, readFileSync as readFileSync56, statSync as statSync22 } from "node:fs";
-import { relative as relative4, resolve as resolve5 } from "node:path";
+import { relative as relative4, resolve as resolve6 } from "node:path";
 var IGNORE_DIRS = /* @__PURE__ */ new Set([
   ".git",
   "node_modules",
@@ -253997,23 +254101,23 @@ function walkMarkdownFiles(dir, out3, includeGenerated) {
         continue;
       if (!includeGenerated && (entry.name === ".roll" || entry.name === "archive"))
         continue;
-      walkMarkdownFiles(resolve5(dir, entry.name), out3, includeGenerated);
+      walkMarkdownFiles(resolve6(dir, entry.name), out3, includeGenerated);
     } else if (entry.isFile() && isMarkdownFile(entry.name)) {
-      out3.push(resolve5(dir, entry.name));
+      out3.push(resolve6(dir, entry.name));
     }
   }
 }
 function defaultScanRoots(root, includeGenerated) {
   const roots = [];
   for (const rel of ["AGENTS.md", "roll.md", "conventions", "skills", "guide"]) {
-    const abs = resolve5(root, rel);
+    const abs = resolve6(root, rel);
     if (!existsSync59(abs))
       continue;
     roots.push(abs);
   }
   if (includeGenerated) {
     for (const rel of [".roll", "archive"]) {
-      const abs = resolve5(root, rel);
+      const abs = resolve6(root, rel);
       if (existsSync59(abs))
         roots.push(abs);
     }
@@ -256854,7 +256958,7 @@ function renderAiClients(out3, clients) {
     }
     out3.push("  " + pad(nameCol, 14) + pad(c("dim", cl.cfg_file), 14) + pad(syncCol, 14) + c("dim", String(cl.skills)));
     if (cl.sync === "out-of-sync" || cl.sync === "missing") {
-      out3.push("       " + c("dim", "fix: ") + c("blue", `roll setup -f ${cl.name}`));
+      out3.push("       " + c("dim", "fix: ") + c("blue", "roll setup -f"));
     }
   }
   out3.push("", hr(), "");
@@ -257180,7 +257284,7 @@ function collectAgentPanel(projectPath3, deps = defaultAgentPanelDeps()) {
       costUsd72h: Number(s.cost.toFixed(4)),
       files,
       syncStale: isInstalled && stale,
-      ...isInstalled && stale ? { setupCmd: `roll setup -f ${name}` } : {}
+      ...isInstalled && stale ? { setupCmd: "roll setup -f" } : {}
     });
   }
   rows.sort((a, b) => Number(b.installed) - Number(a.installed) || b.cycles72h - a.cycles72h || a.name.localeCompare(b.name));
@@ -258049,7 +258153,7 @@ function collectLoopHeartbeat(deps) {
 // packages/cli/dist/lib/git-hooks.js
 import { execFileSync as execFileSync20 } from "node:child_process";
 import { readdirSync as readdirSync29 } from "node:fs";
-import { isAbsolute, join as join77, resolve as resolve7 } from "node:path";
+import { isAbsolute, join as join77, resolve as resolve8 } from "node:path";
 var HOOK_DESCRIPTIONS = {
   "pre-commit": {
     en: "TCR proof gate before commit",
@@ -258111,11 +258215,11 @@ function resolveHooksPath(projectPath3) {
   if (configured !== "" && configured !== ".git/hooks") {
     return {
       displayPath: configured,
-      fsPath: isAbsolute(configured) ? configured : resolve7(projectPath3, configured)
+      fsPath: isAbsolute(configured) ? configured : resolve8(projectPath3, configured)
     };
   }
   const gitPath = gitOutput3(projectPath3, ["rev-parse", "--git-path", "hooks"]);
-  const fsPath = gitPath === "" ? join77(projectPath3, ".git", "hooks") : isAbsolute(gitPath) ? gitPath : resolve7(projectPath3, gitPath);
+  const fsPath = gitPath === "" ? join77(projectPath3, ".git", "hooks") : isAbsolute(gitPath) ? gitPath : resolve8(projectPath3, gitPath);
   return {
     displayPath: configured === "" ? ".git/hooks" : configured,
     fsPath
@@ -260053,6 +260157,91 @@ function registerProject(projectDir) {
   } catch {
   }
 }
+var ROLL_OWNED_GIT_PATHS = [
+  "AGENTS.md",
+  ".claude/CLAUDE.md",
+  ".roll/.version",
+  ".roll/agents.yaml",
+  ".roll/backlog.md",
+  ".roll/brief.md",
+  ".roll/briefs",
+  ".roll/domain",
+  ".roll/domain/context-map.md",
+  ".roll/features",
+  ".roll/features.md",
+  ".roll/init-diagnosis.yaml",
+  ".roll/onboard-changeset.yaml",
+  ".roll/onboard-plan.yaml",
+  ".roll/tech-analysis.md",
+  ".roll/test-assessment.md",
+  ".gitignore"
+];
+function runGit(projectDir, args) {
+  const result = spawnSync11("git", args, {
+    cwd: projectDir,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  return {
+    ok: result.status === 0,
+    stdout: String(result.stdout ?? ""),
+    stderr: String(result.stderr ?? "")
+  };
+}
+function existingRollOwnedPaths(projectDir) {
+  return ROLL_OWNED_GIT_PATHS.filter((rel) => existsSync83(join86(projectDir, rel.replace(/\/$/, ""))));
+}
+function printGitFinalizeManual(reason, command) {
+  warn4(`Roll meta git finalize needs manual follow-up: ${reason}`);
+  process.stderr.write(`  ${command}
+`);
+}
+function finalizeRollOwnedGit(projectDir) {
+  if (!runGit(projectDir, ["rev-parse", "--is-inside-work-tree"]).ok)
+    return;
+  const topLevel = runGit(projectDir, ["rev-parse", "--show-toplevel"]);
+  if (!topLevel.ok)
+    return;
+  if (realpathSync11(projectDir) !== realpathSync11(topLevel.stdout.trim()))
+    return;
+  const paths = existingRollOwnedPaths(projectDir);
+  if (paths.length === 0)
+    return;
+  if (!runGit(projectDir, ["diff", "--cached", "--quiet"]).ok) {
+    printGitFinalizeManual("existing staged changes; auto commit skipped", `git add -A -f -- ${paths.join(" ")} && git commit -m 'roll init: commit Roll-owned meta files'`);
+    return;
+  }
+  const add = runGit(projectDir, ["add", "-A", "-f", "--", ...paths]);
+  if (!add.ok) {
+    printGitFinalizeManual("git add failed", `git add -A -f -- ${paths.join(" ")}`);
+    return;
+  }
+  if (runGit(projectDir, ["diff", "--cached", "--quiet", "--", ...paths]).ok)
+    return;
+  const commit2 = runGit(projectDir, ["commit", "-m", "roll init: commit Roll-owned meta files"]);
+  if (!commit2.ok) {
+    printGitFinalizeManual("git commit failed", "git commit -m 'roll init: commit Roll-owned meta files' -- AGENTS.md .roll .claude .gitignore");
+    return;
+  }
+  const sha = runGit(projectDir, ["rev-parse", "--short", "HEAD"]).stdout.trim();
+  ok10(`Roll meta committed${sha !== "" ? `: ${sha}` : ""}`);
+  const branch = runGit(projectDir, ["rev-parse", "--abbrev-ref", "HEAD"]).stdout.trim();
+  if (branch === "" || branch === "HEAD") {
+    printGitFinalizeManual("detached HEAD; push skipped", "git push origin HEAD");
+    return;
+  }
+  const remotes = runGit(projectDir, ["remote"]).stdout.split("\n").filter((line) => line.trim() !== "");
+  if (!remotes.includes("origin")) {
+    printGitFinalizeManual("origin remote is not configured; push skipped", `git push -u origin ${branch}`);
+    return;
+  }
+  const push2 = runGit(projectDir, ["push", "-u", "origin", branch]);
+  if (!push2.ok) {
+    printGitFinalizeManual("git push failed", `git push -u origin ${branch}`);
+    return;
+  }
+  ok10(`Roll meta pushed: origin/${branch}`);
+}
 function err9(line) {
   const { RED, NC } = pal4();
   process.stderr.write(`${RED}[roll]${NC} ${line}
@@ -260914,6 +261103,7 @@ function initRepair(projectDir, facts, diagnosis2, opts = {}) {
   recordCreatedFileIfNeeded(projectDir, changeset, ".roll/.version", stampExisted);
   printMergeSummary(summary);
   ok10("Repair complete.");
+  finalizeRollOwnedGit(projectDir);
   return 0;
 }
 function initApply(projectDir, opts = {}) {
@@ -261029,6 +261219,7 @@ function initApply(projectDir, opts = {}) {
     registerProject(projectDir);
     process.stdout.write("\n");
     ok10(m3("init.onboard_apply_complete_onboard"));
+    finalizeRollOwnedGit(projectDir);
     return 0;
   } catch (error) {
     err9(m32("init.onboard_apply_failed"));
@@ -261859,6 +262050,7 @@ function initCommand(args, deps = {}) {
   registerProject(projectDir);
   const shouldNudge = detectDesignHandoff(projectDir).shouldNudge;
   emitInitUi(projectDir, hasAgents, syncStatus, summary, shouldNudge, repairMode ? "repair" : void 0, conciergeNextItems(brief, initDiagnosis));
+  finalizeRollOwnedGit(projectDir);
   void err9;
   return 0;
 }
@@ -262057,7 +262249,7 @@ init_dist();
 init_dist2();
 import { spawnSync as spawnSync12 } from "node:child_process";
 import { existsSync as existsSync85, mkdirSync as mkdirSync37, readFileSync as readFileSync78, renameSync as renameSync16, statSync as statSync31, writeFileSync as writeFileSync39 } from "node:fs";
-import { dirname as dirname39, join as join88, relative as relative6, resolve as resolve8 } from "node:path";
+import { dirname as dirname39, join as join88, relative as relative6, resolve as resolve9 } from "node:path";
 
 // packages/cli/dist/lib/review-page.js
 init_dist2();
@@ -262466,7 +262658,7 @@ function renderDesignReviewPageForTarget(ctx, cardsCreated) {
     return;
   const base = join88(".roll", "features", epic, ctx.target);
   const md = join88(base, "spec.md");
-  const absMd = resolve8(ctx.cwd, md);
+  const absMd = resolve9(ctx.cwd, md);
   if (!existsSync85(absMd) || !hasDetailedDesign(absMd))
     return;
   const markdown = readFileSync78(absMd, "utf8");
@@ -262481,7 +262673,7 @@ function renderDesignReviewPageForTarget(ctx, cardsCreated) {
     markdown,
     lang: ctx.lang
   });
-  const out3 = resolve8(ctx.cwd, base, "design-review.html");
+  const out3 = resolve9(ctx.cwd, base, "design-review.html");
   mkdirSync37(dirname39(out3), { recursive: true });
   const tmp = `${out3}.tmp`;
   writeFileSync39(tmp, html, "utf8");
@@ -262594,12 +262786,12 @@ function printHandoff(ctx, statusCode, rawTranscript) {
     const md = join88(base, "spec.md");
     const reviewHtml = join88(base, "design-review.html");
     const html = join88(base, "spec.html");
-    if (existsSync85(resolve8(ctx.cwd, md))) {
-      designPath = hasDetailedDesign(resolve8(ctx.cwd, md)) ? `${md}#detailed-design` : md;
+    if (existsSync85(resolve9(ctx.cwd, md))) {
+      designPath = hasDetailedDesign(resolve9(ctx.cwd, md)) ? `${md}#detailed-design` : md;
     }
-    if (existsSync85(resolve8(ctx.cwd, reviewHtml)))
+    if (existsSync85(resolve9(ctx.cwd, reviewHtml)))
       reviewPagePath = reviewHtml;
-    else if (existsSync85(resolve8(ctx.cwd, html)))
+    else if (existsSync85(resolve9(ctx.cwd, html)))
       reviewPagePath = html;
   }
   let status2;
@@ -262664,7 +262856,7 @@ function designCommand(args, deps = {}) {
     emit4(t(v3Catalog, l, "design.not_roll_project"));
     return 1;
   }
-  if (fromFile !== void 0 && !isRegularFile(resolve8(d.cwd, fromFile))) {
+  if (fromFile !== void 0 && !isRegularFile(resolve9(d.cwd, fromFile))) {
     emit4(t(v3Catalog, l, "design.from_file_not_found", fromFile));
     return 1;
   }
@@ -263734,8 +263926,8 @@ async function probeAgentReachable(agent, spawn10, opts = {}) {
   try {
     res = await Promise.race([
       spawn10(agent, { cwd, skillBody: `Reply with exactly: ${token}`, timeoutMs, bare: true }),
-      new Promise((resolve11) => {
-        setTimeout(() => resolve11(null), timeoutMs).unref();
+      new Promise((resolve12) => {
+        setTimeout(() => resolve12(null), timeoutMs).unref();
       })
     ]);
   } catch (e) {
@@ -264621,7 +264813,7 @@ function reviewTimeoutMs(diffChars) {
 async function firstValid(promises) {
   if (promises.length === 0)
     return null;
-  return new Promise((resolve11, reject) => {
+  return new Promise((resolve12, reject) => {
     let pending = promises.length;
     let settled = false;
     let lastError;
@@ -264633,7 +264825,7 @@ async function firstValid(promises) {
         if (threw)
           reject(lastError);
         else
-          resolve11(null);
+          resolve12(null);
       }
     };
     for (const p of promises) {
@@ -264642,7 +264834,7 @@ async function firstValid(promises) {
           return;
         if (value !== null) {
           settled = true;
-          resolve11(value);
+          resolve12(value);
           return;
         }
         onNonResult();
@@ -265025,7 +265217,7 @@ DIFF:
 
 // packages/cli/dist/runner/executor.js
 var execFileAsync10 = promisify10(execFile10);
-function parsePorcelainPath(line) {
+function parsePorcelainPath2(line) {
   const raw = line.length > 3 ? line.slice(3).trim() : line.trim();
   const target = raw.includes(" -> ") ? raw.split(" -> ").at(-1) ?? raw : raw;
   return target.replace(/^"|"$/g, "");
@@ -265036,7 +265228,7 @@ async function checkMainDirty(repoCwd) {
       cwd: repoCwd,
       encoding: "utf8"
     });
-    return stdout.split("\n").map((line) => line.trimEnd()).filter((line) => line.trim() !== "").map(parsePorcelainPath).filter((path) => path !== ".roll" && !path.startsWith(".roll/")).slice(0, 50);
+    return stdout.split("\n").map((line) => line.trimEnd()).filter((line) => line.trim() !== "").map(parsePorcelainPath2).filter((path) => path !== ".roll" && !path.startsWith(".roll/")).slice(0, 50);
   } catch {
     return [];
   }
@@ -265995,7 +266187,7 @@ ${stderr}
               // FIX-319: review-only framing, no worker autorun directive
               ...ctx.evidenceRunDir !== void 0 ? { runDir: ctx.evidenceRunDir } : {}
             }),
-            new Promise((resolve11) => setTimeout(() => resolve11(null), timeoutMs).unref())
+            new Promise((resolve12) => setTimeout(() => resolve12(null), timeoutMs).unref())
           ]);
         } catch (e) {
           const detail = e instanceof Error ? e.message : String(e);
@@ -266135,7 +266327,7 @@ ${res.stderr}`;
                 timeoutMs,
                 ...ctx.evidenceRunDir !== void 0 ? { runDir: ctx.evidenceRunDir } : {}
               }),
-              new Promise((resolve11) => setTimeout(() => resolve11(null), timeoutMs).unref())
+              new Promise((resolve12) => setTimeout(() => resolve12(null), timeoutMs).unref())
             ]);
           } catch (e) {
             const detail = e instanceof Error ? e.message : String(e);
@@ -269132,10 +269324,10 @@ function autoGc(projectPath3) {
     }
   }
 }
-async function isOffline(resolve11 = (h) => lookup2(h)) {
+async function isOffline(resolve12 = (h) => lookup2(h)) {
   try {
     await Promise.race([
-      resolve11("github.com"),
+      resolve12("github.com"),
       new Promise((_, rej) => {
         const t2 = setTimeout(() => rej(new Error("dns timeout")), 1500);
         if (typeof t2 === "object")
@@ -269204,7 +269396,7 @@ init_dist();
 import { spawnSync as spawnSync15 } from "node:child_process";
 import { existsSync as existsSync100, readFileSync as readFileSync94, realpathSync as realpathSync14, renameSync as renameSync18, rmSync as rmSync17, writeFileSync as writeFileSync50 } from "node:fs";
 import { homedir as homedir28 } from "node:os";
-import { join as join104, resolve as resolve9 } from "node:path";
+import { join as join104, resolve as resolve10 } from "node:path";
 function pal5() {
   const noColor2 = (process.env["NO_COLOR"] ?? "") !== "";
   return noColor2 ? { RED: "", GREEN: "", YELLOW: "", CYAN: "", BOLD: "", NC: "" } : {
@@ -269308,7 +269500,7 @@ function writeFileAtomic2(path, text2) {
   }
 }
 function resolveChangesetItem(projectDir, item) {
-  return item.startsWith("/") ? resolve9(item) : resolve9(projectDir, item);
+  return item.startsWith("/") ? resolve10(item) : resolve10(projectDir, item);
 }
 var HELP3 = `Usage: roll offboard [--confirm]
   Preview (default) or apply (--confirm) the removal of every
@@ -269329,7 +269521,7 @@ function offboardCommand(args) {
   }
   let projectDir;
   try {
-    projectDir = realpathSync14(resolve9(process.cwd()));
+    projectDir = realpathSync14(resolve10(process.cwd()));
   } catch {
     projectDir = process.cwd();
   }
@@ -272118,7 +272310,7 @@ init_showcase2();
 // packages/cli/dist/commands/test.js
 import { spawnSync as spawnSync18 } from "node:child_process";
 import { appendFileSync as appendFileSync19, existsSync as existsSync108, mkdirSync as mkdirSync53, readFileSync as readFileSync102, rmSync as rmSync19, writeFileSync as writeFileSync56 } from "node:fs";
-import { dirname as dirname50, join as join112, resolve as resolve10 } from "node:path";
+import { dirname as dirname50, join as join112, resolve as resolve11 } from "node:path";
 function pal7() {
   const noColor2 = (process.env["NO_COLOR"] ?? "") !== "";
   return noColor2 ? { CYAN: "", GREEN: "", YELLOW: "", RED: "", NC: "" } : { CYAN: "\x1B[0;36m", GREEN: "\x1B[0;32m", YELLOW: "\x1B[0;33m", RED: "\x1B[0;31m", NC: "\x1B[0m" };
@@ -272138,7 +272330,7 @@ function currentEvidenceFrame() {
   const raw = (process.env["ROLL_RUN_DIR"] ?? "").trim();
   if (raw === "")
     return null;
-  const runDir = resolve10(raw);
+  const runDir = resolve11(raw);
   if (!existsSync108(runDir))
     return null;
   const frame = {
@@ -273114,7 +273306,7 @@ function registerAll() {
     if (args[0] === "offboard")
       return offboardCommand(args.slice(1));
     return setupCommand(args);
-  }, { help: "Usage: roll setup [skills|offboard]\n  Install roll conventions/templates for this machine, or remove recorded Roll artifacts.\n\u672C\u673A\u5B89\u88C5\u6A21\u677F\uFF0C\u6216\u79FB\u9664\u8BB0\u5F55\u8FC7\u7684 Roll \u4EA7\u7269\u3002" });
+  }, { help: "Usage: roll setup [-f|--force] [--reselect]\n       roll setup skills [args...]\n       roll setup offboard [args...]\n  Install or re-sync Roll conventions/templates for this machine; use -f to force refresh.\n\u672C\u673A\u5B89\u88C5\u6216\u91CD\u65B0\u540C\u6B65 Roll \u6A21\u677F\u4E0E\u7EA6\u5B9A\uFF1B-f \u5F3A\u5236\u5237\u65B0\u3002" });
   registerPorted("ci", (args) => {
     if (args.includes("--wait"))
       return ciWaitCommand(args);

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.3",
   "description": "Roll — Roll out features with AI agents",
   "packageManager": "pnpm@11.1.3",
   "scripts": {