@guanlin4924/devflow-pi 0.1.25 → 0.1.26

package/README.md

@@ -11,7 +11,7 @@ Devflow Pi 是一个面向项目研发交付的独立 OMP 产品入口，内置
 安装与启动：
 
 ```bash
-npm install -g @guanlin4924/devflow-pi@0.1.23
+npm install -g @guanlin4924/devflow-pi@0.1.26
 cd /path/to/your-project
 devflow-pi init
 devflow-pi doctor
@@ -115,6 +115,12 @@ bash .skills/install.sh --apply --force-config
 
 `/devflow start` 会先进入安全的需求梳理：可澄清并只读检查，不写入项目。用户随后直接补充需求，原文会被带入入口分诊并启动当前步骤。每个步骤结束后，系统展示产物和证据；用户明确回复“批准执行”才会推进并运行下一步，回复修改意见或“拒绝执行”则保持原步骤。普通需求描述绝不会自动确认 checkpoint。`/devflow explain-state` 发现控制面和制品 registry 漂移时会给出只读恢复计划；用户审查后可用 `/devflow recover` 确认仅修复可由文件系统证明的 registry 字段，它绝不推进步骤或自动通过 checkpoint。恢复已有流程使用 `/devflow resume`，它同样只恢复状态而不自动执行。
 
+### 窗口操作指引与干净会话
+
+Devflow 会在输入框上方显示与当前状态对应的“Devflow 操作指引”：空闲时给出初始化、创建功能和状态查看入口；需求梳理时提示直接补充需求；节点审查时提示回复“批准执行”或直接描述修改项；阻塞时只展示解释状态和安全恢复入口。
+
+正式节点经用户批准后，Devflow 会把已校验的状态和产物引用固化为内容校验的 handoff，再自动创建干净 Session 执行下一节点。交接期间工作流冻结；只有新 Session 成功认领并消费同一份 handoff 后才解除冻结。Devflow 不使用 OMP 的模型摘要 handoff，因此 `.planning/STATE.md` 仍是唯一流程事实源。
+
 ### 需求验收测试与 TDD 证据链
 
 新建功能在 `integration-verify` 后会先生成独立的 `TC-*` 验收测试设计，再生成变更清单：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "type": "module",
   "description": "Devflow 专项研发 Pi，基于固定版本 OMP Runtime 组装研发状态机、代码智能、设计、实现与质量门禁。",
   "license": "UNLICENSED",

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

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
-import { mkdir, writeFile } from "node:fs/promises";
+import { mkdir, rename, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
@@ -29,6 +29,7 @@ type ActiveExecutionContract = {
   step: string;
   stateRevision?: number;
   graphRevision?: number;
+  workflowFingerprint?: string;
   allowedPaths: string[];
   allowedAgents: string[];
   allowedTools: string[];
@@ -41,6 +42,30 @@ type ActiveExecutionContract = {
   onUnknown: "block_and_escalate";
 };
 
+function contractFromRecord(record: Record<string, unknown>): ActiveExecutionContract | null {
+  const strings = (key: string): string[] =>
+    Array.isArray(record[key]) ? record[key].filter((item): item is string => typeof item === "string") : [];
+  const contract: ActiveExecutionContract = {
+    contractId: String(record.contract_id ?? ""),
+    feature: String(record.feature ?? ""),
+    step: String(record.step ?? ""),
+    stateRevision: typeof record.state_revision === "number" ? record.state_revision : undefined,
+    graphRevision: typeof record.graph_revision === "number" ? record.graph_revision : undefined,
+    workflowFingerprint: typeof record.workflow_fingerprint === "string" ? record.workflow_fingerprint : undefined,
+    allowedPaths: strings("allowed_paths"),
+    allowedAgents: strings("allowed_agents"),
+    allowedTools: strings("allowed_tools"),
+    checkerIds: strings("checker_ids"),
+    toolBudget: typeof record.tool_budget === "number" ? record.tool_budget : 0,
+    frozenHash: String(record.frozen_hash ?? ""),
+    acceptance: strings("acceptance"),
+    allowedGraphDelta: strings("allowed_graph_delta"),
+    onUnknown: "block_and_escalate",
+  };
+  if (!contract.contractId || !contract.frozenHash) return null;
+  return contract;
+}
+
 const READ_ONLY_TOOLS = new Set([
   "read",
   "grep",
@@ -56,7 +81,6 @@ const READ_ONLY_TOOLS = new Set([
   "devflow_usage_stats",
   "usage_stats",
 ]);
-
 const REQUIREMENT_DRAFT_TOOLS = new Set([...READ_ONLY_TOOLS, "ask"]);
 // A Todo update changes only the client-visible task list, never the project
 // or Devflow state. Permit it during planning so a harmless checklist cannot
@@ -414,6 +438,7 @@ const REQUIRED_SCRIPTS = [
   "workflow-orchestrator/scripts/phase_ownership.rb",
   "workflow-orchestrator/scripts/inspect_state.rb",
   "workflow-orchestrator/scripts/advance_state.rb",
+  "workflow-orchestrator/scripts/session_rollover.rb",
   "workflow-orchestrator/scripts/sync_artifacts.rb",
   "workflow-orchestrator/scripts/requirement_graph.rb",
   "workflow-orchestrator/scripts/acceptance_test_suite.rb",
@@ -840,9 +865,35 @@ export default function devflowCore(pi: ExtensionAPI) {
   let activeContract: ActiveExecutionContract | undefined;
   let contractAgentCalls = 0;
 
-  function setControlState(ctx: { ui: { setStatus(key: string, text: string | undefined): void } }, state: SessionControlState) {
+  function controlGuide(state: SessionControlState): string[] {
+    const title = "Devflow 操作指引";
+    if (state.intent === "project-init" && state.phase === "planning") {
+      return [title, "初始化范围待确认：按界面完成选择；批准写入请回复“批准执行”。"];
+    }
+    if (state.intent === "requirement-draft" && state.phase === "planning") {
+      return [title, "需求梳理：直接补充需求正文、目标、边界和验收结果；此时不会推进实现。"];
+    }
+    if (state.phase === "waiting-user" || state.phase === "awaiting-approval") {
+      return [title, "当前节点等待审查：批准请回复“批准执行”；需修改请直接描述修改项。", "状态说明：/devflow explain-state"];
+    }
+    if (state.phase === "executing") {
+      return [title, `正在处理：${state.label}`, "请等待当前步骤输出；完成后会提示你审查。"];
+    }
+    if (state.phase === "blocked") {
+      return [title, "当前步骤被阻塞：使用 /devflow explain-state 查看证据与可恢复路径。", "仅在系统给出安全恢复计划后使用 /devflow recover。"];
+    }
+    return [title, "初始化项目：/devflow project-init", "创建功能：/devflow start <功能名>    查看状态：/devflow explain-state"];
+  }
+
+  function setControlState(ctx: {
+    ui: {
+      setStatus(key: string, text: string | undefined): void;
+      setWidget?(key: string, content: string[] | undefined, options?: { placement?: "aboveEditor" | "belowEditor" }): void;
+    };
+  }, state: SessionControlState) {
     controlState = state;
     ctx.ui.setStatus("devflow-control", statusText(state));
+    ctx.ui.setWidget?.("devflow-operation-guide", controlGuide(state), { placement: "aboveEditor" });
   }
 
   function normalizeContractSegment(value: string, label: string): string {
@@ -862,11 +913,57 @@ export default function devflowCore(pi: ExtensionAPI) {
     const stateRevision = typeof state?.revision === "number" ? state.revision : undefined;
     const graphResult = parseJsonResult(await runRuby(cwd, "workflow-orchestrator/scripts/requirement_graph.rb", ["inspect", "--feature", contract.feature, "--json"]));
     const graph = graphResult?.graph;
-    const graphRevision = graph && typeof graph === "object" && typeof (graph as Record<string, unknown>).revision === "number"
-      ? (graph as Record<string, number>).revision : undefined;
+    const graphRevision =
+      graph && typeof graph === "object" && typeof (graph as Record<string, unknown>).revision === "number"
+        ? (graph as Record<string, number>).revision
+        : undefined;
     return stateRevision === contract.stateRevision && graphRevision === contract.graphRevision;
   }
 
+  async function restoreActiveContract(cwd: string): Promise<ActiveExecutionContract | undefined> {
+    try {
+      const state = parseJsonResult(await runRuby(cwd, "workflow-orchestrator/scripts/inspect_state.rb", ["--json"]));
+      const feature = typeof state?.current_feature === "string" ? state.current_feature : undefined;
+      const rawStep = state?.current_step;
+      const step =
+        typeof rawStep === "string"
+          ? rawStep
+          : rawStep && typeof rawStep === "object" && typeof (rawStep as { id?: unknown }).id === "string"
+            ? (rawStep as { id: string }).id
+            : undefined;
+      if (!feature || !step) return undefined;
+      const contractsDir = path.join(cwd, ".planning", "contracts", feature);
+      if (!existsSync(contractsDir)) return undefined;
+      const candidates = readdirSync(contractsDir)
+        .filter(name => name.startsWith("EC-") && name.endsWith(".json"))
+        .map(name => path.join(contractsDir, name))
+        .sort((a, b) => lstatSync(b).mtimeMs - lstatSync(a).mtimeMs);
+      for (const candidate of candidates) {
+        let parsed: Record<string, unknown>;
+        try {
+          parsed = JSON.parse(readFileSync(candidate, "utf8")) as Record<string, unknown>;
+        } catch {
+          continue;
+        }
+        const contract = contractFromRecord(parsed);
+        if (!contract || contract.feature !== feature || contract.step !== step) continue;
+        const inspected = parseJsonResult(await runRuby(cwd, "workflow-orchestrator/scripts/execution_contract.rb", ["inspect", "--feature", feature, "--step", step, "--json"]));
+        const currentRaw = inspected?.contract;
+        const current = currentRaw && typeof currentRaw === "object" ? contractFromRecord(currentRaw as Record<string, unknown>) : null;
+        if (!current) continue;
+        if (current.contractId !== contract.contractId) continue;
+        if (current.frozenHash !== contract.frozenHash) continue;
+        if (current.workflowFingerprint !== contract.workflowFingerprint) continue;
+        if (!(await contractIsFresh(cwd, contract))) continue;
+        contract.contractPath = candidate;
+        return contract;
+      }
+    } catch {
+      // 恢复失败不阻塞会话启动；对应步骤执行时会提示重新合成合同。
+    }
+    return undefined;
+  }
+
   async function collectProjectInitialization(ctx: {
     cwd: string;
     ui: {
@@ -1190,6 +1287,32 @@ export default function devflowCore(pi: ExtensionAPI) {
 
   let activeWorkflowTurn = false;
   let pendingProjectInitialization: ProjectInitializationRequest | undefined;
+  let pendingRollover: { snapshot: Record<string, unknown>; preparedRevision: number; rolloverId: string } | undefined;
+
+  async function enqueueControlledRolloverRequest(cwd: string, rolloverId: string, sourceSessionId: string) {
+    const requestPath = path.join(cwd, ".planning", "rollover-request.json");
+    const temporary = `${requestPath}.${randomUUID()}.tmp`;
+    await writeFile(temporary, JSON.stringify({ schema_version: 1, rollover_id: rolloverId, source_session_id: sourceSessionId }) + "\n", "utf8");
+    await rename(temporary, requestPath);
+  }
+
+  async function requestControlledRollover(ctx: { cwd: string; sessionManager: { getSessionId(): string } }, snapshot: Record<string, unknown>) {
+    const revision = typeof snapshot.revision === "number" ? snapshot.revision : undefined;
+    if (revision === undefined) throw new Error("Cannot prepare session rollover without a STATE revision.");
+    const prepared = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/session_rollover.rb", [
+      "prepare", "--write", "--json", "--expected-revision", String(revision),
+      "--source-session-id", ctx.sessionManager.getSessionId(), "--reason", "workflow_step_boundary",
+    ]);
+    const payload = parseJsonResult(prepared);
+    if (!prepared.ok || !payload || typeof payload.revision !== "number") {
+      throw new Error(prepared.stderr || prepared.stdout || "rollover prepare failed");
+    }
+    const rollover = payload.rollover as Record<string, unknown> | undefined;
+    const rolloverId = typeof rollover?.id === "string" ? rollover.id : undefined;
+    if (!rolloverId) throw new Error("rollover prepare returned no rollover id");
+    await enqueueControlledRolloverRequest(ctx.cwd, rolloverId, ctx.sessionManager.getSessionId());
+    pendingRollover = { snapshot, preparedRevision: payload.revision, rolloverId };
+  }
 
   async function triggerWorkflow(snapshot: Record<string, unknown>, source: "start" | "approval", requirementDraft?: string) {
     activeWorkflowTurn = true;
@@ -1211,7 +1334,71 @@ export default function devflowCore(pi: ExtensionAPI) {
       return;
     }
     ctx.ui.setStatus("devflow", "Devflow ready");
+    const restored = await restoreActiveContract(ctx.cwd);
+    if (restored) {
+      activeContract = restored;
+      contractAgentCalls = 0;
+      ctx.ui.notify(`已恢复执行合同 ${restored.contractId}（${restored.feature}/${restored.step}）；步骤推进后自动失效。`, "info");
+    }
     setControlState(ctx, initialControlState());
+    // Recovery never searches the handoff directory. STATE.rollover is the
+    // 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);
+    const rollover = rolloverState?.rollover as Record<string, unknown> | undefined;
+    const currentSessionId = ctx.sessionManager.getSessionId();
+    if (rolloverState && typeof rolloverState.revision === "number" && rollover?.status === "prepared" && rollover.source_session_id === currentSessionId && typeof rollover.id === "string") {
+      const workflow = await inspectWorkflow(ctx.cwd);
+      if (workflow.result.ok && workflow.snapshot) {
+        pendingRollover = { snapshot: workflow.snapshot, preparedRevision: rolloverState.revision, rolloverId: rollover.id };
+        await enqueueControlledRolloverRequest(ctx.cwd, rollover.id, currentSessionId);
+        ctx.ui.notify("已恢复待完成的受控会话交接；当前回合结束后将继续切换。", "info");
+      }
+    } else if (rolloverState && typeof rolloverState.revision === "number" && rollover?.status === "claimed" && rollover.target_session_id === currentSessionId) {
+      const consumed = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/session_rollover.rb", [
+        "consume", "--write", "--json", "--expected-revision", String(rolloverState.revision), "--target-session-id", currentSessionId,
+      ]);
+      const after = await inspectWorkflow(ctx.cwd);
+      if (consumed.ok && after.result.ok && after.snapshot) {
+        setControlState(ctx, executingState("恢复已认领的干净会话"));
+        await triggerWorkflow(after.snapshot, "approval");
+      } else if (!consumed.ok) {
+        ctx.ui.notify(`已认领的会话交接无法恢复；工作流保持冻结：${consumed.stderr || consumed.stdout}`, "error");
+      }
+    }
+  });
+
+  pi.on("session_before_switch", async (event) => {
+    // A controlled rollover must always create a fresh session. Other session
+    // navigation remains OMP-owned and never consumes a Devflow handoff.
+    if (pendingRollover && event.reason !== "new") return { cancel: true };
+  });
+
+  pi.on("session_switch", async (event, ctx) => {
+    if (!pendingRollover || event.reason !== "new") return;
+    const pending = pendingRollover;
+    const targetSessionId = ctx.sessionManager.getSessionId();
+    const claimed = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/session_rollover.rb", [
+      "claim", "--write", "--json", "--expected-revision", String(pending.preparedRevision), "--target-session-id", targetSessionId,
+    ]);
+    const claimedPayload = parseJsonResult(claimed);
+    if (!claimed.ok || !claimedPayload || typeof claimedPayload.revision !== "number") {
+      ctx.ui.notify(`Devflow 会话交接认领失败；工作流保持冻结：${claimed.stderr || claimed.stdout}`, "error");
+      return;
+    }
+    const consumed = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/session_rollover.rb", [
+      "consume", "--write", "--json", "--expected-revision", String(claimedPayload.revision), "--target-session-id", targetSessionId,
+    ]);
+    if (!consumed.ok) {
+      ctx.ui.notify(`Devflow 会话交接消费失败；工作流保持冻结：${consumed.stderr || consumed.stdout}`, "error");
+      return;
+    }
+    pendingRollover = undefined;
+    activeContract = undefined;
+    contractAgentCalls = 0;
+    setControlState(ctx, executingState("在干净会话中执行下一工作流步骤"));
+    await triggerWorkflow(pending.snapshot, "approval");
   });
 
   pi.on("before_agent_start", async event => ({
@@ -1277,7 +1464,10 @@ export default function devflowCore(pi: ExtensionAPI) {
           return { handled: true };
         }
         const result = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/advance_state.rb", [
-          "--write", "--json", "--expected-revision", String(revision),
+          "--write",
+          "--json",
+          "--expected-revision",
+          String(revision),
           ...(checkpoint ? ["--confirm-checkpoint"] : ["--complete-step", stepId!]),
         ]);
         if (!result.ok) {
@@ -1286,13 +1476,21 @@ export default function devflowCore(pi: ExtensionAPI) {
           return { handled: true };
         }
         const after = await inspectWorkflow(ctx.cwd);
+        activeContract = undefined;
+        contractAgentCalls = 0;
         if (!after.result.ok || !after.snapshot || after.snapshot.action === "workflow_complete") {
           setControlState(ctx, initialControlState());
           ctx.ui.notify(after.snapshot?.action === "workflow_complete" ? "工作流已完成。" : "已推进，但读取下一步骤失败。", "info");
           return { handled: true };
         }
-        setControlState(ctx, executingState("执行已批准的下一工作流步骤"));
-        await triggerWorkflow(after.snapshot, "approval");
+        setControlState(ctx, waitingUserState("正在准备干净会话以执行下一工作流步骤"));
+        try {
+          await requestControlledRollover(ctx, after.snapshot);
+          ctx.ui.notify("当前节点的证据已固定；本回合结束后将自动切换到干净会话并继续下一节点。", "info");
+        } catch (error) {
+          setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "会话轮换准备失败" });
+          ctx.ui.notify(`未开始下一节点：会话轮换准备失败：${String(error)}`, "error");
+        }
         return { handled: true };
       }
     }
@@ -1538,9 +1736,11 @@ export default function devflowCore(pi: ExtensionAPI) {
   });
 
   pi.registerTool({
+
     name: "devflow_requirement_graph",
     label: "Devflow Requirement Graph",
-    description: "Submit bounded requirement-graph candidates or inspect/validate the Core-owned canonical graph.",
+    description: "Submit bounded requirement-graph candidates or inspect and validate the Core-owned canonical graph.",
+
     parameters: z.object({
       action: z.enum(["propose", "inspect", "validate", "context", "confirm"]),
       feature: z.string().min(1),
@@ -1552,7 +1752,7 @@ export default function devflowCore(pi: ExtensionAPI) {
       read: z.boolean().optional(),
       delta: z.object({
         op: z.enum(["add", "link", "update"]),
-        kind: z.enum(["source", "code", "term", "object", "behavior", "requirement", "rule", "boundary", "slice", "risk", "decision", "acceptance", "api", "workload_shape", "workload_constraint", "test_case"]).optional(),
+        kind: z.enum(["source", "code", "term", "object", "behavior", "requirement", "rule", "boundary", "slice", "risk", "decision", "acceptance", "api", "workload_shape", "workload_constraint", "metric", "read_model", "test_case"]).optional(),
         id: z.string().min(1).optional(),
         data: z.record(z.string(), z.unknown()).optional(),
         from: z.string().min(1).optional(),
@@ -1596,23 +1796,49 @@ export default function devflowCore(pi: ExtensionAPI) {
         const node = Array.isArray(inspected?.graph?.nodes)
           ? inspected.graph.nodes.find((candidate: unknown) => typeof candidate === "object" && candidate !== null && (candidate as { id?: unknown }).id === params.nodeId) as { kind?: unknown; data?: unknown } | undefined
           : undefined;
-        const architectureDecision = node?.kind === "decision" && typeof node?.data === "object" && node.data !== null && (node.data as { decision_type?: unknown }).decision_type === "architecture_option_comparison";
-        const architectureRisk = node?.kind === "risk" && typeof node?.data === "object" && node.data !== null && (node.data as { risk_type?: unknown }).risk_type === "architecture_option_risk";
-        if (node?.kind === "workload_shape" || node?.kind === "workload_constraint" || architectureDecision || architectureRisk) {
+        const architectureDecision =
+          node?.kind === "decision" && typeof node?.data === "object" && node.data !== null && (node.data as { decision_type?: unknown }).decision_type === "architecture_option_comparison";
+        const architectureRisk =
+          node?.kind === "risk" && typeof node?.data === "object" && node.data !== null && (node.data as { risk_type?: unknown }).risk_type === "architecture_option_risk";
+        const metricNode = node?.kind === "metric";
+        const readModelNode = node?.kind === "read_model";
+        if (node?.kind === "workload_shape" || node?.kind === "workload_constraint" || metricNode || readModelNode || architectureDecision || architectureRisk) {
           const preview = JSON.stringify(node.data ?? {}, null, 2);
-          const decisionDialog = architectureDecision;
-          const riskDialog = architectureRisk;
           const confirmed = await ctx.ui.confirm(
-            decisionDialog ? "确认架构方案取舍" : riskDialog ? "确认架构风险处理" : "确认工作负载事实或缺口",
+            architectureDecision
+              ? "确认架构方案取舍"
+              : architectureRisk
+                ? "确认架构风险处理"
+                : metricNode
+                  ? "确认业务指标定义"
+                  : readModelNode
+                    ? "确认读模型定义"
+                    : "确认工作负载事实或缺口",
             [
               `Feature：${params.feature}`,
               `节点：${params.nodeId}`,
-              `类型：${decisionDialog ? "架构方案比较" : riskDialog ? "架构风险处理" : node.kind === "workload_shape" ? "工作负载形态" : "工作负载约束"}`,
-              decisionDialog
+              `类型：${
+                architectureDecision
+                  ? "架构方案比较"
+                  : architectureRisk
+                    ? "架构风险处理"
+                    : metricNode
+                      ? "业务指标"
+                      : readModelNode
+                        ? "读模型"
+                        : node?.kind === "workload_shape"
+                          ? "工作负载形态"
+                          : "工作负载约束"
+              }`,
+              architectureDecision
                 ? "确认的含义是：你已核对候选方案、证据与取舍，并接受其中 recommendation_option_id 作为本次架构选择。"
-                : riskDialog
-                  ? "确认的含义是：你已核对失败模式、影响、处理方式、负责人和复核条件；它不代表生产风险从此消失。"
-                : "确认的含义仅是：该事实或缺口、来源与责任归属已被你核对；它不代表容量已经满足，也不会替你选择实现方案。",
+                : architectureRisk
+                  ? "确认的含义是：你已核对风险陈述、缓解策略与剩余风险，并接受该风险登记结果。"
+                  : metricNode
+                    ? "确认的含义是：你已核对该业务指标的口径、粒度、包含/排除规则与归属；它代表可追踪的业务事实，不只是文本标签。"
+                    : readModelNode
+                      ? "确认的含义是：你已核对该读模型的投影语义、消费边界与查询责任；它代表 Core 认可的读侧契约。"
+                      : "确认的含义仅是：该事实或缺口、来源与责任归属已被你核对；它不代表容量已经满足，也不会替你选择实现方案。",
               "待确认内容：",
               preview.length > 8_000 ? `${preview.slice(0, 8_000)}\n…（内容过长，已截断）` : preview,
             ].join("\n\n"),
@@ -2029,19 +2255,12 @@ export default function devflowCore(pi: ExtensionAPI) {
       const payload = parseJsonResult(inspected);
       const raw = payload?.contract;
       if (!controlPlaneSucceeded(inspected) || !raw || typeof raw !== "object") return renderResult(inspected, { action: input.action });
-      const record = raw as Record<string, unknown>;
-      const strings = (key: string): string[] => Array.isArray(record[key]) ? record[key].filter((item): item is string => typeof item === "string") : [];
-      const contract: ActiveExecutionContract = {
-        contractId: String(record.contract_id ?? ""), feature: String(record.feature ?? ""), step: String(record.step ?? ""),
-        stateRevision: typeof record.state_revision === "number" ? record.state_revision : undefined,
-        graphRevision: typeof record.graph_revision === "number" ? record.graph_revision : undefined,
-        allowedPaths: strings("allowed_paths"), allowedAgents: strings("allowed_agents"), allowedTools: strings("allowed_tools"), checkerIds: strings("checker_ids"),
-        toolBudget: typeof record.tool_budget === "number" ? record.tool_budget : 0,
-        frozenHash: String(record.frozen_hash ?? ""), acceptance: strings("acceptance"), allowedGraphDelta: strings("allowed_graph_delta"), onUnknown: "block_and_escalate",
-      };
-      if (!contract.contractId || !contract.frozenHash) return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: "Core returned an invalid execution contract." });
+      const contract = contractFromRecord(raw as Record<string, unknown>);
+      if (!contract) return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: "Core returned an invalid execution contract." });
       if (input.action === "inspect") return { content: [{ type: "text" as const, text: JSON.stringify(contract, null, 2) }], details: { contract } };
-      if (controlState.phase !== "planning") return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "Contracts may only be activated from the planning phase." });
+      if (!["planning", "waiting-user", "awaiting-approval"].includes(controlState.phase)) {
+        return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "Contracts may only be activated from the planning phase or while the step waits for user review." });
+      }
       const confirmed = await ctx.ui.confirm(
         "激活 Devflow 执行合同",
         [

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/advance_state.rb

@@ -504,7 +504,15 @@ result =
       next_intent_requested = false
       current_revision = Integer(state.fetch("revision", 0))
 
-      if !options[:expected_revision].nil? && current_revision != options[:expected_revision]
+      if state.dig("rollover", "status") && %w[prepared claimed].include?(state.dig("rollover", "status"))
+        result = fail_result(
+          "session_rollover_in_progress",
+          "rollover" => state["rollover"],
+          "message" => "Workflow transitions are frozen until the controlled session handoff is consumed or explicitly recovered."
+        )
+      end
+
+      if result.nil? && !options[:expected_revision].nil? && current_revision != options[:expected_revision]
         result = fail_result(
           "stale_revision",
           "expected_revision" => options[:expected_revision],

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/control_io.rb

@@ -31,6 +31,10 @@ module DevflowControlIO
               when :workflow then normalized.match?(%r{\A\.planning/workflows/[A-Za-z0-9][A-Za-z0-9_-]*\.yaml\z})
               when :registry then normalized == ".planning/artifacts/index.yaml"
               when :artifact then normalized.start_with?(".planning/") || normalized.start_with?(".context/")
+              # Feature names are user-facing and may be Unicode. `cleanpath`
+              # and the parent-traversal check above own containment; this
+              # matcher only fixes the handoff namespace and immutable name.
+              when :handoff then normalized.match?(%r{\A\.planning/handoffs/[^/]+/ROL-[0-9a-f-]+\.json\z})
               else false
               end
     raise InvalidControlPath, "invalid #{kind} control path" unless allowed

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/execution_contract.rb

@@ -13,7 +13,7 @@ require_relative "requirement_graph"
 POLICY = {
   "requirement-baseline" => { "checkers" => %w[requirement-graph-check slice-independence-check acceptance-coverage-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[requirement rule boundary slice acceptance] },
   "api-contract" => { "checkers" => %w[requirement-graph-check contract-coverage-check api-test-schema-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[api] },
-  "architecture-feasibility" => { "checkers" => %w[requirement-graph-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[workload_shape workload_constraint decision risk] },
+  "architecture-feasibility" => { "checkers" => %w[requirement-graph-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[workload_shape workload_constraint decision risk metric read_model] },
   "integration-verify" => { "checkers" => %w[requirement-graph-check slice-independence-check contract-coverage-check change-impact-check], "agents" => ["verification-runner"], "budget" => 1, "allowed_graph_delta" => %w[requirement risk decision] },
   "acceptance-test-design" => { "checkers" => %w[requirement-graph-check contract-coverage-check acceptance-coverage-check api-test-matrix-check test-coverage-check test-obligation-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[test_case] },
   "change-plan" => { "checkers" => %w[requirement-graph-check slice-independence-check contract-coverage-check api-test-matrix-check test-coverage-check test-obligation-check test-task-binding-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[acceptance] },

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/session_rollover.rb

@@ -0,0 +1,159 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Controlled, content-addressed session handoff state. This script is the only
+# writer for STATE.rollover; callers must hold no assumptions about a
+# filesystem "latest" handoff. STATE is the authority and immutable handoff
+# JSON is the evidence it points to.
+
+require "digest"
+require "json"
+require "optparse"
+require "securerandom"
+require "time"
+require "yaml"
+require_relative "control_io"
+
+options = { json: false, write: false }
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: session_rollover.rb prepare|claim|consume|inspect [options]"
+  opts.on("--write", "Apply the requested transition") { options[:write] = true }
+  opts.on("--json", "Print JSON") { options[:json] = true }
+  opts.on("--expected-revision N", Integer, "STATE revision compare-and-swap") { |v| options[:expected_revision] = v }
+  opts.on("--source-session-id ID", "Source OMP session id") { |v| options[:source_session_id] = v }
+  opts.on("--target-session-id ID", "Target OMP session id") { |v| options[:target_session_id] = v }
+  opts.on("--reason TEXT", "Auditable rollover reason") { |v| options[:reason] = v }
+end
+action = ARGV.shift
+parser.parse!
+
+def fail_result(reason, details = {})
+  { "ok" => false, "reason" => reason }.merge(details)
+end
+
+def parse_state(path)
+  raw = File.read(path)
+  match = raw.match(/\A---\n(.*?)\n---\n/m)
+  raise "STATE.md is missing YAML front matter" unless match
+  [YAML.safe_load(match[1], permitted_classes: [], aliases: false), raw]
+end
+
+def write_state(path, state, previous)
+  body = previous.sub(/\A---\n.*?\n---\n/m, "")
+  front = state.to_yaml.sub(/\A---\n/, "")
+  DevflowControlIO.atomic_write(path, "---\n#{front}---\n#{body}")
+end
+
+def valid_session_id?(value)
+  value.is_a?(String) && value.match?(/\A[A-Za-z0-9][A-Za-z0-9._:-]{0,255}\z/)
+end
+
+def iso_now
+  Time.now.utc.iso8601(3)
+end
+
+root = Dir.pwd
+state_path, = DevflowControlIO.resolve_control_path(root, ".planning/STATE.md", :state)
+result = catch(:transition_done) do
+  lock = DevflowControlIO.acquire_project_lock(root)
+  begin
+  unless File.exist?(state_path)
+    result = fail_result("missing_state")
+    throw :transition_done, result
+  end
+  state, raw = parse_state(state_path)
+  revision = Integer(state.fetch("revision", 0))
+  if !options[:expected_revision].nil? && revision != options[:expected_revision]
+    result = fail_result("stale_revision", "expected_revision" => options[:expected_revision], "actual_revision" => revision)
+    throw :transition_done, result
+  end
+  rollover = state["rollover"]
+
+  case action
+  when "inspect"
+    result = { "ok" => true, "revision" => revision, "rollover" => rollover }
+  when "prepare"
+    unless valid_session_id?(options[:source_session_id])
+      result = fail_result("invalid_source_session_id")
+      throw :transition_done, result
+    end
+    if rollover && %w[prepared claimed].include?(rollover["status"])
+      result = fail_result("rollover_in_progress", "rollover" => rollover)
+      throw :transition_done, result
+    end
+    rollover_id = "ROL-#{SecureRandom.uuid}"
+    relative_path = ".planning/handoffs/#{state.fetch("current_feature")}/#{rollover_id}.json"
+    absolute_path, = DevflowControlIO.resolve_control_path(root, relative_path, :handoff)
+    payload = {
+      "schema_version" => 1,
+      "rollover_id" => rollover_id,
+      "created_at" => iso_now,
+      "reason" => options[:reason].to_s.empty? ? "workflow_step_boundary" : options[:reason],
+      "source_session_id" => options[:source_session_id],
+      "state" => {
+        "revision" => revision,
+        "current_flow" => state["current_flow"], "current_feature" => state["current_feature"],
+        "current_phase" => state["current_phase"], "current_step" => state["current_step"],
+        "status" => state["status"], "completed_steps" => state["completed_steps"], "pending_steps" => state["pending_steps"]
+      },
+      "references" => {
+        "state_path" => ".planning/STATE.md",
+        "workflow_path" => state["workflow_config"],
+        "artifact_registry" => ".planning/artifacts/index.yaml"
+      }
+    }
+    serialized = JSON.generate(payload) + "\n"
+    digest = Digest::SHA256.hexdigest(serialized)
+    if options[:write]
+      DevflowControlIO.atomic_create(absolute_path, serialized)
+      state["rollover"] = {
+        "id" => rollover_id, "status" => "prepared", "handoff_path" => relative_path,
+        "handoff_sha256" => digest, "source_session_id" => options[:source_session_id],
+        "target_session_id" => nil, "expected_state_revision" => revision,
+        "prepared_at" => iso_now, "claimed_at" => nil
+      }
+      state["revision"] = revision + 1
+      write_state(state_path, state, raw)
+    end
+    result = { "ok" => true, "written" => options[:write], "rollover" => options[:write] ? state["rollover"] : payload.merge("handoff_sha256" => digest), "revision" => options[:write] ? revision + 1 : revision }
+  when "claim"
+    unless rollover.is_a?(Hash) && rollover["status"] == "prepared"
+      result = fail_result("rollover_not_prepared", "rollover" => rollover)
+      throw :transition_done, result
+    end
+    unless valid_session_id?(options[:target_session_id])
+      result = fail_result("invalid_target_session_id")
+      throw :transition_done, result
+    end
+    path, = DevflowControlIO.resolve_control_path(root, rollover["handoff_path"], :handoff)
+    unless File.exist?(path) && Digest::SHA256.hexdigest(File.binread(path)) == rollover["handoff_sha256"]
+      result = fail_result("handoff_integrity_failure")
+      throw :transition_done, result
+    end
+    if options[:write]
+      rollover["status"] = "claimed"; rollover["target_session_id"] = options[:target_session_id]; rollover["claimed_at"] = iso_now
+      state["rollover"] = rollover; state["revision"] = revision + 1; write_state(state_path, state, raw)
+    end
+    result = { "ok" => true, "written" => options[:write], "rollover" => rollover, "revision" => options[:write] ? revision + 1 : revision }
+  when "consume"
+    unless rollover.is_a?(Hash) && rollover["status"] == "claimed" && valid_session_id?(options[:target_session_id]) && rollover["target_session_id"] == options[:target_session_id]
+      result = fail_result("rollover_not_owned_by_target", "rollover" => rollover)
+      throw :transition_done, result
+    end
+    if options[:write]
+      rollover["status"] = "consumed"; rollover["consumed_at"] = iso_now
+      state["rollover"] = rollover; state["revision"] = revision + 1; write_state(state_path, state, raw)
+    end
+    result = { "ok" => true, "written" => options[:write], "rollover" => rollover, "revision" => options[:write] ? revision + 1 : revision }
+  else
+    result = fail_result("unknown_action")
+  end
+rescue DevflowControlIO::InvalidControlPath, Psych::Exception, SystemCallError, RuntimeError => error
+  result = fail_result("rollover_transition_failed", "message" => error.message)
+ensure
+  DevflowControlIO.release_lock(lock)
+  end
+end
+
+puts JSON.pretty_generate(result)
+exit(result["ok"] ? 0 : 1)

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/validate_state.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "digest"
 require "optparse"
 require "yaml"
 require_relative "control_io"
@@ -42,6 +43,7 @@ module WorkflowStateValidator
     REQUIRED_STATE_FIELDS.each do |field|
       issues << issue("error", "missing_state_field", "STATE.md is missing required field: #{field}", field: field) unless state.key?(field)
     end
+    validate_rollover(issues, root, state)
     return result(false, state_path, nil, nil, issues) if issues.any? { |entry| entry["severity"] == "error" }
 
     ownership = PhaseOwnership.validate_state(root: root, state: state, owner_override: phase_owner_override)
@@ -122,6 +124,40 @@ module WorkflowStateValidator
     nil
   end
 
+  def validate_rollover(issues, root, state)
+    rollover = state["rollover"]
+    return if rollover.nil?
+    unless rollover.is_a?(Hash)
+      issues << issue("error", "invalid_rollover", "STATE.rollover must be an object")
+      return
+    end
+    status = rollover["status"]
+    unless %w[prepared claimed consumed failed].include?(status)
+      issues << issue("error", "invalid_rollover_status", "STATE.rollover.status is invalid", status: status)
+      return
+    end
+    %w[id handoff_path handoff_sha256 source_session_id prepared_at].each do |field|
+      issues << issue("error", "missing_rollover_field", "STATE.rollover is missing #{field}", field: field) unless rollover[field].is_a?(String) && !rollover[field].empty?
+    end
+    return if issues.any? { |entry| entry["severity"] == "error" }
+    begin
+      handoff_path, = DevflowControlIO.resolve_control_path(root, rollover["handoff_path"], :handoff)
+      if %w[prepared claimed consumed].include?(status) && !File.exist?(handoff_path)
+        issues << issue("error", "missing_rollover_handoff", "STATE.rollover references a missing immutable handoff", path: rollover["handoff_path"])
+      elsif File.exist?(handoff_path) && Digest::SHA256.hexdigest(File.binread(handoff_path)) != rollover["handoff_sha256"]
+        issues << issue("error", "rollover_handoff_hash_mismatch", "STATE.rollover handoff hash does not match immutable payload", path: rollover["handoff_path"])
+      end
+    rescue DevflowControlIO::InvalidControlPath => error
+      issues << issue("error", "invalid_rollover_handoff_path", error.message)
+    end
+    if rollover["handoff_sha256"].to_s !~ /\A[0-9a-f]{64}\z/
+      issues << issue("error", "invalid_rollover_handoff_hash", "STATE.rollover.handoff_sha256 must be SHA-256 hex")
+    end
+    if status == "claimed" && (rollover["target_session_id"].to_s.empty? || rollover["claimed_at"].to_s.empty?)
+      issues << issue("error", "incomplete_rollover_claim", "Claimed rollover requires target_session_id and claimed_at")
+    end
+  end
+
   def load_yaml(path, issues, code)
     unless File.exist?(path)
       issues << issue("error", "missing_#{code}", "YAML file does not exist", path: path)

package/plugins/devflow-quality/skills/workflow-acceptance-test-design/SKILL.md

@@ -7,6 +7,14 @@ description: "Use after integration verification and before change planning to d
 
 在代码执行前，基于已确认的需求、契约和架构约束提出独立的 `TC-*` 验收测试候选。测试意图必须独立于实现：禁止读取 `SUMMARY.md`、实现源码、git diff 或 agent 交付自述来决定测试范围。
 
+## 执行合同
+
+本步骤的图谱写入受 ExecutionContract v2 约束：`devflow_requirement_graph(action="propose", kind="test_case")` 与 `devflow_api_test_matrix(action="import")` 仅在 active contract 的 step 为 `acceptance-test-design` 时放行。步骤开始且无 active contract 时：
+
+1. 先调用 `devflow_contract(action="status")` 检查当前会话是否有 active contract；
+2. 未激活时调用 `devflow_contract(action="activate", feature="<feature>", step="acceptance-test-design")` 合成并激活（planning / waiting-user / awaiting-approval 阶段均可，Core 校验 STATE 与图谱 revision 后由用户确认）；
+3. 会话中断后 contract 由 runtime 在 `session_start` 时从 `.planning/contracts/{feature}/EC-*.json` 自动恢复；恢复时校验 state/graph revision，推进后自动失效，需重新合成。
+
 ## 输入
 
 按顺序读取：

package/src/constants.ts

@@ -1,5 +1,5 @@
 export const PRODUCT_NAME = "Devflow Pi";
-export const PRODUCT_VERSION = "0.1.25";
+export const PRODUCT_VERSION = "0.1.26";
 export const PROJECT_SCHEMA_VERSION = 1;
 export const OMP_RUNTIME_VERSION = "17.2.7";
 

package/src/runtime.ts

@@ -1,4 +1,4 @@
-import { mkdir } from "node:fs/promises";
+import { mkdir, readFile, rm } from "node:fs/promises";
 import path from "node:path";
 
 import { OMP_RUNTIME_VERSION, PRODUCT_NAME, PRODUCT_VERSION } from "./constants.ts";
@@ -61,6 +61,10 @@ const MANAGED_SETTINGS: Record<string, unknown> = {
   "lsp.enabled": true,
   "lsp.lazy": true,
   "lsp.diagnosticsOnWrite": true,
+  // Devflow owns cross-session handoff through STATE.rollover. OMP's LLM-made
+  // handoff would create a second, unauditable source of continuation facts.
+  "compaction.strategy": "context-full",
+  "compaction.handoffSaveToDisk": false,
 };
 
 export async function createEmbeddedRuntime(project: ProjectContext, options: RuntimeOptions = {}) {
@@ -173,8 +177,39 @@ export async function runInteractiveRuntime(project: ProjectContext, options: Ru
   mode.showStatus(`Devflow project ${project.manifest.name} · ${project.manifest.projectId.slice(0, 8)}`);
   if (runtime.modelFallbackMessage) mode.showWarning(runtime.modelFallbackMessage);
   if (options.initialPrompt) await runtime.session.prompt(options.initialPrompt);
+  // Extensions cannot create a session from lifecycle hooks.  The interactive
+  // loop, however, owns AgentSession and reaches this point only after the
+  // submitted turn has settled.  A request is merely a wake-up signal: its
+  // authority remains STATE.rollover, which the extension verifies and claims
+  // during session_switch before it starts the next workflow turn.
+  const consumeControlledRollover = async (): Promise<void> => {
+    const requestPath = path.join(project.root, ".planning", "rollover-request.json");
+    let request: { schema_version?: number; rollover_id?: string; source_session_id?: string };
+    try {
+      request = JSON.parse(await readFile(requestPath, "utf8")) as typeof request;
+    } catch {
+      return;
+    }
+    if (
+      request.schema_version !== 1 ||
+      typeof request.rollover_id !== "string" ||
+      !/^ROL-[0-9a-f-]+$/i.test(request.rollover_id) ||
+      request.source_session_id !== runtime.session.sessionManager.getSessionId()
+    ) {
+      await rm(requestPath, { force: true });
+      mode.showWarning("已忽略无效或陈旧的 Devflow 会话轮换请求；STATE 未被修改。");
+      return;
+    }
+    const switched = await runtime.session.newSession();
+    if (!switched) {
+      mode.showWarning("Devflow 会话轮换被运行时取消；当前会话保持不变。请检查控制面状态后重试。");
+      return;
+    }
+    await rm(requestPath, { force: true });
+  };
   while (true) {
     const input = await mode.getUserInput();
     await omp.submitInteractiveInput(mode, runtime.session, input);
+    await consumeControlledRollover();
   }
 }