@guanlin4924/devflow-pi 0.1.37 → 0.1.39

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