@guanlin4924/devflow-pi 0.1.37 → 0.1.39

package/README.md

@@ -11,7 +11,7 @@ Devflow Pi 是一个面向项目研发交付的独立 OMP 产品入口，内置
 安装与启动：
 
 ```bash
-npm install -g @guanlin4924/devflow-pi@0.1.37
+npm install -g @guanlin4924/devflow-pi@0.1.38
 cd /path/to/your-project
 devflow-pi init
 devflow-pi doctor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "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 { appendFile, 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";
@@ -864,6 +864,27 @@ export default function devflowCore(pi: ExtensionAPI) {
   let controlState: SessionControlState = initialControlState();
   let activeContract: ActiveExecutionContract | undefined;
   let contractAgentCalls = 0;
+  let projectRoot: string | undefined;
+
+  async function appendEngineEvidence(cwd: string | undefined, event: string, extra: Record<string, unknown> = {}) {
+    if (!cwd || !activeContract) return;
+    const feature = activeContract.feature;
+    const step = activeContract.step;
+    if (!/^[\p{L}\p{N}._-]{1,160}$/u.test(feature) || !/^[\p{L}\p{N}._-]{1,160}$/u.test(step)) return;
+    const directory = path.join(cwd, ".planning", "evidence", feature);
+    const destination = path.join(directory, `${step}.engine-events.jsonl`);
+    await mkdir(directory, { recursive: true });
+    await appendFile(destination, `${JSON.stringify({
+      schema_version: 1,
+      timestamp: new Date().toISOString(),
+      session_id: sessionId,
+      feature,
+      step,
+      event,
+      collector: "devflow-runtime/harness",
+      ...extra,
+    })}\n`, "utf8");
+  }
 
   function controlGuide(state: SessionControlState): string[] {
     const title = "Devflow 操作指引";
@@ -1285,6 +1306,22 @@ export default function devflowCore(pi: ExtensionAPI) {
     return { result, snapshot: parseJsonResult(result) };
   }
 
+  async function inspectWorkflowWithRegistryRecovery(cwd: string): Promise<{ result: ProcessResult; snapshot: Record<string, unknown> | null }> {
+    let inspected = await inspectWorkflow(cwd);
+    const errors = Array.isArray(inspected.snapshot?.state_validation && (inspected.snapshot.state_validation as Record<string, unknown>).errors)
+      ? (inspected.snapshot!.state_validation as Record<string, unknown>).errors as Array<Record<string, unknown>>
+      : [];
+    const onlyRegistryDrift = inspected.snapshot?.reason === "state_validation_failed" &&
+      errors.length > 0 && errors.every(error => error.code === "artifact_registry_revision_mismatch");
+    if (!onlyRegistryDrift) return inspected;
+    const synced = await runRuby(cwd, "workflow-orchestrator/scripts/sync_artifacts.rb", [
+      "--write", "--no-preserve", "--json",
+    ]);
+    if (!synced.ok) return inspected;
+    inspected = await inspectWorkflow(cwd);
+    return inspected;
+  }
+
   let activeWorkflowTurn = false;
   let pendingProjectInitialization: ProjectInitializationRequest | undefined;
   let pendingRollover: { snapshot: Record<string, unknown>; preparedRevision: number; rolloverId: string } | undefined;
@@ -1322,6 +1359,7 @@ export default function devflowCore(pi: ExtensionAPI) {
   pi.setLabel("Devflow Project Runtime");
 
   pi.on("session_start", async (_event, ctx) => {
+    projectRoot = ctx.cwd;
     sessionId = randomUUID();
     const result = await runHook(ctx.cwd, "start.py", {
       session_id: sessionId,
@@ -1362,7 +1400,7 @@ export default function devflowCore(pi: ExtensionAPI) {
       }
     }
     if (rolloverState && typeof rolloverState.revision === "number" && rollover?.status === "prepared" && typeof rollover.id === "string") {
-      const workflow = await inspectWorkflow(ctx.cwd);
+      const workflow = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
       const expectedStateRevision = typeof rollover.expected_state_revision === "number" ? rollover.expected_state_revision : undefined;
       if (workflow.result.ok && workflow.snapshot && expectedStateRevision !== undefined && expectedStateRevision + 1 === rolloverState.revision) {
         pendingRollover = { snapshot: workflow.snapshot, preparedRevision: rolloverState.revision, rolloverId: rollover.id };
@@ -1373,8 +1411,13 @@ export default function devflowCore(pi: ExtensionAPI) {
       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);
+      const after = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
       if (consumed.ok && after.result.ok && after.snapshot) {
+        if (after.snapshot.action === "blocked") {
+          setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "启动恢复校验失败" });
+          ctx.ui.notify(`会话已恢复，但工作流校验失败，未启动 AI：${String(after.snapshot.reason ?? "state validation failed")}`, "error");
+          return;
+        }
         setControlState(ctx, executingState("恢复已认领的干净会话"));
         await triggerWorkflow(after.snapshot, "approval");
       } else if (!consumed.ok) {
@@ -1421,13 +1464,23 @@ export default function devflowCore(pi: ExtensionAPI) {
     pendingRollover = undefined;
     activeContract = undefined;
     contractAgentCalls = 0;
+    const next = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
+    if (!next.result.ok || !next.snapshot || next.snapshot.action === "blocked") {
+      setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "启动恢复校验失败" });
+      ctx.ui.notify(`会话已切换，但工作流校验失败，未启动 AI：${String(next.snapshot?.reason ?? next.result.stderr ?? next.result.stdout ?? "state validation failed")}`, "error");
+      return;
+    }
     setControlState(ctx, executingState("在干净会话中执行下一工作流步骤"));
-    await triggerWorkflow(pending.snapshot, "approval");
+    await triggerWorkflow(next.snapshot, "approval");
   });
 
-  pi.on("before_agent_start", async event => ({
-    systemPrompt: [...event.systemPrompt, DEVFLOW_CHINESE_LANGUAGE_POLICY],
-  }));
+  pi.on("before_agent_start", async event => {
+    if (activeWorkflowTurn && activeContract) {
+      await appendEngineEvidence(projectRoot, "ai_runtime_initialized", { source: "runtime_before_agent_start" });
+      await appendEngineEvidence(projectRoot, "ai_invocation", { source: "runtime_before_agent_start" });
+    }
+    return { systemPrompt: [...event.systemPrompt, DEVFLOW_CHINESE_LANGUAGE_POLICY] };
+  });
 
   pi.on("agent_end", async (event, ctx) => {
     if (!activeWorkflowTurn || event.willContinue) return;
@@ -1444,7 +1497,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     if (controlState.intent === "requirement-draft" && controlState.phase === "planning") {
       const requirementDraft = event.text.trim();
       if (!requirementDraft) return { handled: true };
-      const inspected = await inspectWorkflow(ctx.cwd);
+      const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
       if (!inspected.result.ok || !inspected.snapshot) {
         ctx.ui.notify(`需求分诊启动失败：${inspected.result.stderr || inspected.result.stdout || "invalid inspector JSON"}`, "error");
         return { handled: true };
@@ -1472,7 +1525,7 @@ export default function devflowCore(pi: ExtensionAPI) {
     // fresh-session handoff. Keep approval useful in this recovery state, but
     // retry only the handoff; never repeat the already-persisted transition.
     if (controlState.phase === "blocked" && controlState.label === "会话轮换准备失败" && controlAction === "approve") {
-      const inspected = await inspectWorkflow(ctx.cwd);
+      const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
       if (!inspected.result.ok || !inspected.snapshot) {
         ctx.ui.notify(`会话交接重试失败：${inspected.result.stderr || inspected.result.stdout || "invalid inspector JSON"}`, "error");
         return { handled: true };
@@ -1498,7 +1551,7 @@ export default function devflowCore(pi: ExtensionAPI) {
         return { handled: true };
       }
       if (controlAction === "approve") {
-        const inspected = await inspectWorkflow(ctx.cwd);
+        const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
         if (!inspected.result.ok || !inspected.snapshot) {
           ctx.ui.notify(`审批处理失败：${inspected.result.stderr || inspected.result.stdout || "invalid inspector JSON"}`, "error");
           return { handled: true };
@@ -1516,14 +1569,14 @@ export default function devflowCore(pi: ExtensionAPI) {
           "--json",
           "--expected-revision",
           String(revision),
-          ...(checkpoint ? ["--confirm-checkpoint"] : ["--complete-step", stepId!]),
+          ...(checkpoint ? ["--confirm-checkpoint", "--runtime-confirmed"] : ["--complete-step", stepId!]),
         ]);
         if (!result.ok) {
           setControlState(ctx, { intent: "workflow-execute", phase: "blocked", label: "推进校验失败" });
           ctx.ui.notify(`未推进：${result.stderr || result.stdout}`, "error");
           return { handled: true };
         }
-        const after = await inspectWorkflow(ctx.cwd);
+        const after = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
         activeContract = undefined;
         contractAgentCalls = 0;
         if (!after.result.ok || !after.snapshot || after.snapshot.action === "workflow_complete") {
@@ -1664,6 +1717,18 @@ export default function devflowCore(pi: ExtensionAPI) {
           "Devflow 状态迁移只能由运行时在用户明确批准已展示的步骤或 checkpoint 后执行；LLM 不得自行推进。",
       };
     }
+    if (isUserConfirmedStepTransition && activeContract) {
+      const evidence = await runRuby(ctx.cwd, "workflow-orchestrator/scripts/machine_evidence.rb", [
+        "--feature", activeContract.feature, "--step", activeContract.step, "--write", "--json",
+      ]);
+      const evidencePayload = parseJsonResult(evidence);
+      if (!evidence.ok || !evidencePayload || evidencePayload.complete !== true) {
+        return {
+          block: true,
+          reason: `Devflow machine evidence is incomplete; collect independent runtime evidence before completing ${activeContract.step}.`,
+        };
+      }
+    }
     if (
       !toolName.startsWith("devflow_") &&
       ["write", "edit", "apply_patch", "notebook_edit", "bash", "shell", "exec_command"].includes(toolName) &&
@@ -1740,6 +1805,12 @@ export default function devflowCore(pi: ExtensionAPI) {
 
   pi.on("tool_result", async (event, ctx) => {
     if (event.isError) return;
+    if (activeWorkflowTurn && activeContract) {
+      await appendEngineEvidence(ctx.cwd, "engine_dispatched", {
+        engine: event.toolName,
+        ai_capable: event.toolName === "task" || event.toolName.toLowerCase().includes("ai") || event.toolName.toLowerCase().includes("midscene"),
+      });
+    }
     await runHook(ctx.cwd, "post_tool.py", {
       session_id: sessionId,
       cwd: ctx.cwd,
@@ -1840,7 +1911,11 @@ export default function devflowCore(pi: ExtensionAPI) {
             stderr: "TC candidates are accepted only during the active acceptance-test-design contract.",
           });
         }
-        args.push("--write", "--expected-revision", String(params.expectedRevision), "--delta-json", JSON.stringify(params.delta));
+        args.push("--expected-revision", String(params.expectedRevision), "--delta-json", JSON.stringify(params.delta));
+        // `write` is an explicit dry-run switch. Omit it only when the caller
+        // explicitly asks for a preview; the normal approved proposal remains
+        // a Core-owned write.
+        if (params.write !== false) args.push("--write");
         if (activeContract?.allowedGraphDelta?.length) args.push("--allowed-kinds", activeContract.allowedGraphDelta.join(","));
       }
       if (params.action === "confirm") {
@@ -2513,7 +2588,7 @@ export default function devflowCore(pi: ExtensionAPI) {
         }
         args.push("--checkpoint-decision", params.decision);
       } else if (params.action === "cancel-feature") {
-        const inspected = await inspectWorkflow(ctx.cwd);
+        const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
         const snapshot = inspected.snapshot;
         const feature = typeof snapshot?.current_feature === "string" ? snapshot.current_feature : "当前需求";
         const revision = typeof snapshot?.revision === "number" ? snapshot.revision : undefined;
@@ -2641,7 +2716,7 @@ export default function devflowCore(pi: ExtensionAPI) {
         return;
       }
       if (trimmed === "explain-state") {
-        const inspected = await inspectWorkflow(ctx.cwd);
+        const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
         ctx.ui.notify(
           inspected.result.ok ? explainWorkflowSnapshot(inspected.snapshot) : `状态读取失败：${inspected.result.stderr || inspected.result.stdout}`,
           inspected.result.ok ? "info" : "error",
@@ -2650,7 +2725,7 @@ export default function devflowCore(pi: ExtensionAPI) {
         return;
       }
       if (trimmed === "recover") {
-        const inspected = await inspectWorkflow(ctx.cwd);
+        const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
         const plan = inspected.snapshot?.recovery_plan as Record<string, unknown> | undefined;
         const revision = plan?.expected_revision;
         if (!inspected.result.ok || !plan || plan.classification !== "safe_repairable" || typeof revision !== "number") {
@@ -2689,7 +2764,7 @@ export default function devflowCore(pi: ExtensionAPI) {
         return;
       }
       if (trimmed === "abandon" || trimmed.startsWith("abandon ") || trimmed === "cancel" || trimmed.startsWith("cancel ")) {
-        const inspected = await inspectWorkflow(ctx.cwd);
+        const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
         const snapshot = inspected.snapshot;
         const revision = typeof snapshot?.revision === "number" ? snapshot.revision : undefined;
         const feature = typeof snapshot?.current_feature === "string" ? snapshot.current_feature : undefined;
@@ -2758,7 +2833,7 @@ export default function devflowCore(pi: ExtensionAPI) {
           ctx.ui.notify(formatDoctorReport(report).slice(0, 10000), "error");
           return;
         }
-        const inspected = await inspectWorkflow(ctx.cwd);
+        const inspected = await inspectWorkflowWithRegistryRecovery(ctx.cwd);
         if (!inspected.result.ok || !inspected.snapshot) {
           ctx.ui.notify(
             `Devflow resume failed: ${inspected.result.stderr || inspected.result.stdout || "invalid inspector JSON"}`,

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

@@ -12,6 +12,7 @@ require_relative "control_io"
 require_relative "validate_state"
 require_relative "phase_ownership"
 require_relative "requirement_graph"
+require_relative "gate_runtime"
 
 options = {
   state: nil,
@@ -24,7 +25,8 @@ options = {
   cancel: false,
   cancel_reason: nil,
   expected_revision: nil,
-  json: false
+  json: false,
+  runtime_confirmed: false
 }
 
 OptionParser.new do |opts|
@@ -40,6 +42,7 @@ OptionParser.new do |opts|
   opts.on("--cancel-reason REASON", "Record why the active feature was cancelled") { |reason| options[:cancel_reason] = reason }
   opts.on("--expected-revision REVISION", Integer, "Reject a stale write unless STATE.md has this revision") { |value| options[:expected_revision] = value }
   opts.on("--json", "Print JSON output") { options[:json] = true }
+  opts.on("--runtime-confirmed", "Internal runtime authorization for checkpoint confirmation") { options[:runtime_confirmed] = true }
 end.parse!
 
 root = Dir.pwd
@@ -64,6 +67,63 @@ def load_workflow(root, state)
   [relative, load_yaml_file(path)]
 end
 
+def gate_contract_enabled?(workflow)
+  workflow.dig("governance", "gate_contract_version").to_i >= 3
+end
+
+# Build the runtime view from the existing workflow declaration.  This keeps
+# governance.step_checkers as the single checker namespace and avoids creating
+# a second hand-maintained per-step transition table.
+def transition_gate_contract(workflow, step)
+  checkpoints = workflow["checkpoints"] || {}
+  checkpoint_id = step["checkpoint"]
+  checkpoint = checkpoint_id && checkpoints[checkpoint_id]
+  track_names = Array(workflow["parallel_windows"]).flat_map do |window|
+    next [] unless window.is_a?(Hash) && window["branches"].is_a?(Hash)
+    window["branches"].keys.map { |name| name.to_s.sub(/\Atrack_/, "").upcase }
+  end
+  allowed_tracks = track_names.empty? ? ["main"] : ["main", *track_names]
+  reentries = (workflow["failure_branches"] || {}).each_with_object([]) do |(source_step, branch), entries|
+    next unless branch.is_a?(Hash) && branch["resume_after_success"].is_a?(Hash)
+    entries << { "source" => { "flow" => branch["workflow"], "step" => source_step }, "target" => branch["resume_after_success"], "requires_checkpoint_reconfirm" => true }
+  end
+  {
+    "gate_id" => "#{step.fetch("id")}-gate-v1",
+    "step_id" => step.fetch("id"),
+    "topology" => {
+      "allowed_tracks" => allowed_tracks,
+      "allowed_predecessors" => Array(step["depends_on"]),
+      "allowed_reentry" => reentries,
+      "checkpoint" => checkpoint && checkpoint.merge("id" => checkpoint_id)
+    },
+    "entry" => { "required_inputs" => Array(step["inputs"]) },
+    "outputs" => { "required" => Array(step["outputs"]).select { |output| output["required"] } },
+    "quality" => { "checker_ids" => Array(workflow.dig("governance", "step_checkers", step["id"])) },
+    "concurrency" => { "project_lock" => "required", "optimistic_revision" => "required", "registry_view" => "candidate_overlay" },
+    "recovery" => { "allowed" => ["sync_artifacts", "repair_outputs"], "max_attempts" => 2 }
+  }
+end
+
+def transition_gate_preflight(workflow, state, step, current_revision, checkpoint_authorized = false, transition_kind = nil)
+  return nil unless gate_contract_enabled?(workflow)
+
+  contract = transition_gate_contract(workflow, step)
+  track = state["active_track"].to_s
+  track = "main" unless %w[A B].include?(track)
+  GateRuntime.evaluate(
+    contract: contract,
+    workflow_state: state,
+    current_revision: current_revision,
+    expected_revision: current_revision,
+    track: track,
+    source: "advance_state",
+    root: Dir.pwd,
+    check_outputs: step["id"].to_s == state["current_step"].to_s,
+    transition_kind: transition_kind,
+    checkpoint_authorized: checkpoint_authorized
+  )
+end
+
 def interpolate_path(path, state)
   path
     .gsub("{feature}", state.fetch("current_feature", "").to_s)
@@ -516,6 +576,39 @@ result =
         )
       end
 
+      # GateRuntime is a read-only boundary check.  It runs while the project
+      # lock is held and before any candidate state mutation; the existing
+      # validator and advance_state CAS remain the final write guard.
+      if result.nil? && gate_contract_enabled?(workflow) &&
+         !%w[prepared claimed].include?(state.dig("rollover", "status")) &&
+         (options[:complete_step] || options[:confirm_checkpoint] || options[:enter_failure_branch] || options[:exit_failure_branch])
+        target_step_id = if options[:complete_step]
+                           options[:complete_step]
+                         elsif options[:confirm_checkpoint]
+                           state["current_step"]
+                         else
+                           state["current_step"]
+                         end
+        target_step = step_by_id[target_step_id]
+        if target_step.nil?
+          result = fail_result("gate_target_step_unknown", "step" => target_step_id)
+        elsif options[:complete_step] && state["current_step"].to_s != target_step_id.to_s
+          result = fail_result("gate_current_step_mismatch", "current_step" => state["current_step"], "requested_step" => target_step_id)
+        else
+          transition_kind = if options[:confirm_checkpoint]
+                              "confirm_checkpoint"
+                            elsif options[:enter_failure_branch]
+                              "enter_failure_branch"
+                            elsif options[:exit_failure_branch]
+                              "exit_failure_branch"
+                            end
+          gate_result = transition_gate_preflight(workflow, state, target_step, current_revision, options[:runtime_confirmed], transition_kind)
+          if gate_result && gate_result["verdict"] != "allow"
+            result = fail_result("gate_boundary_rejected", "gate" => gate_result)
+          end
+        end
+      end
+
       if result.nil? && options[:checkpoint_decision]
         state["checkpoint_decision"] = options[:checkpoint_decision]
         changed = true

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

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+module CheckerRegistry
+  DECLARED = %w[
+    requirement-graph-check slice-independence-check acceptance-coverage-check
+    api-test-schema-check contract-coverage-check api-test-matrix-check
+    test-coverage-check test-obligation-check acceptance-test-results-check
+    change-impact-check tdd-evidence-check test-task-binding-check
+  ].freeze
+  EMBEDDED = %w[requirement-coverage-check source-authority-check traceability-check].freeze
+
+  module_function
+
+  def known?(id)
+    (DECLARED + EMBEDDED).include?(id.to_s)
+  end
+
+  def kind(id)
+    return "declared" if DECLARED.include?(id.to_s)
+    return "embedded" if EMBEDDED.include?(id.to_s)
+    nil
+  end
+
+  def validate!(ids)
+    unknown = Array(ids).map(&:to_s).reject { |id| known?(id) }
+    raise ArgumentError, "unknown checker id(s): #{unknown.join(", ")}" unless unknown.empty?
+    true
+  end
+end

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

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "yaml"
+
+module GateContract
+  module_function
+
+  def load(path)
+    value = YAML.safe_load(File.read(path), permitted_classes: [], aliases: false)
+    validate!(value)
+    value
+  rescue Psych::Exception => e
+    raise ArgumentError, "invalid GateContract YAML: #{e.message}"
+  end
+
+  def validate!(contract)
+    raise ArgumentError, "GateContract must be a mapping" unless contract.is_a?(Hash)
+    %w[gate_id step_id topology entry outputs quality recovery].each do |field|
+      raise ArgumentError, "GateContract missing #{field}" unless contract.key?(field)
+    end
+    topology = contract["topology"]
+    raise ArgumentError, "topology must be a mapping" unless topology.is_a?(Hash)
+    %w[allowed_tracks allowed_predecessors].each do |field|
+      raise ArgumentError, "#{field} must be an array" unless topology[field].is_a?(Array)
+    end
+    raise ArgumentError, "allowed_reentry must be an array" unless topology["allowed_reentry"].is_a?(Array)
+    validate_reentries!(topology["allowed_reentry"])
+    checkpoint = topology["checkpoint"]
+    validate_checkpoint!(checkpoint) unless checkpoint.nil?
+    concurrency = contract["concurrency"]
+    raise ArgumentError, "concurrency must be a mapping" unless concurrency.is_a?(Hash)
+    %w[project_lock optimistic_revision registry_view].each do |field|
+      raise ArgumentError, "concurrency missing #{field}" unless concurrency.key?(field)
+    end
+    raise ArgumentError, "project_lock must be required" unless concurrency["project_lock"].to_s == "required"
+    raise ArgumentError, "optimistic_revision must be required" unless concurrency["optimistic_revision"].to_s == "required"
+    raise ArgumentError, "registry_view must be candidate_overlay" unless concurrency["registry_view"].to_s == "candidate_overlay"
+    recovery = contract["recovery"]
+    raise ArgumentError, "recovery must be a mapping" unless recovery.is_a?(Hash)
+    forbidden = Array(recovery["allowed"]).select { |action| action.to_s.start_with?("reenter_") || %w[confirm_checkpoint transition].include?(action.to_s) }
+    raise ArgumentError, "state transition cannot be an automatic recovery action: #{forbidden.join(", ")}" unless forbidden.empty?
+    contract
+  end
+
+  def validate_reentries!(entries)
+    entries.each do |entry|
+      raise ArgumentError, "reentry must be a mapping" unless entry.is_a?(Hash)
+      source = entry["source"]
+      target = entry["target"]
+      raise ArgumentError, "reentry source/target are required" unless source.is_a?(Hash) && target.is_a?(Hash)
+      %w[flow step].each { |field| raise ArgumentError, "reentry target missing #{field}" if target[field].to_s.empty? }
+      raise ArgumentError, "reentry must declare checkpoint reconfirmation" unless entry.key?("requires_checkpoint_reconfirm")
+    end
+  end
+
+  def validate_checkpoint!(checkpoint)
+    raise ArgumentError, "checkpoint must be a mapping" unless checkpoint.is_a?(Hash)
+    %w[id producing_step required_outputs required_meta_output prompt confirm_options skip_policy resume_behavior].each do |field|
+      raise ArgumentError, "checkpoint missing #{field}" unless checkpoint.key?(field)
+    end
+    raise ArgumentError, "checkpoint confirm_options must be an array" unless checkpoint["confirm_options"].is_a?(Array)
+  end
+end

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

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+module GateResult
+  VERDICTS = %w[allow allow_with_warning await_user waiting_external_input block_unsafe].freeze
+  CONTROL_PLANE_ERROR = "control_plane_error"
+
+  module_function
+
+  def build(verdict:, gate_id:, step_id:, errors: [], warnings: [], recovery: nil, evidence: {}, revisions: {})
+    valid = VERDICTS.include?(verdict.to_s) || verdict.to_s == CONTROL_PLANE_ERROR
+    raise ArgumentError, "invalid gate verdict: #{verdict}" unless valid
+
+    {
+      "ok" => %w[allow allow_with_warning].include?(verdict.to_s),
+      "verdict" => verdict.to_s,
+      "gate_id" => gate_id.to_s,
+      "step_id" => step_id.to_s,
+      "errors" => Array(errors),
+      "warnings" => Array(warnings),
+      "recovery" => recovery,
+      "evidence" => evidence.is_a?(Hash) ? evidence : {},
+      "revisions" => revisions.is_a?(Hash) ? revisions : {}
+    }
+  end
+
+  def allow(gate_id:, step_id:, **kwargs)
+    build(verdict: "allow", gate_id: gate_id, step_id: step_id, **kwargs)
+  end
+
+  def await_user(gate_id:, step_id:, recovery: nil, **kwargs)
+    build(verdict: "await_user", gate_id: gate_id, step_id: step_id, recovery: recovery, **kwargs)
+  end
+
+  def block(gate_id:, step_id:, code:, message:, recovery: nil, details: {}, **kwargs)
+    error = { "code" => code.to_s, "message" => message.to_s }
+    error.merge!(details) if details.is_a?(Hash)
+    build(verdict: "block_unsafe", gate_id: gate_id, step_id: step_id, errors: [error], recovery: recovery, **kwargs)
+  end
+end

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

@@ -0,0 +1,88 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "gate_result"
+require_relative "gate_contract"
+require_relative "checker_registry"
+
+module GateRuntime
+  WORKFLOW_STATUSES = %w[in_progress waiting_checkpoint completed blocked failed cancelled remediation].freeze
+
+  module_function
+
+  def validate_contract!(contract)
+    GateContract.validate!(contract)
+    CheckerRegistry.validate!(Array(contract.dig("quality", "checker_ids")))
+    contract
+  end
+
+  def evaluate(contract:, workflow_state:, current_revision:, expected_revision:, track: nil, source: "harness", evidence: {}, root: nil, check_outputs: false, transition_kind: nil, checkpoint_authorized: false)
+    validate_contract!(contract)
+    gate_id = contract.fetch("gate_id")
+    step_id = contract.fetch("step_id")
+    base = { gate_id: gate_id, step_id: step_id, evidence: evidence.merge("collector" => source), revisions: { "state" => current_revision } }
+    return GateResult.block(**base, code: "REVISION_CONFLICT", message: "current revision does not match expected revision", recovery: { "kind" => "reinspect", "expected_revision" => expected_revision }) unless expected_revision.nil? || current_revision.to_i == expected_revision.to_i
+    unless WORKFLOW_STATUSES.include?(workflow_state["status"].to_s)
+      return GateResult.block(**base, code: "WORKFLOW_STATUS_INVALID", message: "workflow status is not recognized")
+    end
+    unless %w[confirm_checkpoint enter_failure_branch exit_failure_branch].include?(transition_kind)
+      allowed_tracks = Array(contract.dig("topology", "allowed_tracks"))
+      if track && !allowed_tracks.empty? && !allowed_tracks.include?(track)
+        return GateResult.block(**base, code: "TRACK_SCOPE_VIOLATION", message: "current track is not allowed by GateContract", recovery: { "kind" => "registered_reentry" })
+      end
+      allowed_predecessors = Array(contract.dig("topology", "allowed_predecessors"))
+      previous = workflow_state["last_completed_step"] || workflow_state["previous_step"]
+      if previous && !allowed_predecessors.empty? && !allowed_predecessors.include?(previous)
+        return GateResult.block(**base, code: "STEP_PREDECESSOR_INVALID", message: "previous step is not allowed by GateContract")
+      end
+      if root
+        missing = required_paths(contract.dig("entry", "required_inputs"), root, workflow_state)
+        return GateResult.block(**base, code: "REQUIRED_INPUT_MISSING", message: "required gate input is missing", details: { "missing" => missing }) unless missing.empty?
+        if check_outputs
+          missing_outputs = required_paths(contract.dig("outputs", "required"), root, workflow_state)
+          return GateResult.block(**base, code: "REQUIRED_OUTPUT_MISSING", message: "required step output is missing", details: { "missing" => missing_outputs }) unless missing_outputs.empty?
+        end
+      end
+    end
+    if transition_kind == "confirm_checkpoint"
+      checkpoint_id = workflow_state["checkpoint"].to_s
+      checkpoint = contract.dig("topology", "checkpoint")
+      checkpoint_matches = checkpoint.is_a?(Hash) && checkpoint["id"].to_s == checkpoint_id
+      unless workflow_state["status"].to_s == "waiting_checkpoint" && checkpoint_matches && checkpoint_authorized
+      return GateResult.block(**base, code: "CHECKPOINT_NOT_AUTHORIZED", message: "checkpoint confirmation is not authorized by the runtime", details: { "checkpoint" => checkpoint_id })
+      end
+      unless workflow_state["completed_steps"].to_a.include?(checkpoint["producing_step"].to_s)
+        return GateResult.block(**base, code: "CHECKPOINT_PRODUCER_INCOMPLETE", message: "checkpoint producing step is not completed", details: { "checkpoint" => checkpoint_id })
+      end
+    end
+    GateResult.allow(**base)
+  rescue KeyError, ArgumentError => e
+    GateResult.block(gate_id: contract.is_a?(Hash) ? contract["gate_id"] : "unknown", step_id: contract.is_a?(Hash) ? contract["step_id"] : "unknown", code: "GATE_CONTRACT_INVALID", message: e.message)
+  end
+
+  def run_checker(contract:, workflow_state:, current_revision:, expected_revision:, checker:, **kwargs)
+    boundary = evaluate(contract: contract, workflow_state: workflow_state, current_revision: current_revision, expected_revision: expected_revision, **kwargs)
+    return boundary unless boundary["verdict"] == "allow"
+    result = checker.call
+    raise ArgumentError, "checker must return a GateResult hash" unless result.is_a?(Hash) && result["verdict"]
+    result.merge(
+      "gate_id" => result["gate_id"] || boundary["gate_id"],
+      "step_id" => result["step_id"] || boundary["step_id"],
+      "evidence" => boundary.fetch("evidence", {}).merge(result.fetch("evidence", {})),
+      "revisions" => boundary.fetch("revisions", {}).merge(result.fetch("revisions", {}))
+    )
+  end
+
+  def required_paths(entries, root, state)
+    Array(entries).each_with_object([]) do |entry, missing|
+      raw = entry.is_a?(Hash) ? entry["path"] : entry
+      next if raw.to_s.empty?
+      relative = raw.to_s.gsub("{feature}", state.fetch("current_feature", "").to_s).gsub("{phase}", state.fetch("current_phase", "").to_s)
+      absolute = File.expand_path(relative, root)
+      root_real = File.realpath(root)
+      actual = File.exist?(absolute) ? File.realpath(absolute) : absolute
+      next if actual.start_with?("#{root_real}#{File::SEPARATOR}") && File.exist?(actual)
+      missing << relative
+    end
+  end
+end