@guanlin4924/devflow-pi 0.1.38 → 0.1.40

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

@@ -0,0 +1,222 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "date"
+require "digest"
+require "fileutils"
+require "json"
+require "optparse"
+require "securerandom"
+require "time"
+require "yaml"
+require_relative "control_io"
+
+# Durable scheduler state for one workflow parallel window.  This file owns
+# dispatch state only; artifacts/index.yaml owns artifact content state and
+# STATE.md owns the workflow snapshot/current pointer.
+module ParallelRun
+  SCHEMA_VERSION = 1
+  TERMINAL_BRANCH_STATUSES = %w[succeeded failed aborted].freeze
+
+  module_function
+
+  def safe_feature(feature)
+    value = feature.to_s
+    raise ArgumentError, "feature is required" if value.empty?
+    raise ArgumentError, "feature contains path separators" if value.include?("/") || value.include?("\\") || value == "." || value == ".."
+
+    value
+  end
+
+  def path(root, feature)
+    File.join(root, ".planning", "parallel", safe_feature(feature), "branches.yaml")
+  end
+
+  def load(root, feature)
+    target = path(root, feature)
+    return nil unless File.file?(target)
+
+    value = YAML.safe_load(File.read(target), permitted_classes: [Date, Time], aliases: false)
+    raise ArgumentError, "parallel run record must be a mapping" unless value.is_a?(Hash)
+    value
+  end
+
+  def write(root, feature, record)
+    raise ArgumentError, "parallel run record must be a mapping" unless record.is_a?(Hash)
+
+    DevflowControlIO.atomic_write(path(root, feature), record.to_yaml)
+    record
+  end
+
+  def state_front_matter(markdown)
+    match = markdown.match(/\A---\n(.*?)\n---\n/m)
+    match && match[1]
+  end
+
+  def attach_state_ref(root, state_path, run_id, expected_revision)
+    absolute, = DevflowControlIO.resolve_control_path(root, state_path, :state)
+    original = File.read(absolute)
+    front = state_front_matter(original)
+    raise ArgumentError, "STATE.md has no YAML front matter" unless front
+
+    state = YAML.safe_load(front, permitted_classes: [], aliases: false)
+    raise ArgumentError, "STATE.md must contain a mapping" unless state.is_a?(Hash)
+    actual = Integer(state.fetch("revision", 0))
+    raise ArgumentError, "STATE revision conflict" unless actual == Integer(expected_revision)
+    raise ArgumentError, "STATE already references a parallel run" if state["parallel_run_ref"]
+
+    state["parallel_run_ref"] = run_id
+    state["revision"] = actual + 1
+    body = original.sub(/\A---\n.*?\n---\n/m, "---\n#{state.to_yaml.sub(/\A---\n/, "")}---\n")
+    DevflowControlIO.atomic_write(absolute, body)
+    state
+  end
+
+  def prepare(root:, feature:, workflow_window:, state_revision:, branches:, task_ids: {}, state_path: ".planning/STATE.md")
+    lock = DevflowControlIO.acquire_project_lock(root)
+    begin
+      raise ArgumentError, "parallel run already exists" if load(root, feature)
+
+      run_id = "PR-#{SecureRandom.uuid}"
+      branch_records = Array(branches).map do |branch|
+        value = branch.is_a?(Hash) ? branch : { "branch_id" => branch }
+        workflow_step = value["workflow_step"].to_s
+        track = value["track"].to_s
+        raise ArgumentError, "workflow_step is required" if workflow_step.empty?
+        raise ArgumentError, "track is required" if track.empty?
+        branch_id = value["branch_id"].to_s
+        branch_id = "#{run_id}-#{track.sub(/\Atrack_/, "")}-#{workflow_step}" if branch_id.empty?
+
+        value.merge(
+          "branch_id" => branch_id,
+          "workflow_step" => workflow_step,
+          "track" => track,
+          "attempt" => 0,
+          "branch_revision" => 0,
+          "status" => "pending",
+          "task_id" => task_ids[branch_id],
+          "previous_branch_id" => nil,
+          "history" => [],
+        ).compact
+      end
+      record = {
+        "schema_version" => SCHEMA_VERSION,
+        "run_id" => run_id,
+        "workflow_window" => workflow_window,
+        "bound_state_revision" => Integer(state_revision),
+        "run_revision" => 0,
+        "status" => "pending",
+        "created_at" => Time.now.utc.iso8601,
+        "branches" => branch_records,
+      }
+      write(root, feature, record)
+      updated_state = attach_state_ref(root, state_path, run_id, state_revision)
+      record["bound_state_revision"] = Integer(updated_state.fetch("revision"))
+      record["branches"].each { |branch| branch["expected_state_revision"] = record["bound_state_revision"] }
+      write(root, feature, record)
+      { "ok" => true, "run" => record }
+    ensure
+      DevflowControlIO.release_lock(lock)
+    end
+  end
+
+  def update_branch(root:, feature:, branch_id:, expected_revision:, status:, task_id: nil, evidence_path: nil, output_fingerprint: nil, error: nil, lock: nil)
+    owned_lock = lock.nil?
+    lock ||= DevflowControlIO.acquire_project_lock(root)
+    begin
+      record = load(root, feature) || raise(ArgumentError, "parallel run not found")
+      actual = Integer(record.fetch("run_revision", 0))
+      raise ArgumentError, "parallel run revision conflict" unless actual == Integer(expected_revision)
+
+      branch = Array(record["branches"]).find { |item| item["branch_id"].to_s == branch_id.to_s }
+      raise ArgumentError, "parallel branch not found: #{branch_id}" unless branch
+      raise ArgumentError, "invalid branch status: #{status}" unless (TERMINAL_BRANCH_STATUSES + %w[pending running]).include?(status)
+      raise ArgumentError, "terminal branch must retry before update" if TERMINAL_BRANCH_STATUSES.include?(branch["status"])
+
+      branch["status"] = status
+      branch["branch_revision"] = Integer(branch.fetch("branch_revision", 0)) + 1
+      branch["task_id"] = task_id if task_id
+      branch["evidence_path"] = evidence_path if evidence_path
+      branch["output_fingerprint"] = output_fingerprint if output_fingerprint
+      branch["error"] = error if error
+      record["run_revision"] = actual + 1
+      record["status"] = "failed" if status == "failed"
+      record["status"] = "running" if status == "running" && record["status"] == "pending"
+      record["status"] = "completed" if Array(record["branches"]).all? { |item| item["status"] == "succeeded" }
+      record["updated_at"] = Time.now.utc.iso8601
+      write(root, feature, record)
+      { "ok" => true, "run" => record }
+    ensure
+      DevflowControlIO.release_lock(lock) if owned_lock
+    end
+  end
+
+  def retry_branch(root:, feature:, branch_id:, expected_revision:, lock: nil)
+    owned_lock = lock.nil?
+    lock ||= DevflowControlIO.acquire_project_lock(root)
+    begin
+      record = load(root, feature) || raise(ArgumentError, "parallel run not found")
+      raise ArgumentError, "parallel run revision conflict" unless Integer(record.fetch("run_revision", 0)) == Integer(expected_revision)
+      branch = Array(record["branches"]).find { |item| item["branch_id"].to_s == branch_id.to_s }
+      raise ArgumentError, "parallel branch not found: #{branch_id}" unless branch
+      raise ArgumentError, "only failed/aborted branch can retry" unless %w[failed aborted].include?(branch["status"])
+
+      previous_id = branch["branch_id"]
+      branch["history"] ||= []
+      branch["history"] << branch.slice("branch_id", "attempt", "branch_revision", "status", "task_id", "evidence_path")
+      branch["attempt"] = Integer(branch.fetch("attempt", 0)) + 1
+      branch["branch_revision"] = 0
+      branch["previous_branch_id"] = previous_id
+      branch["status"] = "pending"
+      branch.delete("error")
+      record["status"] = "running"
+      record["run_revision"] = Integer(record.fetch("run_revision", 0)) + 1
+      record["updated_at"] = Time.now.utc.iso8601
+      write(root, feature, record)
+      { "ok" => true, "run" => record }
+    ensure
+      DevflowControlIO.release_lock(lock) if owned_lock
+    end
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+  options = { action: nil, feature: nil, state_revision: nil, run_revision: nil, branch_id: nil, status: nil, workflow_window: nil, branches: [], state_path: ".planning/STATE.md", json: false }
+  OptionParser.new do |opts|
+    opts.on("--action ACTION", %w[inspect prepare update retry]) { |value| options[:action] = value }
+    opts.on("--feature FEATURE") { |value| options[:feature] = value }
+    opts.on("--state-revision REV", Integer) { |value| options[:state_revision] = value }
+    opts.on("--run-revision REV", Integer) { |value| options[:run_revision] = value }
+    opts.on("--branch-id ID") { |value| options[:branch_id] = value }
+    opts.on("--status STATUS") { |value| options[:status] = value }
+    opts.on("--workflow-window NAME") { |value| options[:workflow_window] = value }
+    opts.on("--state PATH") { |value| options[:state_path] = value }
+    opts.on("--branch STEP:TRACK", "Register a branch as workflow_step:track") do |value|
+      workflow_step, track = value.split(":", 2)
+      raise ArgumentError, "--branch must be WORKFLOW_STEP:TRACK" if workflow_step.to_s.empty? || track.to_s.empty?
+      options[:branches] << { "workflow_step" => workflow_step, "track" => track }
+    end
+    opts.on("--json") { options[:json] = true }
+  end.parse!
+
+  raise ArgumentError, "--feature is required" unless options[:feature]
+  result = case options[:action]
+           when "inspect"
+             record = ParallelRun.load(Dir.pwd, options[:feature])
+             record ? { "ok" => true, "run" => record } : { "ok" => false, "reason" => "parallel_run_not_found" }
+           when "prepare"
+             ParallelRun.prepare(root: Dir.pwd, feature: options[:feature], workflow_window: options[:workflow_window], state_revision: options[:state_revision], branches: options[:branches], state_path: options[:state_path])
+           when "update"
+             ParallelRun.update_branch(root: Dir.pwd, feature: options[:feature], branch_id: options[:branch_id], expected_revision: options[:run_revision], status: options[:status])
+           when "retry"
+             ParallelRun.retry_branch(root: Dir.pwd, feature: options[:feature], branch_id: options[:branch_id], expected_revision: options[:run_revision])
+           else
+             raise ArgumentError, "--action must be inspect, prepare, update, or retry"
+           end
+  puts(options[:json] ? JSON.generate(result) : YAML.dump(result))
+  rescue StandardError => e
+    warn e.message
+    exit 1
+  end
+end

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,10 @@ 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"
+require_relative "parallel_run"
 
 module WorkflowStateValidator
   REQUIRED_STATE_FIELDS = %w[
@@ -68,6 +72,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"])
@@ -75,9 +81,13 @@ module WorkflowStateValidator
     tracked_ids = completed_ids + pending_ids
 
     validate_step_tracking(issues, state, step_ids, completed_ids, pending_ids, tracked_ids)
-    validate_track_scope(issues, state, completed_ids)
+    if state["parallel_run_ref"]
+      validate_parallel_run(issues, root, state, workflow, step_by_id)
+    else
+      validate_track_scope(issues, state, completed_ids)
+    end
     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 +274,113 @@ 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_parallel_run(issues, root, state, workflow, step_by_id)
+    feature = state["current_feature"].to_s
+    run = ParallelRun.load(root, feature)
+    unless run
+      issues << issue("error", "parallel_run_missing", "parallel_run_ref does not resolve to a run record", feature: feature)
+      return
+    end
+    if run["run_id"].to_s != state["parallel_run_ref"].to_s
+      issues << issue("error", "parallel_run_ref_mismatch", "parallel_run_ref does not match the run record", reference: state["parallel_run_ref"], run_id: run["run_id"])
+    end
+    begin
+      bound_revision = Integer(run.fetch("bound_state_revision"))
+      issues << issue("error", "parallel_state_revision_mismatch", "parallel run is bound to a different STATE revision", state_revision: state["revision"], bound_state_revision: bound_revision) unless bound_revision == Integer(state.fetch("revision"))
+    rescue ArgumentError, TypeError, KeyError
+      issues << issue("error", "parallel_run_revision_invalid", "parallel run bound_state_revision is invalid")
+    end
+
+    window = Array(workflow["parallel_windows"]).find { |candidate| candidate.is_a?(Hash) && candidate["id"].to_s == run["workflow_window"].to_s }
+    unless window
+      issues << issue("error", "parallel_window_not_found", "parallel run references an unknown workflow window", window: run["workflow_window"])
+      return
+    end
+    join_step = window["join_step"].to_s
+    if state["current_step"].to_s != join_step
+      issues << issue("error", "parallel_current_step_invalid", "parallel state current_step must remain the window join step", current_step: state["current_step"], join_step: join_step)
+    end
+
+    branch_steps = window["branches"].is_a?(Hash) ? window["branches"].each_with_object({}) do |(track, steps), result|
+      Array(steps).each { |step| result[step.to_s] = track.to_s }
+    end : {}
+    seen_ids = {}
+    Array(run["branches"]).each do |branch|
+      unless branch.is_a?(Hash)
+        issues << issue("error", "parallel_branch_invalid", "parallel run branch must be a mapping")
+        next
+      end
+      branch_id = branch["branch_id"].to_s
+      step_id = branch["workflow_step"].to_s
+      track = branch["track"].to_s
+      issues << issue("error", "parallel_branch_id_missing", "parallel branch_id is required") if branch_id.empty?
+      issues << issue("error", "parallel_branch_duplicate_id", "parallel branch_id is duplicated", branch_id: branch_id) if seen_ids[branch_id]
+      seen_ids[branch_id] = true
+      issues << issue("error", "parallel_branch_step_missing", "parallel branch workflow_step is required", branch_id: branch_id) if step_id.empty?
+      issues << issue("error", "parallel_branch_step_unknown", "parallel branch step is not in the window", branch_id: branch_id, step: step_id) unless branch_steps.key?(step_id)
+      issues << issue("error", "parallel_branch_track_mismatch", "parallel branch track does not match the workflow window", branch_id: branch_id, track: track, expected_track: branch_steps[step_id]) if branch_steps[step_id] && track.sub(/\Atrack_/, "").upcase != branch_steps[step_id].sub(/\Atrack_/, "").upcase
+      begin
+        attempt = Integer(branch.fetch("attempt"))
+        branch_revision = Integer(branch.fetch("branch_revision"))
+        issues << issue("error", "parallel_branch_attempt_invalid", "parallel branch attempt must be non-negative", branch_id: branch_id) if attempt.negative?
+        issues << issue("error", "parallel_branch_revision_invalid", "parallel branch revision must be non-negative", branch_id: branch_id) if branch_revision.negative?
+      rescue ArgumentError, TypeError, KeyError
+        issues << issue("error", "parallel_branch_version_invalid", "parallel branch attempt and branch_revision are required integers", branch_id: branch_id)
+      end
+      expected_state_revision = branch["expected_state_revision"]
+      if expected_state_revision && expected_state_revision.to_i != state["revision"].to_i
+        issues << issue("error", "parallel_branch_state_revision_mismatch", "parallel branch is bound to a different STATE revision", branch_id: branch_id)
+      end
+      if step_id && state["completed_steps"].to_a.map(&:to_s).include?(step_id)
+        issues << issue("error", "parallel_step_completed_before_join", "parallel branch step must not enter completed_steps before join", branch_id: branch_id, step: step_id)
+      end
+    end
+    declared_steps = branch_steps.keys
+    actual_steps = Array(run["branches"]).select { |branch| branch.is_a?(Hash) }.map { |branch| branch["workflow_step"].to_s }
+    duplicate_steps = actual_steps.each_with_object(Hash.new(0)) { |step, counts| counts[step] += 1 }.select { |_, count| count > 1 }.keys
+    duplicate_steps.each { |step| issues << issue("error", "parallel_branch_step_duplicated", "parallel run contains duplicate workflow_step records", step: step) }
+    (declared_steps - actual_steps).each { |step| issues << issue("error", "parallel_branch_record_missing", "workflow branch step has no persisted branch record", step: step) }
+  rescue ArgumentError, TypeError, Psych::Exception => error
+    issues << issue("error", "parallel_run_invalid", "parallel run record is invalid", detail: error.message)
+  end
+
+  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 +500,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 +521,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 +538,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"