@guanlin4924/devflow-pi 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "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, rename, writeFile } from "node:fs/promises";
+import { mkdir, 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";
@@ -20,9 +20,17 @@ type ActiveExecutionContract = {
   contractId: string;
   feature: string;
   step: string;
+  stateRevision?: number;
+  graphRevision?: number;
   allowedPaths: string[];
   allowedAgents: string[];
+  allowedTools: string[];
+  checkerIds: string[];
+  toolBudget: number;
+  frozenHash: string;
+  contractPath?: string;
   acceptance: string[];
+  allowedGraphDelta: string[];
   onUnknown: "block_and_escalate";
 };
 
@@ -198,7 +206,7 @@ const CONTROL_PATHS = [
   ".planning/artifacts/index.yaml",
 ];
 
-const CONTROL_PREFIXES = [".planning/workflows/", ".planning/contracts/"];
+const CONTROL_PREFIXES = [".planning/workflows/", ".planning/contracts/", ".planning/evidence/"];
 
 const REQUIRED_EXTENSION_TOOLS = [
   "devflow_doctor",
@@ -206,6 +214,10 @@ const REQUIRED_EXTENSION_TOOLS = [
   "devflow_bootstrap",
   "devflow_transition",
   "devflow_artifact",
+  "devflow_machine_evidence",
+  "devflow_requirement_graph",
+  "devflow_evidence",
+  "devflow_contract",
   "devflow_recovery",
   "devflow_skill_script",
   "devflow_context_sync",
@@ -276,6 +288,9 @@ const REQUIRED_SCRIPTS = [
   "workflow-orchestrator/scripts/inspect_state.rb",
   "workflow-orchestrator/scripts/advance_state.rb",
   "workflow-orchestrator/scripts/sync_artifacts.rb",
+  "workflow-orchestrator/scripts/requirement_graph.rb",
+  "workflow-orchestrator/scripts/machine_evidence.rb",
+  "workflow-orchestrator/scripts/execution_contract.rb",
   "workflow-code-index/scripts/code_index.py",
   "workflow-context-sync/scripts/context_sync_cursor.py",
 ];
@@ -380,6 +395,19 @@ function safeControlPath(cwd: string, raw: string | undefined, kind: "state" | "
   return relative;
 }
 
+function isCanonicalRequirementGraphPath(filePath: string): boolean {
+  return /^\.planning\/requirements\/[^/\\\x00-\x1F\x7F]+\/(?:governance|evidence|definitions|behavior-graph|requirement-graph|slices|acceptance|traceability|graph\.meta)\.json$/u.test(filePath)
+    || /^\.planning\/requirements\/[^/\\\x00-\x1F\x7F]+\/(?:context\/[^/\\]+\.json|control-events\.jsonl)$/u.test(filePath);
+}
+
+function isCoreOwnedGovernancePath(filePath: string): boolean {
+  // 规范需求图谱只能由 Core 的 devflow_requirement_graph writer 写入；the
+  // same ownership extends to its views, machine evidence, and audit records.
+  return isCanonicalRequirementGraphPath(filePath)
+    || /^\.planning\/evidence\/[^/\\\x00-\x1F\x7F]+\/[^/\\]+\.machine\.json$/u.test(filePath)
+    || /^\.planning\/contracts\/[^/\\\x00-\x1F\x7F]+\/(?:EC-[A-Fa-f0-9]+\.json|control-events\.jsonl)$/u.test(filePath);
+}
+
 function resolveIntelSkillRoot(cwd: string): string | undefined {
   if (isEmbeddedRuntime()) {
     const packaged = path.join(resolvePluginRoot(), "devflow-intel", "skills");
@@ -641,10 +669,10 @@ function isShellControlMutation(toolName: string, input: unknown): boolean {
   const command = String((input as Record<string, unknown>).command ?? (input as Record<string, unknown>).cmd ?? "");
   if (!command) return false;
   const invokesWriter =
-    /workflow-orchestrator\/scripts\/(?:advance_state|init_state|init_workflow|sync_artifacts)\.rb[^\n]*--write/.test(
+    /workflow-orchestrator\/scripts\/(?:advance_state|init_state|init_workflow|sync_artifacts|requirement_graph|machine_evidence|execution_contract)\.rb[^\n]*--write/.test(
       command,
     );
-  const namesControlPath = [...CONTROL_PATHS, ...CONTROL_PREFIXES].some(item => command.includes(item));
+  const namesControlPath = [...CONTROL_PATHS, ...CONTROL_PREFIXES].some(item => command.includes(item)) || /\.planning\/requirements\//.test(command);
   const looksLikeWrite = /(?:^|[;&|]\s*)(?:rm|mv|cp|install|truncate)\b|(?:^|\s)(?:tee|sed\s+-i|perl\s+-i)\b|>{1,2}/.test(
     command,
   );
@@ -668,6 +696,7 @@ export default function devflowCore(pi: ExtensionAPI) {
   let sessionId = randomUUID();
   let controlState: SessionControlState = initialControlState();
   let activeContract: ActiveExecutionContract | undefined;
+  let contractAgentCalls = 0;
 
   function setControlState(ctx: { ui: { setStatus(key: string, text: string | undefined): void } }, state: SessionControlState) {
     controlState = state;
@@ -686,18 +715,14 @@ export default function devflowCore(pi: ExtensionAPI) {
     return contract.allowedPaths.some(root => filePath === root || filePath.startsWith(`${root}/`));
   }
 
-  async function persistContract(cwd: string, contract: ActiveExecutionContract): Promise<string> {
-    assertRuntimeProjectBoundary(cwd);
-    const feature = normalizeContractSegment(contract.feature, "feature");
-    const contractId = normalizeContractSegment(contract.contractId, "contractId");
-    const root = path.join(cwd, ".planning", "contracts", feature);
-    const destination = path.join(root, `${contractId}.json`);
-    await mkdir(root, { recursive: true });
-    const payload = JSON.stringify({ schemaVersion: 1, activatedAt: new Date().toISOString(), ...contract }, null, 2) + "\n";
-    const temporary = `${destination}.${randomUUID()}.tmp`;
-    await writeFile(temporary, payload, "utf8");
-    await rename(temporary, destination);
-    return path.relative(cwd, destination).replaceAll("\\", "/");
+  async function contractIsFresh(cwd: string, contract: ActiveExecutionContract): Promise<boolean> {
+    const state = parseJsonResult(await runRuby(cwd, "workflow-orchestrator/scripts/inspect_state.rb", ["--json"]));
+    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;
+    return stateRevision === contract.stateRevision && graphRevision === contract.graphRevision;
   }
 
   async function collectProjectInitialization(ctx: {
@@ -1079,6 +1104,14 @@ export default function devflowCore(pi: ExtensionAPI) {
 
   pi.on("tool_call", async (event, ctx) => {
     const toolName = String(event.toolName).toLowerCase();
+    if (activeContract && controlState.phase === "executing" && !toolName.startsWith("devflow_")) {
+      if (!activeContract.allowedTools.includes(toolName)) {
+        return { block: true, reason: `Active contract ${activeContract.contractId} does not allow tool: ${toolName}` };
+      }
+      if (!(await contractIsFresh(ctx.cwd, activeContract))) {
+        return { block: true, reason: `Active contract ${activeContract.contractId} is stale against STATE or graph revision; synthesize a new contract before continuing.` };
+      }
+    }
     if (toolName === "task") {
       const requested = requestedTaskAgents(event.input);
       if (requested.missing) {
@@ -1109,8 +1142,12 @@ export default function devflowCore(pi: ExtensionAPI) {
         controlState.phase === "executing" &&
         !requested.names.every(agent => activeContract?.allowedAgents.includes(agent))
       ) {
-        return { block: true, reason: `Active contract ${activeContract.contractId} only allows agents: ${activeContract.allowedAgents.join(", ")}` };
+          return { block: true, reason: `Active contract ${activeContract.contractId} only allows agents: ${activeContract.allowedAgents.join(", ")}` };
+      }
+      if (activeContract && controlState.phase === "executing" && contractAgentCalls >= activeContract.toolBudget) {
+        return { block: true, reason: `Active contract ${activeContract.contractId} exhausted its fixed agent budget (${activeContract.toolBudget}).` };
       }
+      if (activeContract && controlState.phase === "executing") contractAgentCalls += 1;
     } else if (
       controlState.phase === "planning" &&
       toolName !== "devflow_contract" &&
@@ -1129,6 +1166,16 @@ export default function devflowCore(pi: ExtensionAPI) {
           "Devflow 状态迁移只能由运行时在用户明确批准已展示的步骤或 checkpoint 后执行；LLM 不得自行推进。",
       };
     }
+    if (
+      !toolName.startsWith("devflow_") &&
+      ["write", "edit", "apply_patch", "notebook_edit", "bash", "shell", "exec_command"].includes(toolName) &&
+      inputPaths(event.input, ctx.cwd).some(isCoreOwnedGovernancePath)
+    ) {
+      return {
+        block: true,
+        reason: "规范需求图谱、派生视图、机器 Evidence 与合同审计只能由 Core writer 写入；Skill 只能提交候选 delta 或 agent_claim。",
+      };
+    }
     if (toolName.startsWith("devflow_")) return;
     if (
       activeContract &&
@@ -1234,6 +1281,319 @@ export default function devflowCore(pi: ExtensionAPI) {
     }
   });
 
+  pi.registerTool({
+    name: "devflow_machine_evidence",
+    label: "Devflow Machine Evidence",
+    description: "Collect Core-owned evidence from the current workflow step's actual required outputs and graph revision.",
+    parameters: z.object({ feature: z.string().min(1), step: z.string().min(1) }),
+    approval: "write",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      return renderResult(
+        await runRuby(ctx.cwd, "workflow-orchestrator/scripts/machine_evidence.rb", ["--feature", params.feature, "--step", params.step, "--write"]),
+        { feature: params.feature, step: params.step },
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_requirement_graph",
+    label: "Devflow Requirement Graph",
+    description: "Submit bounded requirement-graph candidates or inspect/validate the Core-owned canonical graph.",
+    parameters: z.object({
+      action: z.enum(["propose", "inspect", "validate", "context", "confirm"]),
+      feature: z.string().min(1),
+      expectedRevision: z.number().int().min(0).optional(),
+      sliceId: z.string().min(1).optional(),
+      nodeId: z.string().min(1).optional(),
+      evidence: z.object({ cp_record: z.unknown().optional(), evidence_ref: z.unknown().optional() }).optional(),
+      write: z.boolean().optional(),
+      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"]).optional(),
+        id: z.string().min(1).optional(),
+        data: z.record(z.string(), z.unknown()).optional(),
+        from: z.string().min(1).optional(),
+        to: z.string().min(1).optional(),
+        relation: z.string().min(1).optional(),
+        propagation: z.enum(["one_hop", "full"]).optional(),
+      }).optional(),
+    }),
+    approval: (args) => args.action === "propose" || args.action === "confirm" ? "write" : "read",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const args = [params.action, "--feature", params.feature, "--json"];
+      if (params.action === "context") {
+        if (!params.sliceId) return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "context requires sliceId" });
+        args.push("--slice-id", params.sliceId);
+        if (params.write) args.push("--write");
+        if (params.read) args.push("--read");
+      }
+      if (params.action === "propose") {
+        if (params.expectedRevision === undefined || !params.delta) {
+          return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "propose requires expectedRevision and delta" });
+        }
+        args.push("--write", "--expected-revision", String(params.expectedRevision), "--delta-json", JSON.stringify(params.delta));
+        if (activeContract?.allowedGraphDelta?.length) args.push("--allowed-kinds", activeContract.allowedGraphDelta.join(","));
+      }
+      if (params.action === "confirm") {
+        if (params.expectedRevision === undefined || !params.nodeId || !params.evidence) {
+          return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "confirm requires expectedRevision, nodeId and evidence" });
+        }
+        args.push("--write", "--expected-revision", String(params.expectedRevision), "--node-id", params.nodeId, "--evidence-json", JSON.stringify(params.evidence));
+        const inspected = parseJsonResult(
+          await runRuby(ctx.cwd, "workflow-orchestrator/scripts/requirement_graph.rb", ["inspect", "--feature", params.feature, "--json"]),
+        );
+        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 preview = JSON.stringify(node.data ?? {}, null, 2);
+          const decisionDialog = architectureDecision;
+          const riskDialog = architectureRisk;
+          const confirmed = await ctx.ui.confirm(
+            decisionDialog ? "确认架构方案取舍" : riskDialog ? "确认架构风险处理" : "确认工作负载事实或缺口",
+            [
+              `Feature：${params.feature}`,
+              `节点：${params.nodeId}`,
+              `类型：${decisionDialog ? "架构方案比较" : riskDialog ? "架构风险处理" : node.kind === "workload_shape" ? "工作负载形态" : "工作负载约束"}`,
+              decisionDialog
+                ? "确认的含义是：你已核对候选方案、证据与取舍，并接受其中 recommendation_option_id 作为本次架构选择。"
+                : riskDialog
+                  ? "确认的含义是：你已核对失败模式、影响、处理方式、负责人和复核条件；它不代表生产风险从此消失。"
+                : "确认的含义仅是：该事实或缺口、来源与责任归属已被你核对；它不代表容量已经满足，也不会替你选择实现方案。",
+              "待确认内容：",
+              preview.length > 8_000 ? `${preview.slice(0, 8_000)}\n…（内容过长，已截断）` : preview,
+            ].join("\n\n"),
+          );
+          if (!confirmed) return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: "User declined workload confirmation; node remains candidate." });
+          args.push("--confirmed-interactively");
+        }
+      }
+      return renderResult(
+        await runRuby(ctx.cwd, "workflow-orchestrator/scripts/requirement_graph.rb", args),
+        { action: params.action, feature: params.feature },
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_runtime_context",
+    label: "Devflow Runtime Context",
+    description: "Collect or inspect the P0 repository-declared dependency snapshot and its coverage.",
+    parameters: z.object({
+      action: z.enum(["collect", "inspect"]),
+    }),
+    approval: (args) => args.action === "collect" ? "write" : "read",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      return renderResult(
+        await runRuby(ctx.cwd, "workflow-orchestrator/scripts/runtime_context_collector.rb", [params.action, "--json"]),
+        { action: params.action },
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_static_runtime_context",
+    label: "Devflow Static Runtime Context",
+    description: "Collect or inspect the P1 static evidence snapshot. It records only repository declarations and references, never production health or capacity.",
+    parameters: z.object({
+      action: z.enum(["collect", "inspect"]),
+    }),
+    approval: (args) => args.action === "collect" ? "write" : "read",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      return renderResult(
+        await runRuby(ctx.cwd, "workflow-orchestrator/scripts/static_runtime_context_collector.rb", [params.action, "--json"]),
+        { action: params.action },
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_architecture_assessment",
+    label: "Devflow Architecture Assessment",
+    description: "Confirm an immutable delta set through an explicit user dialog, then assess only that Core-owned manifest against a pinned runtime-context snapshot.",
+    parameters: z.object({
+      action: z.enum(["inspect", "assess", "write-manifest"]),
+      feature: z.string().min(1),
+      baseSnapshotRevision: z.number().int().min(0).optional(),
+      deltaSetId: z.string().min(1).optional(),
+      deltaJson: z.array(z.record(z.string(), z.unknown())).optional(),
+      sourceBundleRevision: z.string().min(1).optional(),
+      expectedAssessmentRevision: z.number().int().min(0).optional(),
+      write: z.boolean().optional(),
+    }),
+    approval: (args) => args.action === "write-manifest" || args.write ? "write" : "read",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const args = [params.action, "--feature", params.feature, "--json"];
+      if (params.action === "inspect") {
+        if (params.deltaSetId) args.push("--delta-set-id", params.deltaSetId);
+        return renderResult(
+          await runRuby(ctx.cwd, "workflow-orchestrator/scripts/architecture_assessment.rb", args),
+          { action: params.action, feature: params.feature },
+        );
+      }
+      if (!params.deltaSetId) {
+        return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "deltaSetId is required" });
+      }
+      args.push("--delta-set-id", params.deltaSetId);
+      if (params.action === "assess") {
+        if (params.baseSnapshotRevision === undefined) {
+          return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "assess requires baseSnapshotRevision and deltaSetId; deltas and manifest are Core-owned" });
+        }
+        args.push("--base-snapshot-revision", String(params.baseSnapshotRevision));
+        if (params.write) {
+          const inspected = parseJsonResult(await runRuby(ctx.cwd, "workflow-orchestrator/scripts/architecture_assessment.rb", ["inspect", "--feature", params.feature, "--delta-set-id", params.deltaSetId, "--json"]));
+          const currentRevision = typeof inspected?.current_assessment_revision === "number" ? inspected.current_assessment_revision : undefined;
+          if (currentRevision === undefined) {
+            return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: "Unable to read the current assessment revision for CAS." });
+          }
+          args.push("--write", "--expected-assessment-revision", String(currentRevision));
+        }
+      }
+      if (params.action === "write-manifest") {
+        if (!params.sourceBundleRevision || !params.deltaJson?.length) {
+          return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "write-manifest requires deltaSetId, sourceBundleRevision and a non-empty deltaJson" });
+        }
+        const preview = params.deltaJson.map((rawDelta, index) => {
+          const delta = rawDelta as Record<string, unknown>;
+          const source = delta.source && typeof delta.source === "object" ? delta.source as Record<string, unknown> : {};
+          return [
+            `${index + 1}. ID：${String(delta.id ?? "(缺失)")}`,
+            `依赖：${String(delta.subject ?? "(缺失)")}`,
+            `来源：${String(source.locator ?? "(缺失)")}`,
+            `来源 revision：${String(source.repository_revision ?? "(缺失)")}`,
+            `内容哈希：${String(source.input_hash ?? "(缺失)")}`,
+          ].join("\n");
+        }).join("\n\n");
+        const confirmed = await ctx.ui.confirm(
+          "确认架构评估 Delta 集合",
+          [
+            `Feature：${params.feature}`,
+            `Delta 集合：${params.deltaSetId}`,
+            `需求/方案 revision：${params.sourceBundleRevision}`,
+            "确认后 Core 会创建不可覆盖的 manifest；后续评估只能读取这一份确认内容。",
+            "请核对以下依赖、来源与哈希：",
+            preview,
+          ].join("\n\n"),
+        );
+        if (!confirmed) return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: "User declined delta-set confirmation; no manifest was written." });
+        args.push("--source-bundle-revision", params.sourceBundleRevision, "--delta-json", JSON.stringify(params.deltaJson), "--confirmed-interactively", "--write");
+      }
+      return renderResult(
+        await runRuby(ctx.cwd, "workflow-orchestrator/scripts/architecture_assessment.rb", args),
+        { action: params.action, feature: params.feature },
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_workload_constraint",
+    label: "Devflow Workload Constraint",
+    description: "Validate a workload constraint (NFR) against its source-status schema.",
+    parameters: z.object({
+      constraintJson: z.record(z.string(), z.unknown()),
+    }),
+    approval: "read",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      return renderResult(
+        await runRuby(ctx.cwd, "workflow-orchestrator/scripts/workload_constraint.rb", ["validate", "--constraint-json", JSON.stringify(params.constraintJson), "--json"]),
+        {},
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_architecture_constraint",
+    label: "Devflow Architecture Constraint",
+    description: "Validate candidate workload shape or workload constraint inputs without assigning confirmation, decisions, or gate status.",
+    parameters: z.object({
+      action: z.enum(["validate-shape", "validate-constraint"]),
+      shapeJson: z.record(z.string(), z.unknown()).optional(),
+      constraintJson: z.record(z.string(), z.unknown()).optional(),
+    }),
+    approval: "read",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      if (params.action === "validate-shape" && !params.shapeJson) {
+        return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "validate-shape requires shapeJson" });
+      }
+      if (params.action === "validate-constraint" && !params.constraintJson) {
+        return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "validate-constraint requires constraintJson" });
+      }
+      const args = [params.action, "--json"];
+      if (params.shapeJson) args.push("--shape-json", JSON.stringify(params.shapeJson));
+      if (params.constraintJson) args.push("--constraint-json", JSON.stringify(params.constraintJson));
+      return renderResult(
+        await runRuby(ctx.cwd, "workflow-orchestrator/scripts/architecture_constraints.rb", args),
+        { action: params.action },
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_architecture_feasibility",
+    label: "Devflow Architecture Feasibility",
+    description: "Read confirmed workload facts and a pinned static-context snapshot to derive an advisory architecture assessment. It never selects an option or claims production capacity.",
+    parameters: z.object({
+      feature: z.string().min(1),
+    }),
+    approval: "read",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      return renderResult(
+        await runRuby(ctx.cwd, "workflow-orchestrator/scripts/architecture_feasibility.rb", ["assess", "--feature", params.feature, "--json"]),
+        { feature: params.feature },
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_architecture_brief",
+    label: "Devflow Architecture Brief",
+    description: "Inspect or regenerate the Core-derived architecture brief from the current graph and static-context snapshot. The brief is a view, never an agent-authored source of truth.",
+    parameters: z.object({
+      action: z.enum(["inspect", "render"]),
+      feature: z.string().min(1),
+    }),
+    approval: (args) => args.action === "render" ? "write" : "read",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      if (params.action === "inspect") {
+        return renderResult(
+          await runRuby(ctx.cwd, "workflow-orchestrator/scripts/architecture_brief.rb", ["inspect", "--feature", params.feature, "--json"]),
+          { action: params.action, feature: params.feature },
+        );
+      }
+      const inspected = parseJsonResult(
+        await runRuby(ctx.cwd, "workflow-orchestrator/scripts/architecture_brief.rb", ["inspect", "--feature", params.feature, "--json"]),
+      );
+      const currentRevision = typeof inspected?.brief_revision === "number" ? inspected.brief_revision : undefined;
+      if (currentRevision === undefined) {
+        return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: "Unable to read the current architecture brief revision for CAS." });
+      }
+      return renderResult(
+        await runRuby(ctx.cwd, "workflow-orchestrator/scripts/architecture_brief.rb", ["render", "--feature", params.feature, "--write", "--expected-brief-revision", String(currentRevision), "--json"]),
+        { action: params.action, feature: params.feature },
+      );
+    },
+  });
+
+  pi.registerTool({
+    name: "devflow_stale_check",
+    label: "Devflow Stale Check",
+    description: "Check field-level staleness of consumed evidence against the current snapshot.",
+    parameters: z.object({
+      consumedRevision: z.number().int().min(0),
+      evidencePaths: z.array(z.string().min(1)),
+    }),
+    approval: "read",
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      return renderResult(
+        await runRuby(ctx.cwd, "workflow-orchestrator/scripts/stale_check.rb", ["check", "--consumed-revision", String(params.consumedRevision), "--evidence-paths", JSON.stringify(params.evidencePaths), "--json"]),
+        {},
+      );
+    },
+  });
+
   pi.registerTool({
     name: "devflow_evidence",
     label: "Devflow Evidence Pack",
@@ -1254,7 +1614,10 @@ export default function devflowCore(pi: ExtensionAPI) {
         if (!pack || typeof pack !== "object" || Array.isArray(pack)) return ["pack must be an object"];
         const record = pack as Record<string, unknown>;
         const errors: string[] = [];
-        if (record.schemaVersion !== 1) errors.push("schemaVersion must equal 1");
+        const legacySchema = record.schemaVersion === 1;
+        if (record.schemaVersion !== 2 && record.schemaVersion !== 1) errors.push("schemaVersion must equal 2 (or 1 during compatibility period)");
+        if (record.origin !== "agent_claim") errors.push("origin must equal agent_claim");
+        if (Object.prototype.hasOwnProperty.call(record, "passed")) errors.push("agent claims cannot declare passed");
         for (const key of ["facts", "unknowns", "risks"]) {
           if (!Array.isArray(record[key])) errors.push(`${key} must be an array`);
         }
@@ -1272,7 +1635,7 @@ export default function devflowCore(pi: ExtensionAPI) {
         return { content: [{ type: "text" as const, text: JSON.stringify(parsed, null, 2) }], details: { action: params.action, path: path.relative(ctx.cwd, destination), errors } };
       }
       if (!params.pack) return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "pack is required for create" }, { action: params.action });
-      const pack = { schemaVersion: 1, taskId, createdAt: new Date().toISOString(), ...params.pack };
+      const pack = { schemaVersion: 2, taskId, createdAt: new Date().toISOString(), ...params.pack, origin: "agent_claim", evidenceClass: "non_gating_claim" };
       const errors = validatePack(pack);
       if (errors.length > 0) return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: errors.join("; ") }, { action: params.action, errors });
       await mkdir(root, { recursive: true });
@@ -1284,26 +1647,19 @@ export default function devflowCore(pi: ExtensionAPI) {
   pi.registerTool({
     name: "devflow_contract",
     label: "Devflow Execution Contract",
-    description: "Show or activate a user-confirmed, path-bounded execution contract. Only an active contract may authorize low-cost implementation agents.",
+    description: "Inspect or activate a Core-synthesized ExecutionContract v2. Paths, agents, checker IDs, and budgets are fixed by the packaged policy, never model input.",
     parameters: z.object({
-      action: z.enum(["status", "activate"]),
-      contractId: z.string().min(1).optional(),
+      action: z.enum(["status", "inspect", "activate"]),
       feature: z.string().min(1).optional(),
       step: z.string().min(1).optional(),
-      allowedPaths: z.array(z.string().min(1)).default([]),
-      allowedAgents: z.array(z.enum(["implementation-worker", "verification-runner"])).default([]),
-      acceptance: z.array(z.string().min(1)).default([]),
     }),
     approval: "write",
     async execute(_id, params, _signal, _onUpdate, ctx) {
       const input = params as {
-        action: "status" | "activate";
+        action: "status" | "inspect" | "activate";
         contractId?: string;
         feature?: string;
         step?: string;
-        allowedPaths: string[];
-        allowedAgents: string[];
-        acceptance: string[];
       };
       if (input.action === "status") {
         return {
@@ -1311,47 +1667,51 @@ export default function devflowCore(pi: ExtensionAPI) {
           details: { activeContract },
         };
       }
-      if (controlState.phase !== "planning") {
-        return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "Contracts may only be activated from the planning phase." });
-      }
-      if (!input.contractId || !input.feature || !input.step || input.allowedPaths.length === 0 || input.allowedAgents.length === 0 || input.acceptance.length === 0) {
-        return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "contractId, feature, step, allowedPaths, allowedAgents, and acceptance are required." });
-      }
-      let allowedPaths: string[];
-      try {
-        allowedPaths = input.allowedPaths.map(candidate => {
-          const relative = normalizedProjectPath(candidate, ctx.cwd);
-          if (!relative || relative.startsWith(".planning/")) throw new Error(`Invalid contract path: ${candidate}`);
-          return relative.replace(/\/$/, "");
-        });
-      } catch (error) {
-        return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: error instanceof Error ? error.message : String(error) });
-      }
+      if (!input.feature || !input.step) return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "feature and step are required; Core derives all control fields." });
+      const inspected = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/execution_contract.rb", ["inspect", "--feature", input.feature, "--step", input.step, "--json"]);
+      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: input.contractId,
-        feature: input.feature,
-        step: input.step,
-        allowedPaths: [...new Set(allowedPaths)],
-        allowedAgents: [...new Set(input.allowedAgents)],
-        acceptance: [...new Set(input.acceptance)],
-        onUnknown: "block_and_escalate",
+        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." });
+      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." });
       const confirmed = await ctx.ui.confirm(
         "激活 Devflow 执行合同",
         [
           `合同：${contract.contractId}`,
           `Feature：${contract.feature}`,
           `步骤：${contract.step}`,
+          `STATE revision：${contract.stateRevision ?? "未初始化"}`,
+          `图谱 revision：${contract.graphRevision ?? 0}`,
           `可写路径：${contract.allowedPaths.join(", ")}`,
           `允许 Agent：${contract.allowedAgents.join(", ")}`,
-          `验收：${contract.acceptance.join("；")}`,
+          `固定检查器：${contract.checkerIds.join(", ") || "无"}`,
+          `冻结哈希：${contract.frozenHash}`,
           "确认后低成本模型只能在以上范围执行；未知项必须阻塞升级。",
         ].join("\n"),
       );
       if (!confirmed) return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: "User declined execution contract activation." });
       try {
-        const destination = await persistContract(ctx.cwd, contract);
+        const createArgs = ["create", "--feature", input.feature, "--step", input.step, "--write", "--json"];
+        if (contract.stateRevision !== undefined) createArgs.push("--expected-state-revision", String(contract.stateRevision));
+        if (contract.graphRevision !== undefined) createArgs.push("--expected-graph-revision", String(contract.graphRevision));
+        const written = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/execution_contract.rb", createArgs);
+        if (!controlPlaneSucceeded(written)) return renderResult(written, { action: input.action });
+        const writtenPayload = parseJsonResult(written);
+        const destination = typeof writtenPayload?.path === "string" ? writtenPayload.path : ".planning/contracts/";
+        contract.contractPath = destination;
         activeContract = contract;
+        contractAgentCalls = 0;
         setControlState(ctx, executingState(`合同执行：${contract.contractId}`));
         return {
           content: [{ type: "text" as const, text: `Execution contract activated: ${destination}` }],
@@ -1483,6 +1843,17 @@ export default function devflowCore(pi: ExtensionAPI) {
         if (!params.step) {
           return renderResult({ ok: false, exitCode: 2, stdout: "", stderr: "step is required" });
         }
+        const snapshot = parseJsonResult(await runRuby(ctx.cwd, "workflow-orchestrator/scripts/inspect_state.rb", ["--json"]));
+        const feature = snapshot?.snapshot && typeof snapshot.snapshot === "object" ? (snapshot.snapshot as Record<string, unknown>).feature : undefined;
+        if (typeof feature === "string" && feature) {
+          const evidenceArgs = ["--feature", feature, "--step", params.step, "--write"];
+          if (activeContract?.feature === feature && activeContract.step === params.step && activeContract.contractPath) evidenceArgs.push("--contract", activeContract.contractPath);
+          const evidence = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/machine_evidence.rb", evidenceArgs);
+          const evidencePayload = parseJsonResult(evidence);
+          if (!controlPlaneSucceeded(evidence) || evidencePayload?.complete !== true) {
+            return renderResult({ ok: false, exitCode: 1, stdout: "", stderr: "machine evidence collection failed or required outputs are incomplete" }, { action: params.action, evidence: evidence.stdout });
+          }
+        }
         args.push("--complete-step", params.step);
       } else if (params.action === "confirm-checkpoint") {
         args.push("--confirm-checkpoint");