@guanlin4924/devflow-pi 0.1.98 → 0.1.99

package/plugins/devflow-core/extensions/devflow-core.ts

@@ -1,7 +1,7 @@
 import { createHash, createHmac, randomBytes, randomUUID } from "node:crypto";
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import { appendFile, mkdir, rename, unlink, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
@@ -16,7 +16,21 @@ import { loadProjectContext } from "../../../src/project-context.ts";
 import { runProjectInitialization } from "../../../src/project-initializer.ts";
 import { projectControlDatabasePath } from "../../../src/paths.ts";
 import { generateProjectDocuments } from "../../../src/project-documents.ts";
+import { preparedRolloverRevision } from "../../../src/session-rollover.ts";
 import { describeStartupIssue, renderStartupBriefing } from "../../../src/startup-briefing.ts";
+import { PRODUCT_VERSION } from "../../../src/constants.ts";
+import {
+  FIX_LABELS,
+  buildHelpBundle,
+  classifyNextStepPhrase,
+  describeControlFailure,
+  diagnoseWorkflow,
+  renderDiagnosis,
+  summarizeToolFailure,
+  type FixAction,
+  type ToolFailureRecord,
+  type WorkflowDiagnosis,
+} from "../../../src/workflow-diagnosis.ts";
 import { exportInitializationSnapshot, importLegacyInitialization, switchInitializationAuthority } from "../../../src/project-migration.ts";
 import { migrateLegacyProjectLayout } from "../../../src/project-layout.ts";
 import {
@@ -37,6 +51,15 @@ import {
 
 export type DevflowIntent = "idle" | "explain-state" | "project-init" | "requirement-draft" | "workflow-execute";
 
+/** Used only after the runtime receives an explicit user checkpoint approval. */
+export function wireframeApprovalArgs(feature: string, revision: number): string[] {
+  return [
+    "--action", "approve", "--feature", feature,
+    "--expected-revision", String(revision), "--approved-by", "user",
+    "--all-screens", "--runtime-confirmed", "--write", "--json",
+  ];
+}
+
 export type ControlPhase = "idle" | "planning" | "awaiting-approval" | "waiting-user" | "executing" | "blocked";
 
 export type SessionControlState = {
@@ -581,6 +604,10 @@ export function isVirtualStateTransitionResource(toolName: string, input: unknow
   return [record.path, record.uri, record.resource].some(value => value === "xd://devflow_transition");
 }
 
+export const OUTSIDE_STEP_WRITE_REASON =
+  "当前不在受控的工作流步骤中：在这里写入 .devflow/planning/requirements 或 features 下的需求产物不会被工作流采纳，已拒绝。" +
+  "不要改用其他方式写入这些文件。请停止写入，把已有结论直接告诉用户，并请用户说「下一步」（还没有需求时先创建需求），由 Devflow 启动对应步骤后再写。";
+
 export function planningToolBlockReason(toolName: string): string {
   return `Devflow ${toolName} blocked: current intent is planning. Planning is read-only; present an Evidence Pack or plan and wait for explicit approval before writing or executing.`;
 }
@@ -756,6 +783,9 @@ type DoctorContext = {
   };
 };
 
+type DevflowCommandHandler = Parameters<ExtensionAPI["registerCommand"]>[1]["handler"];
+type DevflowCommandContext = Parameters<DevflowCommandHandler>[1];
+
 const CONTROL_PATHS = [
   ".devflow/planning/STATE.md",
   ".devflow/planning/.next-intent",
@@ -1131,8 +1161,31 @@ async function runProcess(
   };
 }
 
+/** Raw failures kept in memory for the user's help bundle; never sent to the model. */
+const recentToolFailures: ToolFailureRecord[] = [];
+
+function recordToolFailure(tool: string, result: ProcessResult, summary: string): void {
+  recentToolFailures.push({
+    at: new Date().toISOString(),
+    tool,
+    exitCode: result.exitCode,
+    summary,
+    raw: (result.stderr || result.stdout).slice(0, 4000),
+  });
+  if (recentToolFailures.length > 20) recentToolFailures.splice(0, recentToolFailures.length - 20);
+}
+
 function renderResult(result: ProcessResult, details: Record<string, unknown> = {}) {
-  const text = result.stdout || result.stderr || `Process exited with ${result.exitCode}`;
+  // JSON output passes through unchanged; plain-text failures and empty output
+  // become a Chinese summary instead of a raw stack trace.
+  const summary = summarizeToolFailure(result);
+  if (summary && !result.ok) recordToolFailure(String(details.action ?? "devflow"), result, summary);
+  const raw = (result.stderr || result.stdout).trim();
+  // Stack traces collapse to the summary; other plain-text failures may list
+  // several problems, so the model still sees them in full.
+  const keepRaw = summary !== null && !result.ok && raw !== "" && !summary.includes(raw)
+    && !/:\d+:in [`']|Traceback \(most recent call last\)/u.test(raw);
+  const text = summary === null ? (result.stdout || result.stderr) : keepRaw ? `${summary}\n\n原始信息：\n${raw.slice(0, 2000)}` : summary;
   return {
     content: [{ type: "text" as const, text }],
     details: { ...details, exitCode: result.exitCode, stderr: result.stderr || undefined },
@@ -1261,7 +1314,7 @@ function selectedWorkflowStep(snapshot: Record<string, unknown>): Record<string,
  * completed step. This predicate lets the runtime re-arm approval handling
  * from the Core-owned snapshot without granting approval by itself.
  */
-function isReviewableWorkflowSnapshot(snapshot: Record<string, unknown>): boolean {
+function isReviewableWorkflowSnapshot(snapshot: Record<string, unknown>, options: { strictRegistry?: boolean } = {}): boolean {
   const status = snapshot.status;
   if (status !== "waiting_checkpoint" && status !== "not_started" && status !== "in_progress") return false;
   const step = snapshot.current_step;
@@ -1284,9 +1337,15 @@ function isReviewableWorkflowSnapshot(snapshot: Record<string, unknown>): boolea
     // Core has already validated and registered the artifact. Treat an
     // explicit false as invalid, but use exists + artifact_status as the
     // durable fallback when the field is absent.
+    // sync_artifacts.rb keeps every output of an unfinished non-checkpoint
+    // step at `planned`, so `planned` must not hide an output the step has
+    // already written. advance_state.rb re-validates outputs on transition.
+    // Resume disposition stays strict so an existing file never lets a step
+    // start without contract activation.
+    const rejected = options.strictRegistry ? ["failed", "blocked", "planned"] : ["failed", "blocked"];
     return record.exists === true
       && record.content_valid !== false
-      && !["failed", "blocked", "planned"].includes(String(record.artifact_status ?? ""));
+      && !rejected.includes(String(record.artifact_status ?? ""));
   });
 }
 
@@ -1314,13 +1373,13 @@ export function workflowResumeDisposition(snapshot: Record<string, unknown>): Wo
   if (!feature || !stepId || typeof revision !== "number" || !Number.isInteger(revision)) return "idle";
 
   if (action === "await_user_confirmation") {
-    return isReviewableWorkflowSnapshot(snapshot) ? "review" : "blocked";
+    return isReviewableWorkflowSnapshot(snapshot, { strictRegistry: true }) ? "review" : "blocked";
   }
   // Parallel windows must be reconstructed by the Runtime even if a stale
   // join artifact happens to exist; branch lifecycle is the join authority.
   if (action === "run_parallel_window" || action === "route_failure_branch") return "execute";
   if (action === "run_next_step") {
-    return isReviewableWorkflowSnapshot(snapshot) ? "review" : "execute";
+    return isReviewableWorkflowSnapshot(snapshot, { strictRegistry: true }) ? "review" : "execute";
   }
   return "blocked";
 }
@@ -2675,6 +2734,9 @@ export default function devflowCore(pi: ExtensionAPI) {
   }
 
   let activeWorkflowTurn = false;
+  // Set once the /devflow command is defined; lets the input handler and the
+  // next-step entry reuse existing subcommands (start, abandon).
+  let devflowCommandRef: ((args: string, ctx: DevflowCommandContext) => Promise<void>) | undefined;
   let parallelRunActive = false;
   let parallelContinuationQueued = false;
   let parallelDispatchSucceededThisTurn = false;
@@ -2880,6 +2942,17 @@ export default function devflowCore(pi: ExtensionAPI) {
       ctx.ui.notify("已保留当前步骤，未推进工作流。", "info");
       return true;
     }
+    if (checkpoint && stepId === "wireframe-review") {
+      const feature = inspected.snapshot.current_feature;
+      if (typeof feature !== "string") return false;
+      const approval = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/wireframe_commit.rb",
+        wireframeApprovalArgs(feature, revision));
+      if (!controlPlaneSucceeded(approval)) {
+        setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "原型确认写入失败" });
+        ctx.ui.notify(`原型确认未写入：${approval.stderr || approval.stdout}`, "error");
+        return true;
+      }
+    }
     const result = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/advance_state.rb", [
       "--write", "--json", "--expected-revision", String(revision),
       ...(checkpoint ? ["--confirm-checkpoint", "--runtime-confirmed"] : ["--complete-step", stepId]),
@@ -2887,7 +2960,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     ]);
     if (!result.ok || !controlPlaneSucceeded(result)) {
       setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "推进校验失败" });
-      ctx.ui.notify(`未推进：${result.stderr || result.stdout}`, "error");
+      ctx.ui.notify(`未推进：${describeControlFailure(result)}\n可以说「下一步」重新诊断，或选择重新执行这一步来修复产物。`, "error");
       return true;
     }
     const after = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
@@ -2909,6 +2982,183 @@ export default function devflowCore(pi: ExtensionAPI) {
     return true;
   }
 
+  async function diagnoseCurrentWorkflow(cwd: string): Promise<{
+    snapshot: Record<string, unknown> | null;
+    inspectError?: string;
+    rolloverState: Record<string, unknown> | null;
+    diagnosis: WorkflowDiagnosis;
+  }> {
+    const inspected = await inspectWorkflowWithRegistryRecovery(cwd);
+    // A missing STATE.md is reported as structured JSON, not always with exit 0.
+    const snapshot = inspected.snapshot ?? parseJsonOutput(inspected.result);
+    const inspectError = snapshot ? undefined : (inspected.result.stderr || inspected.result.stdout || "invalid inspector JSON");
+    const rolloverState = snapshot?.current_feature
+      ? parseJsonResult(await runRuby(cwd, "workflow-orchestrator/scripts/session_rollover.rb", ["inspect", "--json"]))
+      : null;
+    const rollover = rolloverState?.rollover as Record<string, unknown> | undefined;
+    const diagnosis = diagnoseWorkflow({
+      inspect: { ok: Boolean(snapshot), error: inspectError },
+      snapshot,
+      disposition: snapshot ? workflowResumeDisposition(snapshot) : "idle",
+      outputsReady: snapshot ? isReviewableWorkflowSnapshot(snapshot) : false,
+      rolloverPrepared: Boolean(rolloverState && typeof rolloverState.revision === "number"
+        && rollover?.status === "prepared" && typeof rollover.id === "string"),
+    });
+    return { snapshot, inspectError, rolloverState, diagnosis };
+  }
+
+  async function writeHelpBundle(
+    ctx: DevflowCommandContext,
+    current: Awaited<ReturnType<typeof diagnoseCurrentWorkflow>>,
+  ): Promise<string> {
+    const report = await runDoctor(ctx).catch(() => undefined);
+    const createdAt = new Date().toISOString();
+    const bundle = buildHelpBundle({
+      version: PRODUCT_VERSION,
+      createdAt,
+      diagnosis: current.diagnosis,
+      snapshot: current.snapshot,
+      inspectError: current.inspectError,
+      doctor: report?.checks,
+      rollover: current.rolloverState,
+      failures: recentToolFailures,
+      root: ctx.cwd,
+      home: homedir(),
+    });
+    // .devflow/runs is the git-ignored runtime output root.
+    const relative = `.devflow/runs/diagnostics/help-${createdAt.replace(/[:.]/g, "-")}.json`;
+    await mkdir(path.dirname(path.join(ctx.cwd, relative)), { recursive: true });
+    await writeFile(path.join(ctx.cwd, relative), `${JSON.stringify(bundle, null, 2)}\n`, "utf8");
+    return relative;
+  }
+
+  function nextStepHint(diagnosis: WorkflowDiagnosis): string {
+    if (diagnosis.kind === "blocked") return "运行 /devflow fix 查看处理办法。";
+    if (diagnosis.kind === "no-feature" || diagnosis.kind === "complete") return "说「下一步」或运行 /devflow start <需求名> 创建需求。";
+    return "说「下一步」或运行 /devflow next 继续。";
+  }
+
+  async function showWorkflowOverview(ctx: DevflowCommandContext): Promise<void> {
+    const { diagnosis } = await diagnoseCurrentWorkflow(ctx.cwd);
+    ctx.ui.notify(`${renderDiagnosis(diagnosis)}\n\n${nextStepHint(diagnosis)}`, diagnosis.kind === "blocked" ? "error" : "info");
+  }
+
+  /** Fixes that start or advance a step; `/devflow fix` never offers them. */
+  const ADVANCING_FIXES = new Set<FixAction>(["review-and-advance", "rerun-step", "resume-rollover", "create-feature"]);
+
+  /**
+   * Single user entry: diagnose → offer a fix from the closed catalog → let
+   * Core execute it → re-diagnose. The model is never asked to repair control
+   * state; every write goes through the existing runtime/Core paths.
+   */
+  async function runNextStep(ctx: DevflowCommandContext, mode: "next" | "fix"): Promise<void> {
+    if (activeWorkflowTurn || controlState.phase === "executing") {
+      ctx.ui.notify("当前步骤正在执行，等这一轮结束后再说「下一步」。", "info");
+      return;
+    }
+    if (mode === "next") {
+      const report = await runDoctor(ctx);
+      if (!report.ok) {
+        ctx.ui.notify(`运行环境检查没有通过，暂时不能推进：\n${formatDoctorReport(report).slice(0, 6000)}`, "error");
+        return;
+      }
+    }
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+      const current = await diagnoseCurrentWorkflow(ctx.cwd);
+      const { diagnosis, snapshot } = current;
+      const summary = renderDiagnosis(diagnosis);
+      if (diagnosis.kind === "execute" && snapshot) {
+        if (mode === "fix") {
+          ctx.ui.notify(`${summary}\n${nextStepHint(diagnosis)}`, "info");
+          return;
+        }
+        await resumeInspectedWorkflow(ctx, snapshot, { doctorAlreadyPassed: true });
+        return;
+      }
+      const fixes = diagnosis.diagnoses
+        .flatMap(item => item.fixes)
+        .filter(fix => mode === "next" || !ADVANCING_FIXES.has(fix));
+      ctx.ui.notify(fixes.length > 0 || mode === "next" ? summary : `${summary}\n${nextStepHint(diagnosis)}`, diagnosis.kind === "blocked" ? "error" : "info");
+      if (fixes.length === 0) return;
+      const skip = "暂不处理";
+      const choice = await ctx.ui.select("选择处理方式", [
+        ...fixes.map(fix => ({ label: FIX_LABELS[fix].label, description: FIX_LABELS[fix].description })),
+        { label: skip, description: "保持现状，不做任何修改" },
+      ]);
+      const fix = fixes.find(item => FIX_LABELS[item].label === choice);
+      if (!fix) {
+        ctx.ui.notify("已保持现状，未做任何修改。", "info");
+        return;
+      }
+      if (fix === "create-feature") {
+        const name = (await ctx.ui.input("创建需求", "需求名称，例如：私海线索转回公海保护"))?.trim();
+        if (!name) {
+          ctx.ui.notify("未输入需求名称，未创建需求。", "info");
+          return;
+        }
+        await devflowCommandRef?.(`start ${name}`, ctx);
+        return;
+      }
+      if (fix === "review-and-advance") {
+        setControlState(ctx, waitingUserState("等待用户审查步骤产物并明确决定"));
+        if (!(await confirmAndAdvanceWorkflowStep(ctx))) {
+          ctx.ui.notify("无法打开推进确认：当前步骤的产物已经变化。请重新说「下一步」。", "error");
+        }
+        return;
+      }
+      if (fix === "revise-outputs") {
+        setControlState(ctx, waitingUserState("等待用户审查步骤产物并明确决定"));
+        ctx.ui.notify("已回到审查状态。请直接说明需要修改的内容；改完后说「批准执行」或「下一步」推进。", "info");
+        return;
+      }
+      if (fix === "rerun-step" && snapshot) {
+        const stepId = diagnosis.stepId ?? "当前步骤";
+        setControlState(ctx, executingState("开工预检中"));
+        void startWorkflowAfterPreflight(ctx, snapshot, "start", {
+          doctorAlreadyPassed: true,
+          executingLabel: `重新执行 ${stepId}`,
+        }).catch(error => {
+          setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "开工预检未通过" });
+          ctx.ui.notify(`开工预检未通过：${String(error)}`, "error");
+        });
+        return;
+      }
+      if (fix === "resume-rollover" && snapshot) {
+        const rollover = current.rolloverState?.rollover as Record<string, unknown> | undefined;
+        if (typeof current.rolloverState?.revision !== "number" || typeof rollover?.id !== "string") return;
+        pendingRollover = { snapshot, preparedRevision: current.rolloverState.revision, rolloverId: rollover.id };
+        await enqueueControlledRolloverRequest(ctx.cwd, rollover.id, ctx.sessionManager.getSessionId());
+        setControlState(ctx, waitingUserState("正在恢复受控会话交接"));
+        ctx.ui.notify("已恢复未完成的会话交接；当前回合结束后会切换到新会话并继续。", "info");
+        return;
+      }
+      if (fix === "repair-registry") {
+        const plan = snapshot?.recovery_plan as Record<string, unknown> | undefined;
+        if (typeof plan?.expected_revision !== "number") return;
+        const result = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/repair_control_plane.rb", [
+          "--write", "--confirm", "--expected-revision", String(plan.expected_revision), "--json",
+        ]);
+        if (!controlPlaneSucceeded(result)) {
+          ctx.ui.notify(`登记表修复失败：${describeControlFailure(result)}`, "error");
+          return;
+        }
+        ctx.ui.notify("登记表已修复，未推进工作流。正在重新诊断……", "info");
+        continue;
+      }
+      if (fix === "help-bundle") {
+        const bundlePath = await writeHelpBundle(ctx, current);
+        ctx.ui.notify(`已生成求助包：${bundlePath}\n只包含诊断信息（状态摘要、校验错误、最近的工具报错），不含源码。可以把这个文件发给维护者。`, "info");
+        return;
+      }
+      if (fix === "cancel-feature") {
+        await devflowCommandRef?.("abandon", ctx);
+        return;
+      }
+      return;
+    }
+    ctx.ui.notify("自动修复后仍有问题。请运行 /devflow fix 并选择「生成求助包」。", "error");
+  }
+
   type ProjectControlCommandContext = {
     cwd: string;
     models: DoctorContext["models"];
@@ -3321,7 +3571,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     // sole authority: only the original source session may resume a prepared
     // transition, and only the already-recorded target may consume a claim.
     const rolloverResult = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/session_rollover.rb", ["inspect", "--json"]);
-    const rolloverState = parseJsonResult(rolloverResult);
+    let rolloverState = parseJsonResult(rolloverResult);
     let rollover = rolloverState?.rollover as Record<string, unknown> | undefined;
     const currentSessionId = ctx.sessionManager.getSessionId();
     if (
@@ -3334,13 +3584,14 @@ export default function devflowCore(pi: ExtensionAPI) {
       ]);
       if (recovered.ok) {
         const refreshed = parseJsonResult(await runRuby(ctx.cwd, "workflow-orchestrator/scripts/session_rollover.rb", ["inspect", "--json"]));
+        rolloverState = refreshed;
         rollover = refreshed?.rollover as Record<string, unknown> | undefined;
       }
     }
     if (rolloverState && typeof rolloverState.revision === "number" && rollover?.status === "prepared" && typeof rollover.id === "string") {
       const workflow = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
-      const expectedStateRevision = typeof rollover.expected_state_revision === "number" ? rollover.expected_state_revision : undefined;
-      if (workflow.result.ok && workflow.snapshot && expectedStateRevision !== undefined && expectedStateRevision + 1 === rolloverState.revision) {
+      const preparedRevision = preparedRolloverRevision(rolloverState);
+      if (workflow.result.ok && workflow.snapshot && preparedRevision !== undefined && workflow.snapshot.revision === preparedRevision) {
         pendingRollover = { snapshot: workflow.snapshot, preparedRevision: rolloverState.revision, rolloverId: rollover.id };
         await enqueueControlledRolloverRequest(ctx.cwd, rollover.id, currentSessionId);
         ctx.ui.notify("已恢复待完成的受控会话交接；当前回合结束后将继续切换。", "info");
@@ -3507,7 +3758,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     if (event.source !== "interactive") return;
     const controlAction = classifyNaturalControlAction(event.text);
     const stepNote = event.text.trim();
-    if (controlState.intent === "workflow-execute" && !controlAction && stepNote && !stepNote.startsWith("/")) {
+    if (controlState.intent === "workflow-execute" && !controlAction && stepNote && !stepNote.startsWith("/") && !classifyNextStepPhrase(stepNote)) {
       stepUserNotes.push(stepNote);
     }
     if (controlState.intent === "requirement-draft" && controlState.phase === "planning") {
@@ -3561,6 +3812,24 @@ export default function devflowCore(pi: ExtensionAPI) {
       }
       return { handled: true };
     }
+    // Short phrases such as "下一步" open the same diagnose-and-fix entry as
+    // /devflow next. They never approve by themselves: advancing still needs
+    // the runtime confirmation dialog. "继续" is only taken over when a
+    // feature is in progress so ordinary chat continuation reaches the model.
+    const nextPhrase = classifyNextStepPhrase(event.text);
+    if (nextPhrase && ctx.hasUI && ["idle", "waiting-user", "blocked"].includes(controlState.phase)) {
+      let takeOver = nextPhrase === "next";
+      if (nextPhrase === "continue") {
+        const inspected = await inspectWorkflow(ctx.cwd);
+        takeOver = typeof inspected.snapshot?.current_feature === "string"
+          && !["completed", "cancelled", "failed"].includes(String(inspected.snapshot.status));
+      }
+      if (takeOver) {
+        // runNextStep only uses members shared by event and command contexts.
+        await runNextStep(ctx as DevflowCommandContext, "next");
+        return { handled: true };
+      }
+    }
     // The in-memory prompt state is intentionally not authoritative. A fresh
     // session starts idle, so recover the approval arm from the durable Core
     // snapshot before handing an explicit approval phrase to the model. This
@@ -3596,10 +3865,8 @@ export default function devflowCore(pi: ExtensionAPI) {
           return { handled: true };
         }
         if (checkpoint && stepId === "wireframe-review" && typeof inspected.snapshot.current_feature === "string") {
-          const approval = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/wireframe_commit.rb", [
-            "--action", "approve", "--feature", inspected.snapshot.current_feature,
-            "--expected-revision", String(revision), "--all-screens", "--runtime-confirmed", "--write", "--json",
-          ]);
+          const approval = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/wireframe_commit.rb",
+            wireframeApprovalArgs(inspected.snapshot.current_feature, revision));
           if (!controlPlaneSucceeded(approval)) {
             setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "原型确认写入失败" });
             ctx.ui.notify(`原型确认未写入：${approval.stderr || approval.stdout}`, "error");
@@ -3615,7 +3882,7 @@ export default function devflowCore(pi: ExtensionAPI) {
         ]);
         if (!result.ok || !controlPlaneSucceeded(result)) {
           setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "推进校验失败" });
-          ctx.ui.notify(`未推进：${result.stderr || result.stdout}\n请补齐上述校验缺项后重新审批；重复批准不会绕过门禁。可请求重新执行当前步骤以修复产物。`, "error");
+          ctx.ui.notify(`未推进：${describeControlFailure(result)}\n请补齐上述校验缺项后重新审批；重复批准不会绕过门禁。可以说「下一步」重新诊断，或选择重新执行这一步来修复产物。`, "error");
           return { handled: true };
         }
         const after = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
@@ -3852,6 +4119,20 @@ export default function devflowCore(pi: ExtensionAPI) {
         reason: "规范需求图谱、派生视图、机器 Evidence 与合同审计只能由 Core writer 写入；Skill 只能提交候选 delta 或 agent_claim。",
       };
     }
+    // Feature artifacts written while no step is running are never adopted by
+    // the workflow (zhaoshang, 2026-10-22). Refuse early in the interactive
+    // main session; subagents (no UI), review-feedback edits and controlled
+    // turns keep their existing rules.
+    if (
+      ctx.hasUI &&
+      controlState.phase === "idle" &&
+      !activeWorkflowTurn &&
+      !toolName.startsWith("devflow_") &&
+      ["write", "edit", "apply_patch", "notebook_edit"].includes(toolName) &&
+      inputPaths(event.input, ctx.cwd).some(filePath => planningFeatureFromPath(filePath) !== null)
+    ) {
+      return { block: true, reason: OUTSIDE_STEP_WRITE_REASON };
+    }
     if (
       !toolName.startsWith("devflow_") &&
       ["write", "edit", "apply_patch", "notebook_edit"].includes(toolName)
@@ -4327,6 +4608,8 @@ export default function devflowCore(pi: ExtensionAPI) {
       kind: z.string().optional(),
       match: z.string().optional(),
       expected: z.unknown().optional(),
+      normalize_whitespace: z.boolean().optional(),
+      case_sensitive: z.boolean().optional(),
       name: z.string().optional(),
       tc_id: z.string().optional(),
     }),
@@ -4385,7 +4668,7 @@ export default function devflowCore(pi: ExtensionAPI) {
           Object.assign(requestParams, { ref: params.ref, action: params.operation, value: params.value, value_from_secret: params.value_from_secret });
         } else if (params.action === "assert") {
           if (!params.ref || !params.kind || !["text", "visible", "value", "each_text"].includes(params.kind)) return fail("assert requires ref and a supported kind");
-          Object.assign(requestParams, { ref: params.ref, kind: params.kind, match: params.match, expected: params.expected });
+          Object.assign(requestParams, { ref: params.ref, kind: params.kind, match: params.match, expected: params.expected, normalize_whitespace: params.normalize_whitespace, case_sensitive: params.case_sensitive });
         } else if (params.action === "draft") {
           if (!params.name) return fail("draft requires name");
           Object.assign(requestParams, { name: params.name, tc_id: params.tc_id });
@@ -5237,273 +5520,288 @@ export default function devflowCore(pi: ExtensionAPI) {
     },
   });
 
-  pi.registerCommand("devflow", {
-    description: "Devflow runtime: inspect, initialize, plan, run one step, or explicitly advance the controlled delivery pipeline",
-    handler: async (args, ctx) => {
-      const trimmed = args.trim();
-      if (trimmed === "" || trimmed === "status") {
-        const result = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/inspect_state.rb", ["--json"]);
-        ctx.ui.notify((result.stdout || result.stderr).slice(0, 6000), result.ok ? "info" : "error");
+  const devflowCommand = async (args: string, ctx: DevflowCommandContext): Promise<void> => {
+    const trimmed = args.trim();
+    if (trimmed === "" || trimmed === "status") {
+      await showWorkflowOverview(ctx);
+      return;
+    }
+    if (trimmed === "status --json") {
+      const result = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/inspect_state.rb", ["--json"]);
+      ctx.ui.notify((result.stdout || result.stderr).slice(0, 6000), result.ok ? "info" : "error");
+      return;
+    }
+    if (trimmed === "next" || trimmed === "下一步") {
+      await runNextStep(ctx, "next");
+      return;
+    }
+    if (trimmed === "fix") {
+      await runNextStep(ctx, "fix");
+      return;
+    }
+    if (trimmed === "control") {
+      await openProjectControlPanel(ctx);
+      return;
+    }
+    if (trimmed === "explain-state") {
+      const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
+      ctx.ui.notify(
+        inspected.result.ok ? explainWorkflowSnapshot(inspected.snapshot) : `状态读取失败：${inspected.result.stderr || inspected.result.stdout}`,
+        inspected.result.ok ? "info" : "error",
+      );
+      setControlState(ctx, initialControlState());
+      return;
+    }
+    if (trimmed === "recover") {
+      const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
+      const plan = inspected.snapshot?.recovery_plan as Record<string, unknown> | undefined;
+      const revision = plan?.expected_revision;
+      if (!inspected.result.ok || !plan || plan.classification !== "safe_repairable" || typeof revision !== "number") {
+        const status = typeof inspected.snapshot?.status === "string" ? inspected.snapshot.status : "unknown";
+        const step = inspected.snapshot ? selectedWorkflowStep(inspected.snapshot) : null;
+        const stepId = typeof step?.id === "string" ? step.id : "当前步骤";
+        if (inspected.result.ok && status === "in_progress") {
+          ctx.ui.notify(`控制面状态一致，无需恢复。当前步骤是 ${stepId}；请审查当前产物后明确回复“批准执行”或提出修改意见。`, "info");
+        } else if (inspected.result.ok && status === "waiting_checkpoint") {
+          ctx.ui.notify("控制面状态一致，无需恢复。当前正在等待 checkpoint；请审查产物后明确回复“批准执行”或提出修改意见。", "info");
+        } else {
+          ctx.ui.notify("当前状态没有可安全自动执行的恢复计划；请运行 /devflow explain-state，并按其中的阻塞证据处理。", "error");
+        }
         return;
       }
-      if (trimmed === "control") {
-        await openProjectControlPanel(ctx);
+      const confirmed = await ctx.ui.confirm(
+        "确认修复 Devflow 控制面",
+        "将只根据已存在的文件同步 artifact registry；不会推进步骤、确认 checkpoint 或修改需求产物。继续吗？",
+      );
+      if (!confirmed) {
+        ctx.ui.notify("恢复未确认；状态保持不变。", "info");
         return;
       }
-      if (trimmed === "explain-state") {
-        const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
+      const result = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/repair_control_plane.rb", [
+        "--write",
+        "--confirm",
+        "--expected-revision",
+        String(revision),
+        "--json",
+      ]);
+      if (!result.ok) {
+        ctx.ui.notify(`控制面恢复失败：${result.stderr || result.stdout}`, "error");
+        return;
+      }
+      ctx.ui.notify("控制面 registry 已修复；未推进工作流。请审查当前步骤产物后明确回复“批准执行”或提出修改意见。", "info");
+      return;
+    }
+    if (trimmed === "abandon" || trimmed.startsWith("abandon ") || trimmed === "cancel" || trimmed.startsWith("cancel ")) {
+      const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
+      const snapshot = inspected.snapshot;
+      const revision = typeof snapshot?.revision === "number" ? snapshot.revision : undefined;
+      const feature = typeof snapshot?.current_feature === "string" ? snapshot.current_feature : undefined;
+      const status = typeof snapshot?.status === "string" ? snapshot.status : undefined;
+      if (!inspected.result.ok || revision === undefined || !feature) {
+        ctx.ui.notify(`无法读取当前需求状态：${inspected.result.stderr || inspected.result.stdout}`, "error");
+        return;
+      }
+      if (!status || ["completed", "cancelled", "failed"].includes(status)) {
+        ctx.ui.notify(`当前没有可弃用的进行中需求（status=${status || "unknown"}）。`, "info");
+        return;
+      }
+      const reason = trimmed.split(/\s+/, 2)[1]?.trim() || "用户主动终止当前需求";
+      const confirmed = await ctx.ui.confirm(
+        "确认弃用当前需求",
+        `需求：${feature}\n原因：${reason}\n\n将结束当前需求、释放项目占用并保留现有工件；不会把未完成步骤标记为完成。继续吗？`,
+      );
+      if (!confirmed) {
+        ctx.ui.notify("已取消弃用操作；状态保持不变。", "info");
+        return;
+      }
+      const result = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/advance_state.rb", [
+        "--write", "--json", "--cancel", "--cancel-reason", reason, "--expected-revision", String(revision),
+      ]);
+      if (!result.ok) {
+        ctx.ui.notify(`弃用当前需求失败：${result.stderr || result.stdout}`, "error");
+        return;
+      }
+      activeContract = undefined;
+      contractAgentCalls = 0;
+      setControlState(ctx, initialControlState());
+      ctx.ui.notify(`需求“${feature}”已弃用；现有工件已保留。现在可以创建新需求。`, "info");
+      return;
+    }
+    if (trimmed === "project-init") {
+      const initialization = await collectProjectInitialization(ctx);
+      if (!initialization) return;
+      pendingProjectInitialization = initialization;
+      if (initialization.mode === "apply") {
+        setControlState(ctx, executingState("执行已确认的项目初始化"));
+        activeWorkflowTurn = true;
+        await pi.sendUserMessage(projectInitializationDirective(initialization.summary));
+        return;
+      }
+      setControlState(ctx, planningState("project-init"));
+      await pi.sendUserMessage(
+        [
+          "<devflow-planner-directive>",
+          "用户已确认项目初始化的输入。你现在是 Planner，只允许只读分析和派发 project-scout / requirements-auditor / contract-auditor。",
+          "不得创建 .devflow/planning 文件、不得调用状态迁移、不得执行实现。",
+          "先输出：已知事实、待验证点、最少侦察任务和必须由用户决定的问题。没有证据时写 unknown。",
+          initialization.summary,
+          "</devflow-planner-directive>",
+        ].join("\n"),
+      );
+      return;
+    }
+    if (trimmed === "doctor") {
+      const report = await runDoctor(ctx);
+      ctx.ui.notify(formatDoctorReport(report).slice(0, 10000), report.ok ? "info" : "error");
+      return;
+    }
+    if (trimmed === "resume") {
+      const report = await runDoctor(ctx);
+      if (!report.ok) {
+        ctx.ui.notify(formatDoctorReport(report).slice(0, 10000), "error");
+        return;
+      }
+      const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
+      if (!inspected.result.ok || !inspected.snapshot) {
         ctx.ui.notify(
-          inspected.result.ok ? explainWorkflowSnapshot(inspected.snapshot) : `状态读取失败：${inspected.result.stderr || inspected.result.stdout}`,
-          inspected.result.ok ? "info" : "error",
+          `Devflow resume failed: ${inspected.result.stderr || inspected.result.stdout || "invalid inspector JSON"}`,
+          "error",
         );
-        setControlState(ctx, initialControlState());
         return;
       }
-      if (trimmed === "recover") {
-        const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
-        const plan = inspected.snapshot?.recovery_plan as Record<string, unknown> | undefined;
-        const revision = plan?.expected_revision;
-        if (!inspected.result.ok || !plan || plan.classification !== "safe_repairable" || typeof revision !== "number") {
-          const status = typeof inspected.snapshot?.status === "string" ? inspected.snapshot.status : "unknown";
-          const step = inspected.snapshot ? selectedWorkflowStep(inspected.snapshot) : null;
-          const stepId = typeof step?.id === "string" ? step.id : "当前步骤";
-          if (inspected.result.ok && status === "in_progress") {
-            ctx.ui.notify(`控制面状态一致，无需恢复。当前步骤是 ${stepId}；请审查当前产物后明确回复“批准执行”或提出修改意见。`, "info");
-          } else if (inspected.result.ok && status === "waiting_checkpoint") {
-            ctx.ui.notify("控制面状态一致，无需恢复。当前正在等待 checkpoint；请审查产物后明确回复“批准执行”或提出修改意见。", "info");
-          } else {
-            ctx.ui.notify("当前状态没有可安全自动执行的恢复计划；请运行 /devflow explain-state，并按其中的阻塞证据处理。", "error");
-          }
-          return;
-        }
-        const confirmed = await ctx.ui.confirm(
-          "确认修复 Devflow 控制面",
-          "将只根据已存在的文件同步 artifact registry；不会推进步骤、确认 checkpoint 或修改需求产物。继续吗？",
-        );
-        if (!confirmed) {
-          ctx.ui.notify("恢复未确认；状态保持不变。", "info");
-          return;
-        }
-        const result = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/repair_control_plane.rb", [
-          "--write",
-          "--confirm",
-          "--expected-revision",
-          String(revision),
-          "--json",
-        ]);
-        if (!result.ok) {
-          ctx.ui.notify(`控制面恢复失败：${result.stderr || result.stdout}`, "error");
-          return;
-        }
-        ctx.ui.notify("控制面 registry 已修复；未推进工作流。请审查当前步骤产物后明确回复“批准执行”或提出修改意见。", "info");
+      // Re-arm a durable rollover left by an interrupted runtime. An
+      // explicit resume is the user's authorization for a fresh session to
+      // adopt the same project's integrity-checked prepared handoff.
+      const rolloverResult = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/session_rollover.rb", ["inspect", "--json"]);
+      let rolloverState = parseJsonResult(rolloverResult);
+      const rollover = rolloverState?.rollover as Record<string, unknown> | undefined;
+      const currentSessionId = ctx.sessionManager.getSessionId();
+      if (
+        rolloverState &&
+        typeof rolloverState.revision === "number" &&
+        rollover?.status === "prepared" &&
+        typeof rollover.id === "string"
+      ) {
+        pendingRollover = {
+          snapshot: inspected.snapshot,
+          preparedRevision: rolloverState.revision,
+          rolloverId: rollover.id,
+        };
+        await enqueueControlledRolloverRequest(ctx.cwd, rollover.id, currentSessionId);
+        setControlState(ctx, waitingUserState("正在恢复受控会话交接"));
+        ctx.ui.notify("Devflow 已恢复待完成的受控会话交接；当前回合结束后将继续切换。", "info");
         return;
       }
-      if (trimmed === "abandon" || trimmed.startsWith("abandon ") || trimmed === "cancel" || trimmed.startsWith("cancel ")) {
-        const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
-        const snapshot = inspected.snapshot;
-        const revision = typeof snapshot?.revision === "number" ? snapshot.revision : undefined;
-        const feature = typeof snapshot?.current_feature === "string" ? snapshot.current_feature : undefined;
-        const status = typeof snapshot?.status === "string" ? snapshot.status : undefined;
-        if (!inspected.result.ok || revision === undefined || !feature) {
-          ctx.ui.notify(`无法读取当前需求状态：${inspected.result.stderr || inspected.result.stdout}`, "error");
-          return;
-        }
-        if (!status || ["completed", "cancelled", "failed"].includes(status)) {
-          ctx.ui.notify(`当前没有可弃用的进行中需求（status=${status || "unknown"}）。`, "info");
-          return;
-        }
-        const reason = trimmed.split(/\s+/, 2)[1]?.trim() || "用户主动终止当前需求";
-        const confirmed = await ctx.ui.confirm(
-          "确认弃用当前需求",
-          `需求：${feature}\n原因：${reason}\n\n将结束当前需求、释放项目占用并保留现有工件；不会把未完成步骤标记为完成。继续吗？`,
-        );
-        if (!confirmed) {
-          ctx.ui.notify("已取消弃用操作；状态保持不变。", "info");
-          return;
-        }
-        const result = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/advance_state.rb", [
-          "--write", "--json", "--cancel", "--cancel-reason", reason, "--expected-revision", String(revision),
-        ]);
-        if (!result.ok) {
-          ctx.ui.notify(`弃用当前需求失败：${result.stderr || result.stdout}`, "error");
-          return;
-        }
-        activeContract = undefined;
-        contractAgentCalls = 0;
-        setControlState(ctx, initialControlState());
-        ctx.ui.notify(`需求“${feature}”已弃用；现有工件已保留。现在可以创建新需求。`, "info");
+      await resumeInspectedWorkflow(ctx, inspected.snapshot, { doctorAlreadyPassed: true });
+      return;
+    }
+    if (trimmed.startsWith("start ")) {
+      const [feature, requestedPhase] = trimmed.slice(6).split("|", 2).map(value => value.trim());
+      if (!feature) {
+        ctx.ui.notify("Usage: /devflow start <feature>|<phase>", "error");
         return;
       }
-      if (trimmed === "project-init") {
-        const initialization = await collectProjectInitialization(ctx);
-        if (!initialization) return;
-        pendingProjectInitialization = initialization;
-        if (initialization.mode === "apply") {
-          setControlState(ctx, executingState("执行已确认的项目初始化"));
-          activeWorkflowTurn = true;
-          await pi.sendUserMessage(projectInitializationDirective(initialization.summary));
-          return;
-        }
-        setControlState(ctx, planningState("project-init"));
-        await pi.sendUserMessage(
-          [
-            "<devflow-planner-directive>",
-            "用户已确认项目初始化的输入。你现在是 Planner，只允许只读分析和派发 project-scout / requirements-auditor / contract-auditor。",
-            "不得创建 .devflow/planning 文件、不得调用状态迁移、不得执行实现。",
-            "先输出：已知事实、待验证点、最少侦察任务和必须由用户决定的问题。没有证据时写 unknown。",
-            initialization.summary,
-            "</devflow-planner-directive>",
-          ].join("\n"),
+      const phase = requestedPhase || defaultPhaseId(feature);
+      if (!validPhaseId(phase)) {
+        ctx.ui.notify("Phase ID 必须是 1-64 位字母、数字、下划线或连字符，且不得包含路径分隔符。", "error");
+        return;
+      }
+      const report = await runDoctor(ctx);
+      if (!report.ok) {
+        ctx.ui.notify(formatDoctorReport(report).slice(0, 10000), "error");
+        return;
+      }
+      const existing = await inspectWorkflow(ctx.cwd);
+      const existingFeature = existing.snapshot?.current_feature;
+      const previousWorkflowComplete = ["workflow_complete", "workflow_cancelled"].includes(existing.snapshot?.action as string);
+      if (
+        !previousWorkflowComplete &&
+        typeof existingFeature === "string" &&
+        existingFeature !== feature
+      ) {
+        ctx.ui.notify(
+          `当前仍有未完成需求：${existingFeature}。请在对话中继续处理当前步骤，完成后再创建新需求：${feature}。`,
+          "error",
         );
         return;
       }
-      if (trimmed === "doctor") {
-        const report = await runDoctor(ctx);
-        ctx.ui.notify(formatDoctorReport(report).slice(0, 10000), report.ok ? "info" : "error");
+      // This dry-run happens before init_workflow.rb, so a rejected feature
+      // can never overwrite generated workflow files belonging to an active
+      // owner or a legacy phase directory that has no trustworthy owner.
+      const ownership = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/phase_ownership.rb", [
+        "claim",
+        "--feature",
+        feature,
+        "--phase",
+        phase,
+        "--flow",
+        "feature-development",
+        "--json",
+      ]);
+      if (!controlPlaneSucceeded(ownership)) {
+        ctx.ui.notify((ownership.stderr || ownership.stdout).slice(0, 6000), "error");
         return;
       }
-      if (trimmed === "resume") {
-        const report = await runDoctor(ctx);
-        if (!report.ok) {
-          ctx.ui.notify(formatDoctorReport(report).slice(0, 10000), "error");
-          return;
-        }
-        const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
-        if (!inspected.result.ok || !inspected.snapshot) {
-          ctx.ui.notify(
-            `Devflow resume failed: ${inspected.result.stderr || inspected.result.stdout || "invalid inspector JSON"}`,
-            "error",
-          );
-          return;
-        }
-        // Re-arm a durable rollover left by an interrupted runtime. An
-        // explicit resume is the user's authorization for a fresh session to
-        // adopt the same project's integrity-checked prepared handoff.
-        const rolloverResult = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/session_rollover.rb", ["inspect", "--json"]);
-        const rolloverState = parseJsonResult(rolloverResult);
-        const rollover = rolloverState?.rollover as Record<string, unknown> | undefined;
-        const currentSessionId = ctx.sessionManager.getSessionId();
-        if (
-          rolloverState &&
-          typeof rolloverState.revision === "number" &&
-          rollover?.status === "prepared" &&
-          typeof rollover.id === "string"
-        ) {
-          pendingRollover = {
-            snapshot: inspected.snapshot,
-            preparedRevision: rolloverState.revision,
-            rolloverId: rollover.id,
-          };
-          await enqueueControlledRolloverRequest(ctx.cwd, rollover.id, currentSessionId);
-          setControlState(ctx, waitingUserState("正在恢复受控会话交接"));
-          ctx.ui.notify("Devflow 已恢复待完成的受控会话交接；当前回合结束后将继续切换。", "info");
-          return;
-        }
-        await resumeInspectedWorkflow(ctx, inspected.snapshot, { doctorAlreadyPassed: true });
+      const workflow = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/init_workflow.rb", [
+        "--write",
+        "--json",
+      ]);
+      if (!controlPlaneSucceeded(workflow)) {
+        ctx.ui.notify(workflow.stderr || workflow.stdout, "error");
         return;
       }
-      if (trimmed.startsWith("start ")) {
-        const [feature, requestedPhase] = trimmed.slice(6).split("|", 2).map(value => value.trim());
-        if (!feature) {
-          ctx.ui.notify("Usage: /devflow start <feature>|<phase>", "error");
-          return;
-        }
-        const phase = requestedPhase || defaultPhaseId(feature);
-        if (!validPhaseId(phase)) {
-          ctx.ui.notify("Phase ID 必须是 1-64 位字母、数字、下划线或连字符，且不得包含路径分隔符。", "error");
-          return;
-        }
-        const report = await runDoctor(ctx);
-        if (!report.ok) {
-          ctx.ui.notify(formatDoctorReport(report).slice(0, 10000), "error");
-          return;
-        }
-        const existing = await inspectWorkflow(ctx.cwd);
-        const existingFeature = existing.snapshot?.current_feature;
-        const previousWorkflowComplete = ["workflow_complete", "workflow_cancelled"].includes(existing.snapshot?.action as string);
-        if (
-          !previousWorkflowComplete &&
-          typeof existingFeature === "string" &&
-          existingFeature !== feature
-        ) {
-          ctx.ui.notify(
-            `当前仍有未完成需求：${existingFeature}。请在对话中继续处理当前步骤，完成后再创建新需求：${feature}。`,
-            "error",
-          );
-          return;
-        }
-        // This dry-run happens before init_workflow.rb, so a rejected feature
-        // can never overwrite generated workflow files belonging to an active
-        // owner or a legacy phase directory that has no trustworthy owner.
-        const ownership = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/phase_ownership.rb", [
-          "claim",
-          "--feature",
-          feature,
-          "--phase",
-          phase,
-          "--flow",
-          "feature-development",
-          "--json",
-        ]);
-        if (!controlPlaneSucceeded(ownership)) {
-          ctx.ui.notify((ownership.stderr || ownership.stdout).slice(0, 6000), "error");
-          return;
-        }
-        const workflow = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/init_workflow.rb", [
-          "--write",
-          "--json",
-        ]);
-        if (!controlPlaneSucceeded(workflow)) {
-          ctx.ui.notify(workflow.stderr || workflow.stdout, "error");
-          return;
-        }
-        const state = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/init_state.rb", [
-          "--feature",
-          feature,
-          "--phase",
-          phase,
-          "--flow",
-          "feature-development",
-          "--write",
-          "--json",
-          ...(previousWorkflowComplete ? ["--force"] : []),
-        ]);
-        if (!controlPlaneSucceeded(state)) {
-          ctx.ui.notify((state.stderr || state.stdout).slice(0, 6000), "error");
-          return;
-        }
-        const artifacts = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/sync_artifacts.rb", [
-          "--write",
-          "--json",
-        ]);
-        if (!controlPlaneSucceeded(artifacts)) {
-          ctx.ui.notify((artifacts.stderr || artifacts.stdout).slice(0, 6000), "error");
-          return;
-        }
-        const inspected = await inspectWorkflow(ctx.cwd);
-        if (!inspected.result.ok || !inspected.snapshot) {
-          ctx.ui.notify(
-            `Devflow initialized but inspector failed: ${inspected.result.stderr || inspected.result.stdout || "invalid JSON"}`,
-            "error",
-          );
-          return;
-        }
-        setControlState(ctx, planningState("requirement-draft"));
-        await pi.sendUserMessage(
-          [
-            "<devflow-requirement-draft-directive>",
-            `Devflow 已创建 Feature ${feature}。当前为安全的需求梳理阶段：允许澄清和只读证据收集，不得写入项目或迁移状态。`,
-            "请先基于功能名说明你需要的最少业务背景，并邀请用户直接补充目标、使用者、约束和验收结果。收到用户的下一段需求描述后，运行时会将其原文注入 requirement-triage 并启动该步骤。",
-            "不要让用户输入命令；也不要把普通需求文本当成批准或 checkpoint 确认。",
-            "</devflow-requirement-draft-directive>",
-          ].join("\n"),
+      const state = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/init_state.rb", [
+        "--feature",
+        feature,
+        "--phase",
+        phase,
+        "--flow",
+        "feature-development",
+        "--write",
+        "--json",
+        ...(previousWorkflowComplete ? ["--force"] : []),
+      ]);
+      if (!controlPlaneSucceeded(state)) {
+        ctx.ui.notify((state.stderr || state.stdout).slice(0, 6000), "error");
+        return;
+      }
+      const artifacts = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/sync_artifacts.rb", [
+        "--write",
+        "--json",
+      ]);
+      if (!controlPlaneSucceeded(artifacts)) {
+        ctx.ui.notify((artifacts.stderr || artifacts.stdout).slice(0, 6000), "error");
+        return;
+      }
+      const inspected = await inspectWorkflow(ctx.cwd);
+      if (!inspected.result.ok || !inspected.snapshot) {
+        ctx.ui.notify(
+          `Devflow initialized but inspector failed: ${inspected.result.stderr || inspected.result.stdout || "invalid JSON"}`,
+          "error",
         );
         return;
       }
-      ctx.ui.notify(
-        "Usage: /devflow doctor | status | control | explain-state | recover | abandon [reason] | project-init | start <feature>|<phase> | resume",
-        "warning",
+      setControlState(ctx, planningState("requirement-draft"));
+      await pi.sendUserMessage(
+        [
+          "<devflow-requirement-draft-directive>",
+          `Devflow 已创建 Feature ${feature}。当前为安全的需求梳理阶段：允许澄清和只读证据收集，不得写入项目或迁移状态。`,
+          "请先基于功能名说明你需要的最少业务背景，并邀请用户直接补充目标、使用者、约束和验收结果。收到用户的下一段需求描述后，运行时会将其原文注入 requirement-triage 并启动该步骤。",
+          "不要让用户输入命令；也不要把普通需求文本当成批准或 checkpoint 确认。",
+          "</devflow-requirement-draft-directive>",
+        ].join("\n"),
       );
-    },
+      return;
+    }
+    ctx.ui.notify(
+      "用法：/devflow（查看状态） | /devflow next（下一步） | /devflow fix（诊断修复） | /devflow cancel [原因] | /devflow control | /devflow start <需求名> | /devflow project-init | /devflow doctor\n兼容旧命令：status [--json] | explain-state | recover | abandon | resume",
+      "warning",
+    );
+  };
+  devflowCommandRef = devflowCommand;
+
+  pi.registerCommand("devflow", {
+    description: "Devflow runtime: inspect, initialize, plan, run one step, or explicitly advance the controlled delivery pipeline",
+    handler: devflowCommand,
   });
 }