@guanlin4924/devflow-pi 0.1.15 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "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,73 @@ 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"]).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));
+      }
+      return renderResult(
+        await runRuby(ctx.cwd, "workflow-orchestrator/scripts/requirement_graph.rb", args),
+        { action: params.action, feature: params.feature },
+      );
+    },
+  });
+
   pi.registerTool({
     name: "devflow_evidence",
     label: "Devflow Evidence Pack",
@@ -1254,7 +1368,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 +1389,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 +1401,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 +1421,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 +1597,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");

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

@@ -0,0 +1,93 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# ExecutionContract v2 is synthesized from current Core truth. There is no
+# CLI input for agents, paths, checkers, or budgets: those are fixed policy.
+require "digest"
+require "json"
+require "optparse"
+require "yaml"
+require_relative "control_io"
+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 change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[api] },
+  "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] },
+  "change-plan" => { "checkers" => %w[requirement-graph-check slice-independence-check contract-coverage-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[acceptance] },
+  "execute" => { "checkers" => %w[change-impact-check], "agents" => ["implementation-worker"], "budget" => 1, "allowed_graph_delta" => %w[requirement rule boundary behavior] },
+  "verify" => { "checkers" => %w[acceptance-coverage-check change-impact-check], "agents" => ["verification-runner"], "budget" => 1, "allowed_graph_delta" => %w[acceptance] }
+}.freeze
+
+options = { feature: nil, step: nil, expected_state_revision: nil, expected_graph_revision: nil, write: false, json: false }
+command = ARGV.shift
+OptionParser.new do |o|
+  o.on("--feature NAME") { |v| options[:feature] = v }
+  o.on("--step ID") { |v| options[:step] = v }
+  o.on("--expected-state-revision N", Integer) { |v| options[:expected_state_revision] = v }
+  o.on("--expected-graph-revision N", Integer) { |v| options[:expected_graph_revision] = v }
+  o.on("--write") { options[:write] = true }
+  o.on("--json") { options[:json] = true }
+end.parse!
+
+def load_state(root)
+  document = File.read(File.join(root, ".planning/STATE.md"))
+  front = document.match(/\A---\n(.*?)\n---/m)&.[](1)
+  raise "STATE.md has no YAML front matter" unless front
+  YAML.safe_load(front, permitted_classes: [], aliases: false)
+end
+
+def interpolate(value, state)
+  value.gsub("{feature}", state.fetch("current_feature").to_s).gsub("{phase}", state.fetch("current_phase").to_s)
+end
+
+root = Dir.pwd
+lock = %w[create inspect].include?(command) ? DevflowControlIO.acquire_project_lock(root) : nil
+begin
+  raise ArgumentError, "command must be create or inspect" unless %w[create inspect].include?(command)
+  raise ArgumentError, "invalid feature" unless RequirementGraph.valid_feature?(options[:feature])
+  state = load_state(root)
+  raise ArgumentError, "state feature/step mismatch" unless state["current_feature"] == options[:feature] && state["current_step"] == options[:step]
+  workflow_relative = state.fetch("workflow_config")
+  workflow_path, = DevflowControlIO.resolve_control_path(root, workflow_relative, :workflow)
+  workflow_raw = File.read(workflow_path)
+  workflow = YAML.safe_load(workflow_raw, permitted_classes: [], aliases: false)
+  step = Array(workflow["steps"]).find { |item| item["id"] == options[:step] }
+  raise ArgumentError, "unknown workflow step" unless step
+  graph, = RequirementGraph.load_graph(root, options[:feature])
+  if command == "create"
+    raise ArgumentError, "stale state revision: expected #{options[:expected_state_revision]}, actual #{state["revision"]}" if options[:expected_state_revision] && state["revision"] != options[:expected_state_revision]
+    raise ArgumentError, "stale graph revision: expected #{options[:expected_graph_revision]}, actual #{graph["revision"]}" if options[:expected_graph_revision] && graph["revision"] != options[:expected_graph_revision]
+  end
+  policy = POLICY.fetch(options[:step], { "checkers" => [], "agents" => [], "budget" => 0 })
+  paths = (Array(step["outputs"]).map { |output| output["path"] } + [step.dig("meta_output", "path")]).compact.map { |value| interpolate(value, state) }.uniq
+  contract = {
+    "schema_version" => 2, "origin" => "core_execution_contract", "feature" => options[:feature], "step" => options[:step],
+    "state_revision" => state["revision"], "graph_revision" => graph["revision"], "workflow_path" => workflow_relative,
+    "workflow_fingerprint" => Digest::SHA256.hexdigest(workflow_raw), "manifest_id" => "devflow-core-execution-policy-v2",
+    "allowed_paths" => paths, "allowed_agents" => policy["agents"], "checker_ids" => policy["checkers"],
+    "allowed_tools" => %w[read grep find glob lsp search write edit apply_patch bash shell exec_command task],
+    "tool_budget" => policy["budget"], "acceptance" => Array(graph["nodes"]).select { |node| node["kind"] == "acceptance" }.map { |node| node["id"] },
+    "allowed_graph_delta" => Array(policy["allowed_graph_delta"]),
+    "on_unknown" => "block_and_escalate"
+  }
+  frozen = contract.merge("frozen_hash" => Digest::SHA256.hexdigest(JSON.generate(contract)))
+  contract_id = "EC-#{frozen["frozen_hash"][0, 16]}"
+  frozen["contract_id"] = contract_id
+  if command == "inspect"
+    result = { "ok" => true, "contract" => frozen }
+  else
+    raise ArgumentError, "--write is required" unless options[:write]
+    destination = File.join(root, ".planning/contracts", options[:feature], "#{contract_id}.json")
+    DevflowControlIO.atomic_write(destination, JSON.pretty_generate(frozen) + "\n")
+    audit = File.join(root, ".planning/contracts", options[:feature], "control-events.jsonl")
+    existing = File.exist?(audit) ? File.read(audit) : ""
+    DevflowControlIO.atomic_write(audit, existing + JSON.generate({ "event" => "execution_contract_frozen", "contract_id" => contract_id, "state_revision" => state["revision"], "graph_revision" => graph["revision"], "frozen_hash" => frozen["frozen_hash"] }) + "\n")
+    result = { "ok" => true, "path" => destination.sub("#{root}/", ""), "contract" => frozen }
+  end
+rescue StandardError => error
+  result = { "ok" => false, "reason" => "execution_contract_failed", "message" => error.message }
+ensure
+  DevflowControlIO.release_lock(lock)
+end
+puts JSON.pretty_generate(result)

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

@@ -94,7 +94,8 @@ pending_steps = if File.exist?(workflow_path)
 current_step = options[:step] || pending_steps.first || "requirement-triage"
 
 state = {
-  "state_schema_version" => 1,
+  "state_schema_version" => 2,
+  "governance_started_revision" => 0,
   "revision" => 0,
   "state_updated_at" => Date.today.to_s,
   "current_flow" => options[:flow],

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

@@ -0,0 +1,111 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Evidence Pack v2 is deliberately assembled from the current STATE/workflow
+# and canonical graph. Agent text is never used to decide completion.
+require "digest"
+require "json"
+require "optparse"
+require "yaml"
+require_relative "control_io"
+require_relative "requirement_graph"
+
+options = { feature: nil, step: nil, contract: nil, write: false, json: false }
+OptionParser.new do |o|
+  o.on("--feature NAME") { |v| options[:feature] = v }
+  o.on("--step ID") { |v| options[:step] = v }
+  o.on("--contract PATH") { |v| options[:contract] = v }
+  o.on("--write") { options[:write] = true }
+  o.on("--json") { options[:json] = true }
+end.parse!
+abort "feature, step and --write are required" unless options[:feature] && options[:step] && options[:write]
+abort "invalid feature" unless RequirementGraph.valid_feature?(options[:feature])
+
+def state_front_matter(root)
+  document = File.read(File.join(root, ".planning/STATE.md"))
+  front = document.match(/\A---\n(.*?)\n---/m)&.[](1)
+  raise "STATE.md has no YAML front matter" unless front
+  YAML.safe_load(front, permitted_classes: [], aliases: false)
+end
+
+def interpolate(path, state)
+  path.gsub("{feature}", state.fetch("current_feature", "").to_s).gsub("{phase}", state.fetch("current_phase", "").to_s)
+end
+
+def configured_checkers(workflow, step_id)
+  explicit = workflow.dig("governance", "step_checkers", step_id)
+  return Array(explicit) if explicit
+  case step_id
+  when "requirement-baseline" then %w[requirement-graph-check slice-independence-check acceptance-coverage-check change-impact-check]
+  when "api-contract" then %w[requirement-graph-check contract-coverage-check change-impact-check]
+  when "integration-verify", "change-plan" then %w[requirement-graph-check slice-independence-check contract-coverage-check change-impact-check]
+  when "verify" then %w[acceptance-coverage-check change-impact-check]
+  else []
+  end
+end
+
+root = Dir.pwd
+lock = DevflowControlIO.acquire_project_lock(root)
+begin
+  state = state_front_matter(root)
+  unless state["current_feature"] == options[:feature] && state["current_step"] == options[:step]
+    result = { "ok" => false, "reason" => "state_step_mismatch", "state_feature" => state["current_feature"], "state_step" => state["current_step"] }
+    puts JSON.pretty_generate(result)
+    exit 0
+  end
+  workflow_path, = DevflowControlIO.resolve_control_path(root, state.fetch("workflow_config"), :workflow)
+  workflow_raw = File.read(workflow_path)
+  workflow = YAML.safe_load(workflow_raw, permitted_classes: [], aliases: false)
+  step = Array(workflow["steps"]).find { |item| item["id"] == options[:step] }
+  raise "unknown workflow step" unless step
+
+  output_specs = Array(step["outputs"]).select { |item| item["required"] }
+  output_specs << step["meta_output"] if step["meta_output"].is_a?(Hash)
+  files = output_specs.map do |spec|
+    path = spec["path"]
+    next unless path
+    relative = interpolate(path, state)
+    absolute, = DevflowControlIO.resolve_control_path(root, relative, :artifact)
+    exists = File.file?(absolute)
+    { "path" => relative, "required" => true, "exists" => exists, "bytes" => exists ? File.size(absolute) : 0,
+      "sha256" => exists ? Digest::SHA256.file(absolute).hexdigest : nil }
+  end.compact
+
+  graph, = RequirementGraph.load_graph(root, options[:feature])
+  checkers = RequirementGraph.checker_results(graph)
+  selected = configured_checkers(workflow, options[:step])
+  gate = workflow.dig("governance", "requirement_graph_gate").to_s
+  enforced = gate == "enforced"
+  checker_results = selected.map do |id|
+    issues = checkers.fetch(id, ["unknown fixed checker: #{id}"])
+    { "id" => id, "origin" => "core_fixed_checker", "exit_code" => issues.empty? ? 0 : 1, "passed" => issues.empty?, "issues" => issues,
+      "counters" => { "issue_count" => issues.length } }
+  end
+  graph_missing = graph["revision"].zero? && !File.exist?(RequirementGraph.graph_path(root, options[:feature]).first)
+  checker_passed = !enforced || (!graph_missing && checker_results.all? { |item| item["passed"] })
+  contract_hash = nil
+  if options[:contract]
+    contract_path = File.expand_path(options[:contract], root)
+    raise "contract path escapes project" unless contract_path.start_with?("#{File.realpath(root)}#{File::SEPARATOR}") && File.file?(contract_path)
+    contract_hash = Digest::SHA256.file(contract_path).hexdigest
+  end
+  node_counts = Array(graph["nodes"]).group_by { |node| node["kind"] }.transform_values(&:length)
+  pack = {
+    "schema_version" => 2, "origin" => "core_machine", "feature" => options[:feature], "step" => options[:step],
+    "state_revision" => state["revision"], "graph_revision" => graph["revision"], "workflow_fingerprint" => Digest::SHA256.hexdigest(workflow_raw),
+    "contract_hash" => contract_hash, "files" => files, "checkers" => checker_results,
+    "counters" => { "required_file_count" => files.length, "existing_file_count" => files.count { |item| item["exists"] }, "nodes_by_kind" => node_counts,
+                    "stale_node_count" => Array(graph["stale"]).length, "stale_view_count" => Hash(graph["views"]).count { |_name, view| view["needs_recheck"] } },
+    "view_fingerprints" => Hash(graph["views"]).transform_values { |view| view.select { |key, _value| %w[fingerprint graph_revision state needs_recheck stale_fingerprint].include?(key) } },
+    "complete" => files.all? { |item| item["exists"] } && checker_passed,
+    "gate_mode" => gate.empty? ? "observe" : gate
+  }.compact
+  destination = File.join(root, ".planning/evidence", options[:feature], "#{options[:step]}.machine.json")
+  DevflowControlIO.atomic_write(destination, JSON.pretty_generate(pack) + "\n")
+  result = { "ok" => true, "path" => destination.sub("#{root}/", ""), "complete" => pack["complete"], "state_revision" => pack["state_revision"], "graph_revision" => pack["graph_revision"], "checkers" => checker_results }
+rescue StandardError => error
+  result = { "ok" => false, "reason" => "machine_evidence_failed", "message" => error.message }
+ensure
+  DevflowControlIO.release_lock(lock)
+end
+puts JSON.pretty_generate(result)