@seanyao/roll 3.627.1 → 3.628.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## v3.628.1 — 2026-06-28
+
+### 上手引导
+
+- **`roll init` 给出的 PRD 下一步现在能直接运行**：`roll design --from-file <path>` 会校验输入文件并把 PRD/brief 绑定到 `$roll-design`，不再落到 usage。(#1065) `[legacy-onboard]`
+
 ## v3.627.1 — 2026-06-27
 
 ### 上手引导

package/README.md

@@ -41,7 +41,8 @@ roll loop on        # let AI work through the backlog (optional)
 `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`.
+`.roll/brief.md` from the detected document and points to
+`roll design --from-file <detected-doc>`.
 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`.
@@ -95,7 +96,7 @@ with `roll loop resume` when ready.
 | **Project · per repo** | |
 | `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 design [--from-file <path>] [--agent <name>]` | Launch `$roll-design` interactively; `--from-file` binds a PRD/brief as the design input |
 | `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) |

package/dist/roll.mjs

@@ -2199,8 +2199,8 @@ var init_catalog_v3 = __esm({
       // `design.*` — explicit `roll design` entry point (US-ONBOARD-NUDGE-004).
       // Thin wrapper that launches the existing $roll-design skill interactively.
       "design.usage": {
-        en: "Usage: roll design [--agent <name>]\n  Launch the $roll-design skill in an interactive agent conversation.\n  `--agent` and `ROLL_DESIGN_AGENT` override the configured primary_agent.\n  Unlike `roll init`, this command runs an LLM \u2014 run it only when you want to design.",
-        zh: "\u7528\u6CD5\uFF1Aroll design [--agent <name>]\n  \u5728\u4EA4\u4E92\u5F0F agent \u5BF9\u8BDD\u4E2D\u542F\u52A8 $roll-design skill\u3002\n  `--agent` \u4E0E `ROLL_DESIGN_AGENT` \u8986\u76D6\u5DF2\u914D\u7F6E\u7684 primary_agent\u3002\n  \u4E0E `roll init` \u4E0D\u540C\uFF0C\u672C\u547D\u4EE4\u4F1A\u8FD0\u884C LLM\u2014\u2014\u53EA\u5728\u9700\u8981\u8BBE\u8BA1\u65F6\u6267\u884C\u3002"
+        en: "Usage: roll design [--from-file <path>] [--agent <name>]\n  Launch the $roll-design skill in an interactive agent conversation.\n  `--from-file` binds a PRD/brief file as the design input.\n  `--agent` and `ROLL_DESIGN_AGENT` override the configured primary_agent.\n  Unlike `roll init`, this command runs an LLM \u2014 run it only when you want to design.",
+        zh: "\u7528\u6CD5\uFF1Aroll design [--from-file <path>] [--agent <name>]\n  \u5728\u4EA4\u4E92\u5F0F agent \u5BF9\u8BDD\u4E2D\u542F\u52A8 $roll-design skill\u3002\n  `--from-file` \u4F1A\u628A PRD/brief \u6587\u4EF6\u7ED1\u5B9A\u4E3A\u8BBE\u8BA1\u8F93\u5165\u3002\n  `--agent` \u4E0E `ROLL_DESIGN_AGENT` \u8986\u76D6\u5DF2\u914D\u7F6E\u7684 primary_agent\u3002\n  \u4E0E `roll init` \u4E0D\u540C\uFF0C\u672C\u547D\u4EE4\u4F1A\u8FD0\u884C LLM\u2014\u2014\u53EA\u5728\u9700\u8981\u8BBE\u8BA1\u65F6\u6267\u884C\u3002"
       },
       "design.not_roll_project": {
         en: "This directory is not a Roll project (no .roll/). Run `roll init` first.",
@@ -2218,6 +2218,14 @@ var init_catalog_v3 = __esm({
         en: "Agent '%s' is unknown or not installed.",
         zh: "agent '%s' \u672A\u77E5\u6216\u672A\u5B89\u88C5\u3002"
       },
+      "design.from_file_missing": {
+        en: "`--from-file` requires a path.",
+        zh: "`--from-file` \u9700\u8981\u4E00\u4E2A\u6587\u4EF6\u8DEF\u5F84\u3002"
+      },
+      "design.from_file_not_found": {
+        en: "Design source file not found: %s",
+        zh: "\u672A\u627E\u5230\u8BBE\u8BA1\u8F93\u5165\u6587\u4EF6\uFF1A%s"
+      },
       // `setup.*` — primary agent selection during setup (US-ONBOARD-NUDGE-006).
       "setup.primary_prompt": {
         en: "Multiple AI agents detected. Pick a default:",
@@ -13611,7 +13619,7 @@ function isDaemonRunning(cwd, pidAlive = systemPidAlive) {
   return pidAlive(record.pid);
 }
 function spawnDaemon(cwd, opts) {
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     const host = opts.host ?? "127.0.0.1";
     const port = opts.port ?? 7077;
     const entrypoint = resolveCliEntrypoint(opts);
@@ -13652,7 +13660,7 @@ function spawnDaemon(cwd, opts) {
           finish(reject, new Error("Daemon child did not expose a pid"));
           return;
         }
-        finish(resolve9, { child, pid, address: addr });
+        finish(resolve10, { child, pid, address: addr });
       }
     };
     const onErr = (data) => {
@@ -14633,16 +14641,16 @@ async function crontabRead() {
   }
 }
 async function crontabWrite(text2) {
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     const child = execFile4("crontab", ["-"], (err16) => {
       if (err16 === null) {
-        resolve9(0);
+        resolve10(0);
       } else if (typeof err16.code === "number") {
-        resolve9(err16.code);
+        resolve10(err16.code);
       } else if (err16.code === "ENOENT") {
         reject(err16);
       } else {
-        resolve9(1);
+        resolve10(1);
       }
     });
     child.stdin?.end(text2);
@@ -16686,14 +16694,14 @@ var init_mcp = __esm({
         child.on("exit", () => this.rejectAll(new Error("MCP server exited")));
       }
       static async open(child) {
-        await new Promise((resolve9, reject) => {
+        await new Promise((resolve10, reject) => {
           const onError = (cause) => {
             child.off("spawn", onSpawn);
             reject(cause);
           };
           const onSpawn = () => {
             child.off("error", onError);
-            resolve9();
+            resolve10();
           };
           child.once("error", onError);
           child.once("spawn", onSpawn);
@@ -16722,8 +16730,8 @@ var init_mcp = __esm({
         const id = this.nextId;
         this.nextId += 1;
         const message = { jsonrpc: "2.0", id, method, params };
-        return new Promise((resolve9, reject) => {
-          this.pending.set(id, { resolve: resolve9, reject });
+        return new Promise((resolve10, reject) => {
+          this.pending.set(id, { resolve: resolve10, reject });
           this.write(message);
         });
       }
@@ -16818,7 +16826,7 @@ async function requestWithRedirects(url, input, deps, timeoutMs, redirects, star
   return response;
 }
 function requestOnce(url, input, deps, timeoutMs, startedAt) {
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     const proxy = proxyFor(url);
     const viaProxy = proxy !== void 0;
     const requestUrl = viaProxy ? proxy : url;
@@ -16840,7 +16848,7 @@ function requestOnce(url, input, deps, timeoutMs, startedAt) {
       });
       res.on("end", () => {
         clearTimeout(timer);
-        resolve9({
+        resolve10({
           statusCode: res.statusCode ?? 0,
           headers: normalizeHeaders(res.headers),
           body: deps.redact(Buffer.concat(chunks).toString("utf8")),
@@ -16894,7 +16902,7 @@ function isTimeout(cause) {
 function delay(ms) {
   if (ms <= 0)
     return Promise.resolve();
-  return new Promise((resolve9) => setTimeout(resolve9, ms));
+  return new Promise((resolve10) => setTimeout(resolve10, ms));
 }
 function failure4(invocation, startedAt, endedAt, code, message, retryable, detail, attempt) {
   return {
@@ -25887,7 +25895,7 @@ ${lanes.join("\n")}
               return process.memoryUsage().heapUsed;
             },
             getFileSize(path) {
-              const stat = statSync35(path);
+              const stat = statSync36(path);
               if (stat == null ? void 0 : stat.isFile()) {
                 return stat.size;
               }
@@ -25931,7 +25939,7 @@ ${lanes.join("\n")}
             }
           };
           return nodeSystem;
-          function statSync35(path) {
+          function statSync36(path) {
             try {
               return _fs.statSync(path, statSyncOptions);
             } catch {
@@ -25990,7 +25998,7 @@ ${lanes.join("\n")}
               activeSession.post("Profiler.stop", (err16, { profile }) => {
                 var _a;
                 if (!err16) {
-                  if ((_a = statSync35(profilePath)) == null ? void 0 : _a.isDirectory()) {
+                  if ((_a = statSync36(profilePath)) == null ? void 0 : _a.isDirectory()) {
                     profilePath = _path.join(profilePath, `${(/* @__PURE__ */ new Date()).toISOString().replace(/:/g, "-")}+P${process.pid}.cpuprofile`);
                   }
                   try {
@@ -26110,7 +26118,7 @@ ${lanes.join("\n")}
                 let stat;
                 if (typeof dirent === "string" || dirent.isSymbolicLink()) {
                   const name = combinePaths(path, entry);
-                  stat = statSync35(name);
+                  stat = statSync36(name);
                   if (!stat) {
                     continue;
                   }
@@ -26134,7 +26142,7 @@ ${lanes.join("\n")}
             return matchFiles(path, extensions, excludes, includes, useCaseSensitiveFileNames2, process.cwd(), depth, getAccessibleFileSystemEntries, realpath2);
           }
           function fileSystemEntryExists(path, entryKind) {
-            const stat = statSync35(path);
+            const stat = statSync36(path);
             if (!stat) {
               return false;
             }
@@ -26176,7 +26184,7 @@ ${lanes.join("\n")}
           }
           function getModifiedTime3(path) {
             var _a;
-            return (_a = statSync35(path)) == null ? void 0 : _a.mtime;
+            return (_a = statSync36(path)) == null ? void 0 : _a.mtime;
           }
           function setModifiedTime(path, time) {
             try {
@@ -141529,7 +141537,7 @@ ${lanes.join("\n")}
           }
         }
         function createImportCallExpressionAMD(arg, containsLexicalThis) {
-          const resolve9 = factory2.createUniqueName("resolve");
+          const resolve10 = factory2.createUniqueName("resolve");
           const reject = factory2.createUniqueName("reject");
           const parameters = [
             factory2.createParameterDeclaration(
@@ -141538,7 +141546,7 @@ ${lanes.join("\n")}
               /*dotDotDotToken*/
               void 0,
               /*name*/
-              resolve9
+              resolve10
             ),
             factory2.createParameterDeclaration(
               /*modifiers*/
@@ -141555,7 +141563,7 @@ ${lanes.join("\n")}
                 factory2.createIdentifier("require"),
                 /*typeArguments*/
                 void 0,
-                [factory2.createArrayLiteralExpression([arg || factory2.createOmittedExpression()]), resolve9, reject]
+                [factory2.createArrayLiteralExpression([arg || factory2.createOmittedExpression()]), resolve10, reject]
               )
             )
           ]);
@@ -228486,8 +228494,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((resolve9, reject) => {
-            (this.packageInstalledPromise ?? (this.packageInstalledPromise = /* @__PURE__ */ new Map())).set(this.packageInstallId, { resolve: resolve9, reject });
+          const promise = new Promise((resolve10, reject) => {
+            (this.packageInstalledPromise ?? (this.packageInstalledPromise = /* @__PURE__ */ new Map())).set(this.packageInstallId, { resolve: resolve10, reject });
           });
           this.installer.send(request);
           return promise;
@@ -229468,7 +229476,7 @@ __export(showcase_exports, {
   showcaseCommand: () => showcaseCommand
 });
 import { spawnSync as spawnSync15 } from "node:child_process";
-import { cpSync as cpSync2, existsSync as existsSync101, mkdirSync as mkdirSync49, mkdtempSync as mkdtempSync8, readdirSync as readdirSync39, readFileSync as readFileSync95, rmSync as rmSync19, statSync as statSync32, writeFileSync as writeFileSync51 } from "node:fs";
+import { cpSync as cpSync2, existsSync as existsSync101, mkdirSync as mkdirSync49, mkdtempSync as mkdtempSync8, readdirSync as readdirSync39, readFileSync as readFileSync95, rmSync as rmSync19, statSync as statSync33, writeFileSync as writeFileSync51 } from "node:fs";
 import { tmpdir as tmpdir10 } from "node:os";
 import { dirname as dirname47, join as join106 } from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
@@ -229549,7 +229557,7 @@ function runRoll(sandbox, rollHome4, args, opts = {}) {
 }
 function fileNonEmpty3(p) {
   try {
-    return existsSync101(p) && statSync32(p).size > 0;
+    return existsSync101(p) && statSync33(p).size > 0;
   } catch {
     return false;
   }
@@ -229584,7 +229592,7 @@ function findCardSpec2(sandbox, card) {
       const full = join106(dir, name);
       let isDir4 = false;
       try {
-        isDir4 = statSync32(full).isDirectory();
+        isDir4 = statSync33(full).isDirectory();
       } catch {
         continue;
       }
@@ -229982,7 +229990,7 @@ function networkNeeds(command, args) {
   }
 }
 function tcpConnect(host, port, timeoutMs) {
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     const socket = createConnection({ host, port });
     let settled = false;
     const done = (err16) => {
@@ -229994,7 +230002,7 @@ function tcpConnect(host, port, timeoutMs) {
       if (err16)
         reject(err16);
       else
-        resolve9();
+        resolve10();
     };
     socket.setTimeout(timeoutMs, () => done(new Error("tcp timeout")));
     socket.once("connect", () => done());
@@ -230006,11 +230014,11 @@ async function networkReachable(probes = {}) {
     host: PROBE_HOST,
     port: PROBE_PORT
   };
-  const resolve9 = probes.resolve ?? ((h) => lookup(h));
+  const resolve10 = probes.resolve ?? ((h) => lookup(h));
   const tcpProbe2 = probes.tcpProbe ?? (() => tcpConnect(target.host, target.port, TCP_TIMEOUT_MS));
   try {
     await Promise.race([
-      resolve9(target.host),
+      resolve10(target.host),
       new Promise((_, rej) => {
         const timer = setTimeout(() => rej(new Error("dns timeout")), DNS_TIMEOUT_MS);
         if (typeof timer === "object")
@@ -230456,7 +230464,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((resolve9) => {
+  return new Promise((resolve10) => {
     const child = spawn3(bin, args, {
       cwd: opts.cwd,
       env: childEnv(opts),
@@ -230492,7 +230500,7 @@ function spawnAndWait(bin, args, opts, pty = false) {
       liveAgents.delete(child);
       if (timer !== void 0)
         clearTimeout(timer);
-      resolve9(result);
+      resolve10(result);
     };
     child.on("error", (e) => {
       settle({ stdout, stderr: `${stderr}${String(e)}
@@ -230519,13 +230527,13 @@ function realDeps() {
     sharedRoot: () => process.env["ROLL_SHARED_ROOT"] || join20(homedir5(), ".shared", "roll"),
     launchdDir: () => join20(homedir5(), "Library", "LaunchAgents"),
     scheduler: createScheduler(process.platform, { uid: process.getuid?.() ?? 501 }),
-    execRunner: (runner) => new Promise((resolve9) => {
+    execRunner: (runner) => new Promise((resolve10) => {
       const child = spawn4("bash", [runner], {
         stdio: "inherit",
         env: { ...process.env, ROLL_LOOP_FORCE: "1" }
       });
-      child.on("exit", (code) => resolve9(code ?? 1));
-      child.on("error", () => resolve9(1));
+      child.on("exit", (code) => resolve10(code ?? 1));
+      child.on("error", () => resolve10(1));
     }),
     hasTmux: () => {
       try {
@@ -230536,7 +230544,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((resolve9) => {
+    observe: (rt) => new Promise((resolve10) => {
       const lock = join20(rt, "inner.lock");
       const tail3 = spawn4("tail", ["-n", "+1", "-F", join20(rt, "live.log")], { stdio: "inherit" });
       let sawLock = false;
@@ -230547,7 +230555,7 @@ function realDeps() {
         } catch {
         }
         process.removeListener("SIGINT", finish);
-        resolve9();
+        resolve10();
       };
       const timer = setInterval(() => {
         if (existsSync16(lock))
@@ -242663,7 +242671,7 @@ function reviewTimeoutMs(diffChars) {
 async function firstValid(promises) {
   if (promises.length === 0)
     return null;
-  return new Promise((resolve9, reject) => {
+  return new Promise((resolve10, reject) => {
     let pending = promises.length;
     let settled = false;
     let lastError;
@@ -242675,7 +242683,7 @@ async function firstValid(promises) {
         if (threw)
           reject(lastError);
         else
-          resolve9(null);
+          resolve10(null);
       }
     };
     for (const p of promises) {
@@ -242684,7 +242692,7 @@ async function firstValid(promises) {
           return;
         if (value !== null) {
           settled = true;
-          resolve9(value);
+          resolve10(value);
           return;
         }
         onNonResult();
@@ -243641,7 +243649,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((resolve9) => {
+  return new Promise((resolve10) => {
     let stdout = "";
     let stderr = "";
     let timedOut = false;
@@ -243659,7 +243667,7 @@ function spawnPeerReviewAgent(input) {
       settled = true;
       if (timer !== void 0)
         clearTimeout(timer);
-      resolve9(result);
+      resolve10(result);
     };
     timer = setTimeout(() => {
       timedOut = true;
@@ -247831,8 +247839,8 @@ Sec-WebSocket-Accept: ${acceptKey}\r
       }
     }
     clients.clear();
-    return new Promise((resolve9) => {
-      server2.close(() => resolve9());
+    return new Promise((resolve10) => {
+      server2.close(() => resolve10());
     });
   };
   return {
@@ -249251,7 +249259,7 @@ function realDeps4() {
     startTmux: startGoTmux,
     followFeed: followGoLiveFeed,
     runOnce: realRunOnce,
-    sleep: (ms) => new Promise((resolve9) => setTimeout(resolve9, ms)),
+    sleep: (ms) => new Promise((resolve10) => setTimeout(resolve10, ms)),
     externalTools: guideExternalToolSetup,
     preinstallChromium: () => {
       silentPreinstallChromium();
@@ -249528,7 +249536,7 @@ function startGoTmux(input) {
   }
 }
 function followGoLiveFeed(projectPath3, rollBin4) {
-  return new Promise((resolve9) => {
+  return new Promise((resolve10) => {
     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 watch2 = spawn7(cmd, args, { cwd: projectPath3, stdio: ["ignore", "inherit", "inherit"] });
@@ -249538,7 +249546,7 @@ function followGoLiveFeed(projectPath3, rollBin4) {
       } catch {
       }
       process.removeListener("SIGINT", finish);
-      resolve9();
+      resolve10();
     };
     process.on("SIGINT", finish);
     watch2.on("exit", finish);
@@ -249549,7 +249557,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((resolve9) => {
+  return new Promise((resolve10) => {
     const child = spawn7(cmd, args, {
       cwd: input.projectPath,
       detached: true,
@@ -249563,8 +249571,8 @@ function realRunOnce(input) {
       },
       stdio: "inherit"
     });
-    child.on("exit", (code) => resolve9(code ?? 1));
-    child.on("error", () => resolve9(1));
+    child.on("exit", (code) => resolve10(code ?? 1));
+    child.on("error", () => resolve10(1));
   });
 }
 function writeGoal(path, goal) {
@@ -254856,8 +254864,8 @@ function nextCommand(args) {
 // packages/cli/dist/commands/design.js
 init_dist();
 import { spawnSync as spawnSync10 } from "node:child_process";
-import { existsSync as existsSync80 } from "node:fs";
-import { join as join83 } from "node:path";
+import { existsSync as existsSync80, statSync as statSync28 } from "node:fs";
+import { join as join83, resolve as resolve7 } from "node:path";
 function lang8() {
   return currentLang();
 }
@@ -254865,17 +254873,24 @@ function emit3(line) {
   process.stderr.write(`${line}
 `);
 }
-function readDesignPrompt() {
+function readDesignPrompt(fromFile) {
   const body = readSkillBody2("roll-design");
   if (body === null)
     return null;
-  return `Run the $roll-design skill below for this project. Follow it end-to-end.
+  const handoff = fromFile === void 0 ? "" : [
+    `The user invoked \`roll design --from-file ${fromFile}\`.`,
+    `Use this product brief file as the design input: ${fromFile}`,
+    "Read it before asking broad discovery questions, then run the $roll-design workflow.",
+    ""
+  ].join("\n");
+  return `${handoff}Run the $roll-design skill below for this project. Follow it end-to-end.
 
 ${body}`;
 }
-function parseAgentFlag(args) {
+function parseDesignFlags(args) {
   const rest = [];
   let agent;
+  let fromFile;
   for (let i = 0; i < args.length; i += 1) {
     const a = args[i] ?? "";
     if (a === "--agent") {
@@ -254883,15 +254898,34 @@ function parseAgentFlag(args) {
       i += 1;
     } else if (a.startsWith("--agent=")) {
       agent = a.slice("--agent=".length);
+    } else if (a === "--from-file") {
+      const value = args[i + 1];
+      if (value === void 0 || value === "" || value.startsWith("-")) {
+        return { agent, fromFile, rest, error: "from_file_missing" };
+      }
+      fromFile = value;
+      i += 1;
+    } else if (a.startsWith("--from-file=")) {
+      const value = a.slice("--from-file=".length);
+      if (value === "")
+        return { agent, fromFile, rest, error: "from_file_missing" };
+      fromFile = value;
     } else {
       rest.push(a);
     }
   }
-  return { agent, rest };
+  return { agent, fromFile, rest, error: null };
 }
 function isRollProject(cwd) {
   return existsSync80(join83(cwd, ".roll"));
 }
+function isRegularFile(path) {
+  try {
+    return statSync28(path).isFile();
+  } catch {
+    return false;
+  }
+}
 var defaultDeps = {
   cwd: process.cwd(),
   env: process.env,
@@ -254948,7 +254982,13 @@ function designCommand(args, deps = {}) {
 `);
     return 0;
   }
-  const { agent: forced, rest } = parseAgentFlag(args);
+  const { agent: forced, fromFile, rest, error: parseError } = parseDesignFlags(args);
+  if (parseError === "from_file_missing") {
+    emit3(t(v3Catalog, l, "design.from_file_missing"));
+    process.stderr.write(`${t(v3Catalog, l, "design.usage")}
+`);
+    return 1;
+  }
   if (rest.some((a) => a.startsWith("-"))) {
     process.stderr.write(`${t(v3Catalog, l, "design.usage")}
 `);
@@ -254958,7 +254998,11 @@ function designCommand(args, deps = {}) {
     emit3(t(v3Catalog, l, "design.not_roll_project"));
     return 1;
   }
-  const prompt = readDesignPrompt();
+  if (fromFile !== void 0 && !isRegularFile(resolve7(d.cwd, fromFile))) {
+    emit3(t(v3Catalog, l, "design.from_file_not_found", fromFile));
+    return 1;
+  }
+  const prompt = readDesignPrompt(fromFile);
   if (prompt === null) {
     emit3(t(v3Catalog, l, "design.skill_missing"));
     return 1;
@@ -255293,7 +255337,7 @@ init_dist3();
 init_dist2();
 init_dist();
 import { spawnSync as spawnSync12 } from "node:child_process";
-import { existsSync as existsSync82, mkdirSync as mkdirSync33, readFileSync as readFileSync74, readdirSync as readdirSync30, renameSync as renameSync14, rmSync as rmSync14, statSync as statSync28, writeFileSync as writeFileSync33 } from "node:fs";
+import { existsSync as existsSync82, mkdirSync as mkdirSync33, readFileSync as readFileSync74, readdirSync as readdirSync30, renameSync as renameSync14, rmSync as rmSync14, statSync as statSync29, writeFileSync as writeFileSync33 } from "node:fs";
 import { homedir as homedir22 } from "node:os";
 import { basename as basename15, dirname as dirname33, join as join85 } from "node:path";
 function palette3() {
@@ -255372,7 +255416,7 @@ function realGcDeps() {
 }
 function fileMtimeSec(f) {
   try {
-    return Math.floor(statSync28(f).mtimeMs / 1e3);
+    return Math.floor(statSync29(f).mtimeMs / 1e3);
   } catch {
     return 0;
   }
@@ -255387,7 +255431,7 @@ function plistWorkingDir(plistPath) {
 }
 function isDir3(p) {
   try {
-    return statSync28(p).isDirectory();
+    return statSync29(p).isDirectory();
   } catch {
     return false;
   }
@@ -255532,7 +255576,7 @@ function loopGcCommand(args = [], deps = realGcDeps()) {
 }
 function statSafeIsFile(f) {
   try {
-    return statSync28(f).isFile();
+    return statSync29(f).isFile();
   } catch {
     return false;
   }
@@ -256636,7 +256680,7 @@ init_dist2();
 init_dist();
 init_dist3();
 import { execFile as execFile10, execFileSync as execFileSync21 } from "node:child_process";
-import { appendFileSync as appendFileSync16, existsSync as existsSync91, lstatSync as lstatSync4, mkdirSync as mkdirSync41, readdirSync as readdirSync34, readFileSync as readFileSync85, realpathSync as realpathSync11, rmSync as rmSync17, statSync as statSync30, symlinkSync as symlinkSync3, unlinkSync as unlinkSync3, writeFileSync as writeFileSync42 } from "node:fs";
+import { appendFileSync as appendFileSync16, existsSync as existsSync91, lstatSync as lstatSync4, mkdirSync as mkdirSync41, readdirSync as readdirSync34, readFileSync as readFileSync85, realpathSync as realpathSync11, rmSync as rmSync17, statSync as statSync31, symlinkSync as symlinkSync3, unlinkSync as unlinkSync3, writeFileSync as writeFileSync42 } from "node:fs";
 import { dirname as dirname40, join as join96 } from "node:path";
 import { promisify as promisify10 } from "node:util";
 
@@ -256699,8 +256743,8 @@ async function probeAgentReachable(agent, spawn11, opts = {}) {
   try {
     res = await Promise.race([
       spawn11(agent, { cwd, skillBody: `Reply with exactly: ${token}`, timeoutMs, bare: true }),
-      new Promise((resolve9) => {
-        setTimeout(() => resolve9(null), timeoutMs).unref();
+      new Promise((resolve10) => {
+        setTimeout(() => resolve10(null), timeoutMs).unref();
       })
     ]);
   } catch (e) {
@@ -256898,7 +256942,7 @@ function clearSelfHeal(runtimeDir9, storyId) {
 
 // packages/cli/dist/runner/usage-recovery.js
 init_dist2();
-import { readFileSync as readFileSync82, readdirSync as readdirSync32, statSync as statSync29 } from "node:fs";
+import { readFileSync as readFileSync82, readdirSync as readdirSync32, statSync as statSync30 } from "node:fs";
 import { homedir as homedir23 } from "node:os";
 import { basename as basename16, join as join93 } from "node:path";
 function defaultPiSessionsRoot() {
@@ -256919,7 +256963,7 @@ function recoverPiUsage(worktreeCwd, sinceSec, sessionsRoot = defaultPiSessionsR
   for (const f of files) {
     const p = join93(dir, f);
     try {
-      if (sinceSec !== void 0 && statSync29(p).mtimeMs / 1e3 < sinceSec)
+      if (sinceSec !== void 0 && statSync30(p).mtimeMs / 1e3 < sinceSec)
         continue;
       summaries.push(sumPiSession(readFileSync82(p, "utf8").split("\n")));
     } catch {
@@ -256966,7 +257010,7 @@ function recoverKimiUsage(worktreeCwd, sinceSec, sessionsRoot = defaultKimiSessi
   const summaries = [];
   for (const p of wireFiles) {
     try {
-      if (sinceSec !== void 0 && statSync29(p).mtimeMs / 1e3 < sinceSec)
+      if (sinceSec !== void 0 && statSync30(p).mtimeMs / 1e3 < sinceSec)
         continue;
       summaries.push(sumKimiWire(readFileSync82(p, "utf8").split("\n")));
     } catch {
@@ -258241,7 +258285,7 @@ ${res.stderr}
               // FIX-319: review-only framing, no worker autorun directive
               ...ctx.evidenceRunDir !== void 0 ? { runDir: ctx.evidenceRunDir } : {}
             }),
-            new Promise((resolve9) => setTimeout(() => resolve9(null), timeoutMs).unref())
+            new Promise((resolve10) => setTimeout(() => resolve10(null), timeoutMs).unref())
           ]);
         } catch (e) {
           const cause = await attributeBlockCause(peer, "error", e instanceof Error ? e.message : String(e), "review");
@@ -258371,7 +258415,7 @@ ${res.stderr}`, "review");
                 timeoutMs,
                 ...ctx.evidenceRunDir !== void 0 ? { runDir: ctx.evidenceRunDir } : {}
               }),
-              new Promise((resolve9) => setTimeout(() => resolve9(null), timeoutMs).unref())
+              new Promise((resolve10) => setTimeout(() => resolve10(null), timeoutMs).unref())
             ]);
           } catch (e) {
             const detail = e instanceof Error ? e.message : String(e);
@@ -259564,7 +259608,7 @@ function nodePorts(opts) {
   const deliveryFreshness = {
     mtimeMs(absPath) {
       try {
-        return statSync30(absPath).mtimeMs;
+        return statSync31(absPath).mtimeMs;
       } catch {
         return void 0;
       }
@@ -261041,10 +261085,10 @@ function autoGc(projectPath3) {
     }
   }
 }
-async function isOffline(resolve9 = (h) => lookup2(h)) {
+async function isOffline(resolve10 = (h) => lookup2(h)) {
   try {
     await Promise.race([
-      resolve9("github.com"),
+      resolve10("github.com"),
       new Promise((_, rej) => {
         const t3 = setTimeout(() => rej(new Error("dns timeout")), 1500);
         if (typeof t3 === "object")
@@ -261113,7 +261157,7 @@ init_dist();
 import { spawnSync as spawnSync14 } from "node:child_process";
 import { existsSync as existsSync96, readFileSync as readFileSync90, realpathSync as realpathSync12, renameSync as renameSync15, rmSync as rmSync18, writeFileSync as writeFileSync47 } from "node:fs";
 import { homedir as homedir24 } from "node:os";
-import { join as join101, resolve as resolve7 } from "node:path";
+import { join as join101, resolve as resolve8 } from "node:path";
 function pal5() {
   const noColor2 = (process.env["NO_COLOR"] ?? "") !== "";
   return noColor2 ? { RED: "", GREEN: "", YELLOW: "", CYAN: "", BOLD: "", NC: "" } : {
@@ -261217,7 +261261,7 @@ function writeFileAtomic2(path, text2) {
   }
 }
 function resolveChangesetItem(projectDir, item) {
-  return item.startsWith("/") ? resolve7(item) : resolve7(projectDir, item);
+  return item.startsWith("/") ? resolve8(item) : resolve8(projectDir, item);
 }
 var HELP4 = `Usage: roll offboard [--confirm]
   Preview (default) or apply (--confirm) the removal of every
@@ -261238,7 +261282,7 @@ function offboardCommand(args) {
   }
   let projectDir;
   try {
-    projectDir = realpathSync12(resolve7(process.cwd()));
+    projectDir = realpathSync12(resolve8(process.cwd()));
   } catch {
     projectDir = process.cwd();
   }
@@ -262025,7 +262069,7 @@ init_dist2();
 init_dist();
 init_render();
 import { execFileSync as execFileSync23 } from "node:child_process";
-import { existsSync as existsSync100, mkdirSync as mkdirSync48, readFileSync as readFileSync94, readdirSync as readdirSync38, statSync as statSync31, writeFileSync as writeFileSync50 } from "node:fs";
+import { existsSync as existsSync100, mkdirSync as mkdirSync48, readFileSync as readFileSync94, readdirSync as readdirSync38, statSync as statSync32, writeFileSync as writeFileSync50 } from "node:fs";
 import { dirname as dirname46, join as join105 } from "node:path";
 
 // packages/cli/dist/lib/consistency-audit.js
@@ -262329,7 +262373,7 @@ function lineNumberAt(text2, index) {
 function existingTextFiles(projectDir, rels) {
   return rels.map((rel) => ({ rel, abs: join105(projectDir, rel) })).filter((f) => {
     try {
-      return statSync31(f.abs).isFile();
+      return statSync32(f.abs).isFile();
     } catch {
       return false;
     }
@@ -262473,7 +262517,7 @@ function backlogRowFacts(backlogText) {
 var nodeFreshnessPort2 = {
   mtimeMs(absPath) {
     try {
-      return statSync31(absPath).mtimeMs;
+      return statSync32(absPath).mtimeMs;
     } catch {
       return void 0;
     }
@@ -262811,7 +262855,7 @@ function listFiles2(dir) {
   try {
     return readdirSync38(dir).filter((n) => {
       try {
-        return statSync31(join105(dir, n)).isFile();
+        return statSync32(join105(dir, n)).isFile();
       } catch {
         return false;
       }
@@ -262888,7 +262932,7 @@ function rglobBats(dir) {
       const full = join105(d, e);
       let st;
       try {
-        st = statSync31(full);
+        st = statSync32(full);
       } catch {
         continue;
       }
@@ -263698,7 +263742,7 @@ ${c("dim", "\u2192 Running the golden-path showcase (real models; its verdict do
 init_dist();
 init_render();
 import { spawnSync as spawnSync16 } from "node:child_process";
-import { existsSync as existsSync103, lstatSync as lstatSync5, mkdirSync as mkdirSync50, readFileSync as readFileSync97, readdirSync as readdirSync40, readlinkSync as readlinkSync2, statSync as statSync33 } from "node:fs";
+import { existsSync as existsSync103, lstatSync as lstatSync5, mkdirSync as mkdirSync50, readFileSync as readFileSync97, readdirSync as readdirSync40, readlinkSync as readlinkSync2, statSync as statSync34 } from "node:fs";
 import { join as join108 } from "node:path";
 function err13(line) {
   const noColor2 = (process.env["NO_COLOR"] ?? "") !== "";
@@ -263736,7 +263780,7 @@ function setupSnapshot(watch2) {
       continue;
     let isDir4 = false;
     try {
-      isDir4 = statSync33(d).isDirectory();
+      isDir4 = statSync34(d).isDirectory();
     } catch {
       isDir4 = false;
     }
@@ -263770,7 +263814,7 @@ function walk(dir, lines2) {
     }
     let st;
     try {
-      st = statSync33(p);
+      st = statSync34(p);
     } catch {
       continue;
     }
@@ -264016,7 +264060,7 @@ init_showcase2();
 // packages/cli/dist/commands/test.js
 import { spawnSync as spawnSync17 } from "node:child_process";
 import { appendFileSync as appendFileSync20, existsSync as existsSync104, mkdirSync as mkdirSync51, readFileSync as readFileSync98, rmSync as rmSync20, writeFileSync as writeFileSync53 } from "node:fs";
-import { dirname as dirname48, join as join109, resolve as resolve8 } from "node:path";
+import { dirname as dirname48, join as join109, resolve as resolve9 } 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" };
@@ -264036,7 +264080,7 @@ function currentEvidenceFrame() {
   const raw = (process.env["ROLL_RUN_DIR"] ?? "").trim();
   if (raw === "")
     return null;
-  const runDir = resolve8(raw);
+  const runDir = resolve9(raw);
   if (!existsSync104(runDir))
     return null;
   const frame = {
@@ -264369,7 +264413,7 @@ function pad4(value, width) {
 // packages/cli/dist/commands/truth.js
 init_dist();
 init_dist2();
-import { statSync as statSync34, readFileSync as readFileSync99, writeFileSync as writeFileSync54, mkdirSync as mkdirSync52, existsSync as existsSync105 } from "node:fs";
+import { statSync as statSync35, readFileSync as readFileSync99, writeFileSync as writeFileSync54, mkdirSync as mkdirSync52, existsSync as existsSync105 } from "node:fs";
 import { dirname as dirname49, join as join111 } from "node:path";
 var TRUTH_USAGE = "Usage: roll truth <command>\n  query <storyId>  Deterministic delivery-truth query (structured, zero markdown parse).\n  audit            Bidirectional drift audit: backlog Done \u2194 projection truth.\n\u547D\u4EE4:\n  query <storyId>  \u7ED3\u6784\u5316\u4EA4\u4ED8\u771F\u76F8\u67E5\u8BE2\uFF08\u786E\u5B9A\u6027\uFF0C\u4E0D\u89E3\u6790 markdown\uFF09\n  audit            \u53CC\u5411\u6F02\u79FB\u5BA1\u8BA1\uFF1Abacklog Done \u2194 \u6295\u5F71\u771F\u76F8";
 function formatTruth(t3, lang11) {
@@ -264395,7 +264439,7 @@ function formatTruth(t3, lang11) {
 var nodeFreshnessPort3 = {
   mtimeMs(absPath) {
     try {
-      return statSync34(absPath).mtimeMs;
+      return statSync35(absPath).mtimeMs;
     } catch {
       return void 0;
     }
@@ -264943,7 +264987,7 @@ function registerAll() {
   registerPorted("config", configCommand);
   registerPorted("init", initCommand, { help: "Usage: roll init [--auto|--repair|--apply]\n  Diagnose this project and route to scaffold, PRD design, existing-codebase onboard, repair, migration, or roll status.\n  --auto: apply deterministic fresh-project scaffolding in non-interactive runs.\n  --repair: repair partial Roll markers only.\n  --apply: validate and apply a reviewed existing-codebase onboard plan.\n\u8BCA\u65AD\u9879\u76EE\u5E76\u8DEF\u7531\u5230\u9AA8\u67B6\u3001PRD \u8BBE\u8BA1\u3001\u5DF2\u6709\u4EE3\u7801\u5E93\u63A5\u5165\u3001\u4FEE\u590D\u3001\u8FC1\u79FB\u6216 roll status\u3002\n  --apply\uFF1A\u6821\u9A8C\u5E76\u5E94\u7528\u5DF2\u5BA1\u9605\u7684\u5DF2\u6709\u4EE3\u7801\u5E93\u63A5\u5165\u8BA1\u5212\u3002" });
   registerPorted("next", nextCommand, { help: NEXT_USAGE });
-  registerPorted("design", designCommand, { help: "Usage: roll design [--agent <name>]\n  Launch $roll-design interactively.\n\u4EA4\u4E92\u5F0F\u542F\u52A8 $roll-design\u3002" });
+  registerPorted("design", designCommand, { help: "Usage: roll design [--from-file <path>] [--agent <name>]\n  Launch $roll-design interactively; --from-file binds a PRD/brief.\n\u4EA4\u4E92\u5F0F\u542F\u52A8 $roll-design\uFF1B--from-file \u7ED1\u5B9A PRD/brief\u3002" });
   registerPorted("offboard", offboardCommand);
   registerPorted("setup", (args) => {
     if (args[0] === "skills") {

package/package.json

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