@guanlin4924/devflow-pi 0.1.38 → 0.1.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.38",
+  "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 操作指引";
@@ -1338,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,
@@ -1452,9 +1474,13 @@ export default function devflowCore(pi: ExtensionAPI) {
     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;
@@ -1543,7 +1569,7 @@ 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: "推进校验失败" });
@@ -1691,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) &&
@@ -1767,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,
@@ -1867,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") {

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

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

@@ -10,6 +10,7 @@ require "optparse"
 require "yaml"
 require_relative "control_io"
 require_relative "requirement_graph"
+require_relative "checker_registry"
 
 options = { feature: nil, step: nil, contract: nil, write: false, json: false }
 OptionParser.new do |o|
@@ -33,6 +34,69 @@ def interpolate(path, state)
   path.gsub("{feature}", state.fetch("current_feature", "").to_s).gsub("{phase}", state.fetch("current_phase", "").to_s)
 end
 
+def file_evidence(root, relative)
+  absolute, = DevflowControlIO.resolve_control_path(root, relative, :artifact)
+  return { "path" => relative, "exists" => false } unless File.file?(absolute)
+
+  { "path" => relative, "exists" => true, "sha256" => Digest::SHA256.file(absolute).hexdigest, "bytes" => File.size(absolute) }
+end
+
+def independent_evidence(root, feature, step, state, workflow, graph, files, checker_results)
+  source_nodes = Array(graph["nodes"]).select { |node| node.is_a?(Hash) && node["kind"] == "source" }
+  authority = source_nodes.map do |node|
+    evidence = node["evidence"].is_a?(Hash) ? node["evidence"] : {}
+    {
+      "source_id" => node["id"], "authority" => evidence["authority"], "path" => evidence["path"] || evidence["ref"],
+      "fingerprint" => evidence["sha256"] || evidence["source_document_fingerprint"]
+    }.compact
+  end
+
+  # The harness may publish an append-only event log beside the machine pack.
+  # Absence is represented as unavailable, never as false/zero, so the pack
+  # cannot manufacture proof that an engine did not invoke AI.
+  event_path = File.join(".planning", "evidence", feature, "#{step}.engine-events.jsonl")
+  event_absolute, = DevflowControlIO.resolve_control_path(root, event_path, :artifact)
+  events = if File.file?(event_absolute)
+             File.foreach(event_absolute).first(10_000).each_with_object([]) do |line, parsed|
+               next if line.strip.empty?
+
+               begin
+                 parsed << JSON.parse(line)
+               rescue JSON::ParserError
+                 # A malformed event is not evidence of a clean execution;
+                 # retain the valid events and let the collector expose the
+                 # observed subset without inventing a zero count.
+               end
+             end
+           else
+             nil
+           end
+  ai_events = events ? events.select { |event| %w[ai_runtime_initialized ai_invocation].include?(event["event"]) } : []
+
+  {
+    "collector" => "core.machine_evidence/v1",
+    "state" => { "revision" => state["revision"], "step" => step },
+    "source_authority" => { "status" => authority.empty? ? "unavailable" : "observed", "sources" => authority },
+    "candidate_binding" => {
+      "status" => "observed",
+      "graph_revision" => graph["revision"],
+      "test_case_ids" => Array(graph["nodes"]).each_with_object([]) { |node, ids| ids << node["id"] if node.is_a?(Hash) && node["kind"] == "test_case" }
+    },
+    "structured_execution" => {
+      "status" => "observed",
+      "required_files" => files,
+      "checker_ids" => checker_results.map { |item| item["id"] }
+    },
+    "engine_evidence" => {
+      "collector" => events ? "harness.engine-events/v1" : "unavailable",
+      "event_log" => event_path,
+      "ai_runtime_initialized" => events ? ai_events.any? { |event| event["event"] == "ai_runtime_initialized" } : nil,
+      "ai_invocation_count" => events ? ai_events.count { |event| event["event"] == "ai_invocation" } : nil,
+      "evidence_status" => events ? "observed" : "unavailable"
+    }
+  }
+end
+
 def configured_checkers(workflow, step_id)
   explicit = workflow.dig("governance", "step_checkers", step_id)
   checkers = if explicit
@@ -98,7 +162,7 @@ begin
   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
+    exit 1
   end
   workflow_path, = DevflowControlIO.resolve_control_path(root, state.fetch("workflow_config"), :workflow)
   workflow_raw = File.read(workflow_path)
@@ -121,6 +185,7 @@ begin
   graph, = RequirementGraph.load_graph(root, options[:feature])
   checkers = RequirementGraph.checker_results(graph)
   selected = configured_checkers(workflow, options[:step])
+  CheckerRegistry.validate!(selected)
   gate = workflow.dig("governance", "requirement_graph_gate").to_s
   enforced = gate == "enforced"
   checker_results = selected.map do |id|
@@ -133,6 +198,7 @@ begin
   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"] })
+  engine_evidence_gate = (step["engine_evidence_gate"] || workflow.dig("governance", "engine_evidence_gate")).to_s
   contract_hash = nil
   if options[:contract]
     contract_path = File.expand_path(options[:contract], root)
@@ -140,14 +206,18 @@ begin
     contract_hash = Digest::SHA256.file(contract_path).hexdigest
   end
   node_counts = Array(graph["nodes"]).group_by { |node| node["kind"] }.transform_values(&:length)
+  independent = independent_evidence(root, options[:feature], options[:step], state, workflow, graph, files, checker_results)
+  engine_evidence_complete = independent.dig("engine_evidence", "evidence_status") == "observed"
+  evidence_complete = engine_evidence_gate != "enforced" || engine_evidence_complete
   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,
+    "contract_hash" => contract_hash, "files" => files, "checkers" => checker_results, "evidence" => independent,
     "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,
+    "complete" => files.all? { |item| item["exists"] } && checker_passed && evidence_complete,
+    "evidence_complete" => evidence_complete,
     "gate_mode" => gate.empty? ? "observe" : gate
   }.compact
   destination = File.join(root, ".planning/evidence", options[:feature], "#{options[:step]}.machine.json")

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

@@ -0,0 +1,173 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Canonical wayfinder quality checker.  It validates references and structured
+# coverage only; AI-provided equivalence labels are never trusted.
+require "digest"
+require "json"
+require "optparse"
+require "yaml"
+require_relative "requirement_graph"
+
+module RequirementCoverage
+  module_function
+
+  def validate(root:, feature:)
+    directory = RequirementGraph.feature_dir(root, feature)
+    errors = []
+    source = load(File.join(directory, "source_units.yaml"), errors, "SOURCE_UNITS_MISSING")
+    coverage = load(File.join(directory, "coverage.yaml"), errors, "COVERAGE_ARTIFACT_MISSING")
+    return result(errors, {}, {}) unless source && coverage
+    validate_source(source, errors)
+    validate_coverage(coverage, errors)
+    return result(errors, {}, {}) unless errors.empty?
+
+    units = Array(source["units"])
+    unit_by_id = units.to_h { |unit| [unit["stable_unit_id"].to_s, unit] }
+    assertions = units.flat_map { |unit| Array(unit["required_assertions"]) }
+    assertion_by_id = assertions.to_h { |assertion| [assertion["assertion_id"].to_s, assertion] }
+    claims = Array(coverage["claims"])
+    claim_ids = {}
+    covered = {}
+    uncertain = {}
+    approval_required = {}
+
+    claims.each do |claim|
+      id = claim["claim_id"].to_s
+      duplicate(errors, claim_ids, id, "DUPLICATE_CLAIM_ID")
+      unit_id = claim["source_unit_id"].to_s
+      unless unit_by_id.key?(unit_id)
+        add(errors, "CLAIM_WITHOUT_UNIT", "claim references an unknown source unit", claim_id: id)
+        next
+      end
+      Array(claim["assertion_ids"]).each do |assertion_id|
+        assertion = assertion_by_id[assertion_id.to_s]
+        unless assertion && assertion["source_unit_id"].to_s == unit_id
+          add(errors, "ASSERTION_REF_NOT_FOUND", "claim references an unknown assertion", claim_id: id, assertion_id: assertion_id)
+          next
+        end
+        relation = compare(assertion, claim["inherited_constraints"])
+        case relation
+        when "equivalent" then covered[assertion_id.to_s] = true
+        when "uncertain" then uncertain[assertion_id.to_s] = true
+        when "scope_widened", "constraint_tightened"
+          approval = claim["approval"]
+          expected_content_fingerprint = sha(canonical(claim["inherited_constraints"]))
+          if approval.is_a?(Hash) && approval["approval_id"].to_s != "" && approval["claim_id"].to_s == id && approval["assertion_id"].to_s == assertion_id.to_s && approval["relation"].to_s == relation && approval["content_fingerprint"].to_s == expected_content_fingerprint && approval["source_document_fingerprint"].to_s == source["source_document_fingerprint"].to_s
+            covered[assertion_id.to_s] = true
+          else
+            approval_required[assertion_id.to_s] = true
+          end
+        else
+          add(errors, relation == "under_coverage" ? "ASSERTION_UNCOVERED" : "CONTRADICTORY_CLAIM", "claim is not an equivalent coverage", claim_id: id, assertion_id: assertion_id, relation: relation)
+        end
+      end
+    end
+
+    disposition_by_id = {}
+    Array(coverage["units"]).each do |entry|
+      unit_id = entry["unit_id"].to_s
+      duplicate(errors, disposition_by_id, unit_id, "DUPLICATE_COVERAGE")
+      add(errors, "UNIT_REF_NOT_FOUND", "coverage references an unknown unit", unit_id: unit_id) unless unit_by_id.key?(unit_id)
+      disposition = entry["disposition"]
+      unless disposition.is_a?(Hash) && %w[active deferred out_of_scope merged].include?(disposition["kind"].to_s)
+        add(errors, "DISPOSITION_SCHEMA_INVALID", "invalid unit disposition", unit_id: unit_id)
+        next
+      end
+      if %w[deferred out_of_scope].include?(disposition["kind"].to_s)
+        approval = disposition["approval"]
+        unless approval.is_a?(Hash) && approval["approval_id"].to_s != "" && approval["unit_id"].to_s == unit_id && approval["source_document_fingerprint"].to_s == source["source_document_fingerprint"].to_s
+          add(errors, "DISPOSITION_APPROVAL_MISSING", "deferred/out_of_scope requires a current unit approval", unit_id: unit_id)
+        end
+      end
+    end
+    unit_by_id.each_key { |id| add(errors, "UNIT_DISPOSITION_MISSING", "source unit has no disposition", unit_id: id) unless disposition_by_id.key?(id) }
+    active = disposition_by_id.select { |_id, entry| entry.dig("disposition", "kind").to_s == "active" }.keys
+    active.each do |unit_id|
+      Array(unit_by_id[unit_id]["required_assertions"]).each do |assertion|
+        id = assertion["assertion_id"].to_s
+        next if covered[id] || uncertain[id] || approval_required[id]
+        add(errors, "ASSERTION_UNCOVERED", "active assertion has no valid claim", unit_id: unit_id, assertion_id: id)
+      end
+    end
+    counts = { "unit_count" => units.length, "assertion_count" => assertions.length, "claim_count" => claims.length, "covered_assertion_count" => covered.length, "uncertain_assertion_count" => uncertain.length, "approval_required_assertion_count" => approval_required.length }
+    result(errors, counts, (uncertain.any? || approval_required.any?) ? "await_user" : nil)
+  rescue JSON::ParserError, Psych::Exception, ArgumentError => e
+    result([{ "code" => "COVERAGE_SCHEMA_INVALID", "message" => e.message }], {}, {})
+  end
+
+  def load(path, errors, code)
+    unless File.file?(path)
+      add(errors, code, "required coverage artifact is missing", path: path)
+      return nil
+    end
+    value = YAML.safe_load(File.read(path), permitted_classes: [], aliases: false)
+    raise ArgumentError, "coverage artifact must be a mapping" unless value.is_a?(Hash)
+    value
+  end
+
+  def validate_source(source, errors)
+    add(errors, "SOURCE_UNITS_SCHEMA_INVALID", "source_units schema_version must be 1") unless source["schema_version"].to_i == 1
+    add(errors, "SOURCE_UNITS_NOT_CORE_GENERATED", "source_units must be produced by Core") unless source["produced_by"].to_s == "core.source_unitizer/v1"
+    add(errors, "SOURCE_UNITS_SCHEMA_INVALID", "source_document_fingerprint is required") if source["source_document_fingerprint"].to_s.empty?
+    add(errors, "SOURCE_UNITS_SCHEMA_INVALID", "units must be an array") unless source["units"].is_a?(Array)
+    Array(source["units"]).each do |unit|
+      add(errors, "UNIT_SCHEMA_INVALID", "stable_unit_id is required") if unit["stable_unit_id"].to_s.empty?
+      add(errors, "SOURCE_UNIT_REUSED_STALE", "unit source fingerprint mismatch", unit_id: unit["stable_unit_id"]) unless unit["source_document_fingerprint"].to_s == source["source_document_fingerprint"].to_s
+      add(errors, "EXCERPT_MODIFIED", "excerpt fingerprint mismatch", unit_id: unit["stable_unit_id"]) if unit["excerpt_fingerprint"] && sha(unit["excerpt"]) != unit["excerpt_fingerprint"].to_s
+    end
+  end
+
+  def validate_coverage(coverage, errors)
+    add(errors, "COVERAGE_SCHEMA_INVALID", "coverage schema_version must be 1") unless coverage["schema_version"].to_i == 1
+    %w[claims units].each { |key| add(errors, "COVERAGE_SCHEMA_INVALID", "#{key} must be an array") unless coverage[key].is_a?(Array) }
+  end
+
+  def compare(assertion, inherited)
+    return "uncertain" unless inherited.is_a?(Hash)
+    expected = assertion.select { |key, _| %w[type polarity modality predicate condition role_scope order_constraint data_constraint exception].include?(key) }
+    actual = inherited.select { |key, _| expected.key?(key) }
+    return "equivalent" if canonical(expected) == canonical(actual)
+    return "under_coverage" if expected["polarity"] && actual["polarity"] && expected["polarity"] != actual["polarity"]
+    return "under_coverage" if expected["modality"] == "must" && actual["modality"] == "should"
+    if expected["role_scope"].is_a?(Hash) && actual["role_scope"].is_a?(Hash)
+      expected_include = Array(expected["role_scope"]["include"]); actual_include = Array(actual["role_scope"]["include"])
+      return "scope_widened" if (actual_include - expected_include).any?
+      return "under_coverage" if (expected_include - actual_include).any?
+    end
+    "uncertain"
+  end
+
+  def canonical(value)
+    JSON.generate(value.is_a?(Hash) ? value.keys.sort.to_h { |key| [key, canonical_value(value[key])] } : value)
+  end
+  def canonical_value(value)
+    value.is_a?(Hash) ? value.keys.sort.to_h { |key| [key, canonical_value(value[key])] } : value.is_a?(Array) ? value.map { |item| canonical_value(item) } : value
+  end
+  def sha(value)
+    Digest::SHA256.hexdigest(value.to_s)
+  end
+  def duplicate(errors, seen, id, code)
+    add(errors, code, "duplicate identifier", id: id) if seen.key?(id)
+    seen[id] = true
+  end
+  def add(errors, code, message, **extra)
+    errors << { "code" => code, "message" => message }.merge(extra)
+  end
+  def result(errors, counts, forced_verdict = nil)
+    verdict = if errors.any? then "block_unsafe" elsif forced_verdict then forced_verdict else "allow" end
+    { "ok" => verdict == "allow", "verdict" => verdict, "errors" => errors, "warnings" => [], "counts" => counts, "evidence" => { "checker" => "requirement-coverage-check" } }
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  options = {}
+  OptionParser.new do |opts|
+    opts.on("--root PATH") { |value| options[:root] = value }
+    opts.on("--feature NAME") { |value| options[:feature] = value }
+  end.parse!
+  abort("--root and --feature are required") unless options[:root] && options[:feature]
+  payload = RequirementCoverage.validate(root: options[:root], feature: options[:feature])
+  puts JSON.pretty_generate(payload)
+  exit(payload["verdict"] == "allow" ? 0 : 1)
+end

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

@@ -63,6 +63,10 @@ module RequirementGraph
     JSON.generate(value)
   end
 
+  def deep_clone(value)
+    JSON.parse(JSON.generate(value))
+  end
+
   def fingerprint(value)
     Digest::SHA256.hexdigest(canonical_json(value))
   end
@@ -1000,20 +1004,22 @@ if __FILE__ == $PROGRAM_NAME
                  { "ok" => true, "path" => relative, "context" => ctx }
                end
              when "propose"
-               raise ArgumentError, "--write is required" unless options[:write]
                raise ArgumentError, "--expected-revision is required" if options[:expected_revision].nil?
                if graph["revision"] != options[:expected_revision]
                  { "ok" => false, "reason" => "stale_graph_revision", "expected_revision" => options[:expected_revision], "actual_revision" => graph["revision"] }
                else
                  delta = JSON.parse(options[:delta_json].to_s)
                  allowed_kinds = options[:allowed_kinds]&.split(",")&.map(&:strip)
-                 applied = RequirementGraph.proposal(graph, delta, allowed_kinds)
-                 graph["revision"] += 1
-                 stale = Array(graph["stale"]).any?
-                 RequirementGraph.write_views!(root, graph, stale: stale)
-                 RequirementGraph.append_audit!(root, graph, { "event" => "graph_delta", "operation" => applied["operation"], "node_id" => applied.dig("node", "id"), "stale_count" => Array(applied["stale"]).length })
-                 DevflowControlIO.atomic_write(path, JSON.pretty_generate(graph) + "\n")
-                 { "ok" => true, "path" => relative, "revision" => graph["revision"], "applied" => applied, "validation_errors" => RequirementGraph.validate(graph), "checkers" => RequirementGraph.checker_results(graph), "views" => graph["views"] }
+                 candidate = RequirementGraph.deep_clone(graph)
+                 applied = RequirementGraph.proposal(candidate, delta, allowed_kinds)
+                 candidate["revision"] += 1
+                 stale = Array(candidate["stale"]).any?
+                 if options[:write]
+                   RequirementGraph.write_views!(root, candidate, stale: stale)
+                   RequirementGraph.append_audit!(root, candidate, { "event" => "graph_delta", "operation" => applied["operation"], "node_id" => applied.dig("node", "id"), "stale_count" => Array(applied["stale"]).length })
+                   DevflowControlIO.atomic_write(path, JSON.pretty_generate(candidate) + "\n")
+                 end
+                 { "ok" => true, "path" => relative, "written" => options[:write], "revision" => options[:write] ? candidate["revision"] : graph["revision"], "applied" => applied, "validation_errors" => RequirementGraph.validate(candidate), "checkers" => RequirementGraph.checker_results(candidate), "views" => candidate["views"] }
                end
              when "import-test-cases"
                raise ArgumentError, "--write is required" unless options[:write]

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

@@ -9,6 +9,9 @@ require_relative "control_io"
 require_relative "phase_ownership"
 require_relative "requirement_graph"
 require_relative "architecture_feasibility"
+require_relative "checker_registry"
+require_relative "requirement_coverage"
+require_relative "workflow_gate_contract"
 
 module WorkflowStateValidator
   REQUIRED_STATE_FIELDS = %w[
@@ -68,6 +71,8 @@ module WorkflowStateValidator
     )
 
     steps = Array(workflow["steps"])
+    validate_checker_registry(issues, workflow)
+    validate_workflow_gate_contract(issues, workflow)
     step_by_id = steps.to_h { |step| [step.fetch("id"), step] }
     step_ids = steps.map { |step| step.fetch("id") }
     completed_ids = Array(state["completed_steps"])
@@ -77,7 +82,7 @@ module WorkflowStateValidator
     validate_step_tracking(issues, state, step_ids, completed_ids, pending_ids, tracked_ids)
     validate_track_scope(issues, state, completed_ids)
     validate_dependencies(issues, step_by_id, completed_ids)
-    validate_completed_outputs(issues, root, state, step_by_id, completed_ids, artifact_by_path, strict_artifact_status)
+    validate_completed_outputs(issues, root, state, step_by_id, completed_ids, artifact_by_path, strict_artifact_status, workflow)
     validate_waiting_checkpoint(issues, root, state, step_by_id, artifact_by_path, strict_artifact_status)
     validate_current_in_progress_output_drift(issues, root, state, step_by_id, artifact_by_path)
     graph_gate = workflow.dig("governance", "requirement_graph_gate").to_s
@@ -264,13 +269,43 @@ unless %w[prepared claimed consumed superseded failed].include?(status)
     end
   end
 
-  def validate_completed_outputs(issues, root, state, step_by_id, completed_ids, artifact_by_path, strict_artifact_status)
+  def validate_checker_registry(issues, workflow)
+    declared = workflow.dig("governance", "step_checkers")
+    return unless declared.is_a?(Hash)
+
+    declared.each do |step_id, checker_ids|
+      Array(checker_ids).each do |checker_id|
+        next if CheckerRegistry.known?(checker_id)
+
+        issues << issue(
+          "error",
+          "unknown_checker_id",
+          "Workflow references a checker that is not in the canonical checker registry",
+          step: step_id,
+          checker_id: checker_id
+        )
+      end
+    end
+  end
+
+  def validate_workflow_gate_contract(issues, workflow)
+    # GateContract validation is opt-in.  Older/custom workflows intentionally
+    # use a smaller checkpoint shape and must keep the legacy control-plane
+    # behavior until they declare the contract version.
+    return unless workflow.dig("governance", "gate_contract_version").to_i >= 3
+
+    WorkflowGateContract.validate(workflow).each do |entry|
+      issues << issue("error", entry["code"], entry["message"], entry.reject { |key, _| %w[code message].include?(key) })
+    end
+  end
+
+  def validate_completed_outputs(issues, root, state, step_by_id, completed_ids, artifact_by_path, strict_artifact_status, workflow)
     completed_ids.each do |step_id|
       step = step_by_id[step_id]
       next unless step
 
       validate_step_outputs(issues, root, state, step, artifact_by_path, strict_artifact_status, waiting_checkpoint_step?(state, step_id))
-      validate_meta_output(issues, root, state, step)
+      validate_meta_output(issues, root, state, step, workflow)
     end
   end
 
@@ -390,7 +425,7 @@ unless %w[prepared claimed consumed superseded failed].include?(status)
     end
   end
 
-  def validate_meta_output(issues, root, state, step)
+  def validate_meta_output(issues, root, state, step, workflow = nil)
     meta = step["meta_output"]
     return unless meta
 
@@ -411,6 +446,7 @@ unless %w[prepared claimed consumed superseded failed].include?(status)
 
     validate_requirement_triage_gate(issues, step, data)
     validate_requirement_wayfinder_gate(issues, step, data)
+    validate_wayfinder_coverage_gate(issues, root, state, step, workflow)
     validate_domain_modeling_gate(issues, step, data)
     validate_requirement_feasibility_review_gate(issues, step, data)
     validate_requirement_baseline_gate(issues, step, data)
@@ -427,6 +463,21 @@ unless %w[prepared claimed consumed superseded failed].include?(status)
     issues << issue("error", "invalid_meta_json", e.message, step: step["id"], path: path)
   end
 
+  def validate_wayfinder_coverage_gate(issues, root, state, step, workflow)
+    return unless step["id"] == "requirement-wayfinder"
+    return unless workflow.nil? || workflow.dig("governance", "requirement_coverage_gate").to_s == "enforced"
+
+    result = RequirementCoverage.validate(root: root, feature: state.fetch("current_feature"))
+    return if result["verdict"] == "allow"
+
+    Array(result["errors"]).each do |entry|
+      issues << issue("error", entry["code"], entry["message"], step: step["id"], coverage: entry)
+    end
+    if result["verdict"] == "await_user"
+      issues << issue("error", "wayfinder_coverage_requires_decision", "Wayfinder coverage requires user review before completion", step: step["id"], counts: result["counts"])
+    end
+  end
+
   def validate_requirement_triage_gate(issues, step, data)
     return unless step["id"] == "requirement-triage"
 

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

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Validates the existing workflow topology as a GateContract source.  This is
+# intentionally declarative and read-only: it does not advance STATE or alter
+# failure-branch behavior.
+module WorkflowGateContract
+  CHECKPOINT_FIELDS = %w[gate_after producing_step required_outputs required_meta_output required_meta_fields prompt confirm_options skip_policy resume_behavior].freeze
+
+  module_function
+
+  def validate(workflow)
+    errors = []
+    checkpoints = workflow["checkpoints"]
+    unless checkpoints.is_a?(Hash)
+      return [error("CHECKPOINTS_SCHEMA_INVALID", "workflow checkpoints must be a mapping")]
+    end
+    checkpoints.each do |id, checkpoint|
+      unless checkpoint.is_a?(Hash)
+        errors << error("CHECKPOINT_SCHEMA_INVALID", "checkpoint must be a mapping", checkpoint: id)
+        next
+      end
+      CHECKPOINT_FIELDS.each do |field|
+        errors << error("CHECKPOINT_FIELD_MISSING", "checkpoint field is required", checkpoint: id, field: field) unless checkpoint.key?(field)
+      end
+      errors << error("CHECKPOINT_PRODUCER_MISMATCH", "gate_after must equal producing_step", checkpoint: id) if checkpoint["gate_after"].to_s != checkpoint["producing_step"].to_s
+      errors << error("CHECKPOINT_OUTPUTS_INVALID", "required_outputs must be an array", checkpoint: id) unless checkpoint["required_outputs"].is_a?(Array)
+      errors << error("CHECKPOINT_META_FIELDS_INVALID", "required_meta_fields must be an array", checkpoint: id) unless checkpoint["required_meta_fields"].is_a?(Array)
+      errors << error("CHECKPOINT_OPTIONS_INVALID", "confirm_options must include approve and needs_fix", checkpoint: id) unless Array(checkpoint["confirm_options"]).sort == %w[approve needs_fix]
+    end
+
+    Array(workflow.dig("governance", "enforced_checkpoints")).each do |id|
+      errors << error("CHECKPOINT_REF_NOT_FOUND", "enforced checkpoint is not defined", checkpoint: id) unless checkpoints.key?(id)
+    end
+
+    Array(workflow["parallel_windows"]).each do |window|
+      errors << error("PARALLEL_WINDOW_SCHEMA_INVALID", "parallel window must define join_step and branches", window: window["id"]) unless window.is_a?(Hash) && window["join_step"] && window["branches"].is_a?(Hash)
+      next unless window.is_a?(Hash)
+      errors << error("PARALLEL_WINDOW_CHECKPOINT_INVALID", "parallel join checkpoint is not defined", window: window["id"], checkpoint: window["checkpoint"]) if window["checkpoint"] && !checkpoints.key?(window["checkpoint"])
+    end
+
+    (workflow["failure_branches"] || {}).each do |source_step, branch|
+      resume = branch.is_a?(Hash) && branch["resume_after_success"]
+      unless resume.is_a?(Hash) && %w[flow step status checkpoint].all? { |field| resume.key?(field) }
+        errors << error("FAILURE_RETURN_TO_INVALID", "failure branch must declare flow, step, status and checkpoint", source_step: source_step)
+        next
+      end
+      errors << error("FAILURE_RETURN_CHECKPOINT_INVALID", "failure branch return checkpoint is not defined", source_step: source_step, checkpoint: resume["checkpoint"]) unless checkpoints.key?(resume["checkpoint"])
+    end
+    errors
+  end
+
+  def error(code, message, **extra)
+    { "code" => code, "message" => message }.merge(extra)
+  end
+end

package/plugins/devflow-core/skills/workflow-orchestrator/templates/feature-development.yaml

@@ -17,12 +17,15 @@ phase_scope:
 # files without governance_started_revision remain legacy_unattested and are
 # only reported until their next newly-started governed step.
 governance:
+  gate_contract_version: 3
   requirement_graph_gate: enforced
+  requirement_coverage_gate: enforced
   enforced_checkpoints:
     - CP-1
     - CP-API
     - CP-2
     - CP-3
+    - CP-4
   step_checkers:
     requirement-baseline:
       - requirement-graph-check
@@ -311,6 +314,7 @@ checkpoints:
     producing_step: run-acceptance-tests
     required_outputs:
       - ".planning/test-runs/{feature}/acceptance-results.json"
+    required_meta_output: ".planning/test-runs/{feature}/acceptance-results.meta.json"
     required_meta_fields:
       - acceptance_tc_passed
       - acceptance_tc_failed
@@ -365,6 +369,7 @@ steps:
     order: 6
     label: Requirement wayfinder
     skill: workflow-wayfinder
+    engine_evidence_gate: enforced
     depends_on:
       - requirement-triage
     inputs:
@@ -392,6 +397,7 @@ steps:
     order: 7
     label: Domain modeling
     skill: workflow-domain-modeling
+    engine_evidence_gate: enforced
     depends_on:
       - requirement-wayfinder
     inputs:
@@ -417,6 +423,7 @@ steps:
     order: 8
     label: Requirement feasibility review
     skill: requirement-feasibility-review
+    engine_evidence_gate: enforced
     depends_on:
       - domain-modeling
     inputs:
@@ -443,6 +450,7 @@ steps:
     order: 10
     label: Requirement baseline
     skill: workflow-requirement-baseline
+    engine_evidence_gate: enforced
     depends_on:
       - requirement-feasibility-review
     inputs:
@@ -478,6 +486,7 @@ steps:
     order: 15
     label: API contract
     skill: workflow-api-contract
+    engine_evidence_gate: enforced
     depends_on:
       - requirement-baseline
     inputs:
@@ -504,6 +513,7 @@ steps:
     order: 18
     label: Architecture feasibility
     skill: workflow-architecture-feasibility
+    engine_evidence_gate: enforced
     depends_on:
       - api-contract
     inputs:
@@ -535,6 +545,7 @@ steps:
     order: 20
     label: UI spec
     skill: workflow-ui-spec
+    engine_evidence_gate: enforced
     depends_on:
       - api-contract
       - architecture-feasibility
@@ -551,6 +562,7 @@ steps:
     order: 30
     label: Feature breakdown
     skill: workflow-feature-breakdown
+    engine_evidence_gate: enforced
     depends_on:
       - ui-spec
     inputs:
@@ -565,6 +577,7 @@ steps:
     order: 40
     label: Frontend tech spec
     skill: workflow-frontend-tech-spec
+    engine_evidence_gate: enforced
     depends_on:
       - feature-breakdown
       - api-contract
@@ -598,6 +611,7 @@ steps:
     order: 50
     label: Backend tech spec
     skill: workflow-backend-tech-spec
+    engine_evidence_gate: enforced
     depends_on:
       - api-contract
       - architecture-feasibility
@@ -625,6 +639,7 @@ steps:
     order: 55
     label: API call guide
     skill: workflow-api-call-guide
+    engine_evidence_gate: enforced
     depends_on:
       - api-contract
       - backend-tech-spec
@@ -649,6 +664,7 @@ steps:
     order: 56
     label: API supplement
     skill: workflow-api-supplement
+    engine_evidence_gate: enforced
     depends_on:
       - frontend-tech-spec
       - api-contract
@@ -672,6 +688,7 @@ steps:
     order: 58
     label: Integration verify
     skill: workflow-integration-verify
+    engine_evidence_gate: enforced
     depends_on:
       - api-call-guide
       - frontend-tech-spec
@@ -702,6 +719,7 @@ steps:
     order: 60
     label: Change plan
     skill: workflow-change-plan
+    engine_evidence_gate: enforced
     depends_on:
       - acceptance-test-design
     inputs:
@@ -735,6 +753,7 @@ steps:
     order: 59
     label: Acceptance test design
     skill: workflow-acceptance-test-design
+    engine_evidence_gate: enforced
     depends_on:
       - integration-verify
     inputs:
@@ -774,6 +793,7 @@ steps:
     order: 70
     label: Phase structure
     action: initialize-phase-structure
+    engine_evidence_gate: enforced
     depends_on:
       - change-plan
     inputs:
@@ -791,6 +811,7 @@ steps:
     order: 80
     label: Execute
     skill: workflow-execute-phase
+    engine_evidence_gate: enforced
     depends_on:
       - phase-structure
     inputs:
@@ -835,6 +856,7 @@ steps:
     order: 85
     label: Code Review
     skill: code-review
+    engine_evidence_gate: enforced
     depends_on:
       - code-index-refresh
     inputs:
@@ -849,6 +871,7 @@ steps:
     order: 86
     label: Generate mainflow cases
     skill: workflow-generate-mainflow-cases
+    engine_evidence_gate: enforced
     depends_on:
       - code-index-refresh
     inputs:
@@ -887,6 +910,7 @@ steps:
     order: 88
     label: Run frozen acceptance tests
     skill: workflow-run-acceptance-tests
+    engine_evidence_gate: enforced
     depends_on:
       - code-review
     inputs:

package/src/constants.ts

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