@guanlin4924/devflow-pi 0.1.24 → 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-*` 验收测试设计，再生成变更清单：
@@ -130,6 +136,7 @@ bash .skills/install.sh --apply --force-config
 - `TC-*` 的步骤和 oracle 在代码出现前冻结；CP-3 在同一次确认中先校验候选绑定，再冻结 TC 并固定绑定哈希。需求或契约变化会使它 stale，不能继续以旧测试集宣称通过。
 - `tdd_required` 任务必须先由 Core 记录准备快照，再记录 RED（命中预期失败）、同一目标的 GREEN 和回归；缺失或环境失败不算完成。
 - API、跨数据域、边界、迁移、工作负载与架构风险会派生相应的 `api`、`permission`、`boundary`、`migration`、`performance`、`resilience` TC 义务。
+- 每个 TC 还要声明证明策略：`replay` 用组件/页面/API/集成的稳定回放；`causal` 用已定位的首个偏差加 HAR、控制台、DOM 快照、截图或日志等受控文件证明，Core 会记录文件哈希；`observation` 用于尚不可复现、也未能证明根因的问题，只能保持阻塞并带观测计划。后两者都不能被“AI 已复现”或 Markdown 自述放行。
 - 代码完成后，`workflow-run-acceptance-tests` 只能运行绑定到冻结 TC、且已在初始化 `.planning/toolchain.md` 发现的测试运行器命令。任何失败、未执行、人工待执行或环境阻塞用例都会阻止 CP-4。
 - 验收不是代码完成后的临时手工检查。它是需求基线在编码前派生并冻结的完整测试集，覆盖主流程、异常、边界、权限、迁移、兼容、韧性和工作负载义务；代码只能补充执行适配信息，不能改变测试意图。
 - 验收失败不会创建另一套人工台账，而是进入 `acceptance-remediation`：诊断 → 修复 → code-index 刷新 → 原冻结 `TC-*` 重跑。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.24",
+  "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/acceptance_test_runner.py

@@ -20,6 +20,8 @@ from test_command_policy import validate_test_command
 
 FEATURE_RE = re.compile(r"^[^/\\\x00-\x1f\x7f]+$")
 AUTOMATION_MODES = {"automated", "manual", "blocked"}
+EVIDENCE_STRATEGIES = {"replay", "causal", "observation"}
+MAX_EVIDENCE_FILE_BYTES = 25 * 1024 * 1024
 
 
 def utc_now() -> str:
@@ -142,6 +144,38 @@ def file_fingerprint(path: Path) -> str | None:
     return digest(path.read_bytes()) if path.is_file() else None
 
 
+def evidence_artifacts(root: Path, value: Any) -> tuple[list[dict[str, Any]], list[str]]:
+    """Hash causal evidence from bounded project-relative files only."""
+    if not isinstance(value, list) or not value:
+        return [], ["causal verification requires non-empty evidence_files"]
+    root_real = root.resolve()
+    artifacts: list[dict[str, Any]] = []
+    errors: list[str] = []
+    for raw in value:
+        if not isinstance(raw, str) or not raw.strip() or "\x00" in raw:
+            errors.append("evidence_files entries must be non-empty relative paths")
+            continue
+        candidate = Path(raw)
+        if candidate.is_absolute() or ".." in candidate.parts:
+            errors.append(f"evidence file escapes project root: {raw}")
+            continue
+        resolved = (root_real / candidate).resolve()
+        try:
+            relative = resolved.relative_to(root_real)
+        except ValueError:
+            errors.append(f"evidence file escapes project root: {raw}")
+            continue
+        if not resolved.is_file():
+            errors.append(f"causal evidence file is missing: {raw}")
+            continue
+        size = resolved.stat().st_size
+        if size > MAX_EVIDENCE_FILE_BYTES:
+            errors.append(f"causal evidence file exceeds {MAX_EVIDENCE_FILE_BYTES} bytes: {raw}")
+            continue
+        artifacts.append({"path": relative.as_posix(), "sha256": digest(resolved.read_bytes()), "bytes": size})
+    return artifacts, errors
+
+
 def run_http_case(source: dict[str, Any], adapter: dict[str, Any]) -> tuple[bool, int, str]:
     execution = source["execution"]
     request_spec = execution["request"]
@@ -248,6 +282,11 @@ def validate(root: Path, feature: str) -> tuple[dict[str, Any], dict[str, Any] |
         if source is None:
             errors.append(f"unknown TC reference: {tc_id}")
             continue
+        strategy = source.get("evidence_strategy")
+        if strategy is not None and strategy not in EVIDENCE_STRATEGIES:
+            errors.append(f"{label}.source evidence_strategy is invalid")
+        if strategy == "observation" and source.get("automation_mode") != "blocked":
+            errors.append(f"{label}.observation source must be blocked")
         mode = entry.get("mode")
         if mode not in AUTOMATION_MODES:
             errors.append(f"{label}.mode is invalid")
@@ -278,6 +317,9 @@ def validate(root: Path, feature: str) -> tuple[dict[str, Any], dict[str, Any] |
                             errors.append(f"{label}.adapter.setup: {setup_error}")
             else:
                 errors.append(f"{label}.adapter kind must be command or http")
+            if strategy == "causal":
+                _artifacts, artifact_errors = evidence_artifacts(root, entry.get("evidence_files"))
+                errors.extend(f"{label}.{error}" for error in artifact_errors)
         elif mode == "manual":
             if not isinstance(entry.get("owner"), str) or not entry["owner"].strip() or not isinstance(entry.get("reason"), str) or not entry["reason"].strip():
                 errors.append(f"{label}.manual requires owner and reason")
@@ -303,6 +345,7 @@ def run(root: Path, feature: str, write: bool) -> dict[str, Any]:
     for entry in bindings["cases"]:
         tc_id = entry["tc_id"]
         mode = entry["mode"]
+        strategy = cases[tc_id].get("evidence_strategy")
         if mode == "automated":
             started_at = utc_now()
             adapter = entry["adapter"]
@@ -326,6 +369,13 @@ def run(root: Path, feature: str, write: bool) -> dict[str, Any]:
                 result = {"tc_id": tc_id, "status": "passed" if passed else "failed", "mode": mode, "adapter_kind": "http",
                           "adapter_fingerprint": digest(json.dumps(adapter, ensure_ascii=False, separators=(",", ":"))), "started_at": started_at,
                           "finished_at": utc_now(), "exit_code": exit_code, "output_sha256": digest(output)}
+            if strategy == "causal":
+                artifacts, artifact_errors = evidence_artifacts(root, entry.get("evidence_files"))
+                if artifact_errors:
+                    result["status"] = "failed"
+                    result["evidence_error"] = "; ".join(artifact_errors)
+                else:
+                    result["evidence_artifacts"] = artifacts
             results.append(result)
         elif mode == "manual":
             results.append({"tc_id": tc_id, "status": "blocked", "mode": mode, "owner": entry["owner"], "reason": entry["reason"],

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/api_test_matrix.py

@@ -554,6 +554,8 @@ def tc_candidate(api: dict[str, Any], graph: dict[str, Any], key: str, obligatio
         "steps": ["发送 execution.request 中定义的 HTTP 请求"],
         "oracle": oracle,
         "automation_mode": "automated",
+        "evidence_strategy": "replay",
+        "replay_scope": "api",
         "api_refs": [api["id"]],
         "execution": execution,
     }

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

@@ -96,13 +96,29 @@ module ArchitectureBrief
       assessment["triggers"].each { |trigger| lines << "- `#{trigger["code"]}` — #{trigger["node_id"]}" }
     end
 
-    lines.concat(["", "## 工作负载形态", "", "| 节点 | 状态 | 执行 | 操作 | 扇出 | 数据影响 | 外部调用 |", "|---|---|---|---|---|---|---|"])
+    lines.concat(["", "## 工作负载形态", "", "| 节点 | 状态 | 类型 | 一致性 | 执行 | 操作 | 扇出 | 数据影响 |", "|---|---|---|---|---|---|---|---|"])
     if workload_shapes.empty?
-      lines << "| — | — | — | — | — | — | — |"
+      lines << "| — | — | — | — | — | — | — | — |"
     else
       workload_shapes.each do |node|
         facts = node.fetch("data", {}).fetch("facts", {})
-        lines << "| #{node["id"]} | #{node["status"]} | #{text(facts["execution"])} | #{text(facts["operation"])} | #{text(facts["fanout"])} | #{text(facts["data_effect"])} | #{text(Array(facts["external_calls"]).join(", "))} |"
+        lines << "| #{node["id"]} | #{node["status"]} | #{text(facts["archetype"] || "legacy")} | #{text(facts["consistency"] || "—")} | #{text(facts["execution"])} | #{text(facts["operation"])} | #{text(facts["fanout"])} | #{text(facts["data_effect"])} |"
+      end
+    end
+
+    metrics = Array(graph["nodes"]).select { |node| node["kind"] == "metric" }
+    read_models = Array(graph["nodes"]).select { |node| node["kind"] == "read_model" }
+    lines.concat(["", "## 统计指标与读模型", "", "| 节点 | 状态 | 定义/服务对象 | 时间与修正 |", "|---|---|---|---|"])
+    if metrics.empty? && read_models.empty?
+      lines << "| — | — | — | — |"
+    else
+      metrics.each do |node|
+        data = node.fetch("data", {})
+        lines << "| #{node["id"]} | #{node["status"]} | 指标：#{text(data["name"])}；粒度：#{text(data["grain"])} | #{text(data["time_basis"])} / #{text(data["timezone"])}；#{text(data["correction_policy"])} |"
+      end
+      read_models.each do |node|
+        data = node.fetch("data", {})
+        lines << "| #{node["id"]} | #{node["status"]} | 读模型：#{text(data["projection_mode"])}；服务：#{text(Array(data["serves"]).join(", "))} | 重建：#{text(data.dig("rebuild", "method"))}；迟到数据：#{text(data["late_data_policy"])} |"
       end
     end
 

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

@@ -13,6 +13,10 @@ module ArchitectureConstraints
   OPERATIONS = %w[read write batch_read batch_write].freeze
   FANOUTS = %w[none bounded unbounded unknown].freeze
   DATA_EFFECTS = %w[none update append_only migration unknown].freeze
+  ARCHETYPES = %w[transactional_command operational_query analytics_query analytics_projection batch_processing external_integration].freeze
+  DATA_ROLES = %w[source_of_truth derived_read_model external_projection].freeze
+  CONSISTENCIES = %w[strong read_your_write bounded_staleness eventual unknown].freeze
+  EVENT_TIMES = %w[required not_applicable unknown].freeze
   METRICS = %w[peak_qps data_growth p95_latency rpo rto].freeze
   SOURCE_STATUSES = %w[measured contracted approved_assumption unknown].freeze
   EVIDENCE_KINDS = %w[source_file cp_record external_measurement].freeze
@@ -52,6 +56,26 @@ module ArchitectureConstraints
     errors_for_enum(errors, facts, "data_effect", DATA_EFFECTS)
     external_calls = facts["external_calls"]
     errors << "external_calls must be an array" unless external_calls.nil? || external_calls.is_a?(Array)
+    # `archetype` is optional for pre-v5 graphs. Once supplied it is a
+    # contract, not prose: analytics shapes must say what they serve and how
+    # their time semantics behave.
+    if facts.key?("archetype")
+      errors_for_enum(errors, facts, "archetype", ARCHETYPES)
+      errors_for_enum(errors, facts, "data_role", DATA_ROLES)
+      errors_for_enum(errors, facts, "consistency", CONSISTENCIES)
+      time = facts["time_semantics"]
+      errors << "time_semantics must be an object" unless time.is_a?(Hash)
+      errors_for_enum(errors, time || {}, "event_time", EVENT_TIMES)
+      errors << "time_semantics.timezone is required" unless present?(time && time["timezone"])
+      if %w[analytics_query analytics_projection].include?(facts["archetype"])
+        refs = shape["metric_refs"]
+        errors << "analytics workloads require non-empty metric_refs" unless refs.is_a?(Array) && !refs.empty?
+      end
+      if facts["archetype"] == "analytics_projection"
+        refs = shape["read_model_refs"]
+        errors << "analytics projections require non-empty read_model_refs" unless refs.is_a?(Array) && !refs.empty?
+      end
+    end
     source_refs = shape["source_refs"]
     errors << "source_refs must be a non-empty array" unless source_refs.is_a?(Array) && !source_refs.empty?
     Array(source_refs).each { |ref| errors << "source_refs must reference REQ/BEH/API" unless reference?(ref, %w[REQ BEH API]) }