@guanlin4924/devflow-pi 0.1.39 → 0.1.40

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

@@ -1,9 +1,11 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+require "json"
 require_relative "gate_result"
 require_relative "gate_contract"
 require_relative "checker_registry"
+require_relative "parallel_run"
 
 module GateRuntime
   WORKFLOW_STATUSES = %w[in_progress waiting_checkpoint completed blocked failed cancelled remediation].freeze
@@ -16,7 +18,7 @@ module GateRuntime
     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)
+  def evaluate(contract:, workflow_state:, current_revision:, expected_revision:, track: nil, branch_id: nil, attempt: nil, branch_revision: 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")
@@ -25,7 +27,22 @@ module GateRuntime
     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)
+    if workflow_state["parallel_run_ref"]
+      branch_error = validate_parallel_branch(
+        contract: contract,
+        workflow_state: workflow_state,
+        current_revision: current_revision,
+        track: track,
+        branch_id: branch_id,
+        attempt: attempt,
+        branch_revision: branch_revision,
+        evidence: evidence,
+        root: root,
+        transition_kind: transition_kind,
+      )
+      return GateResult.block(**base, **branch_error) if branch_error
+    end
+    unless %w[confirm_checkpoint enter_failure_branch exit_failure_branch parallel_join].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" })
@@ -60,6 +77,58 @@ module GateRuntime
     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 validate_parallel_branch(contract:, workflow_state:, current_revision:, track:, branch_id:, attempt:, branch_revision:, evidence:, root:, transition_kind:)
+    return { code: "PARALLEL_CONTEXT_MISSING", message: "parallel workflow requires root" } unless root
+
+    record = ParallelRun.load(root, workflow_state.fetch("current_feature"))
+    return { code: "PARALLEL_RUN_NOT_FOUND", message: "parallel_run_ref does not resolve to a run record" } unless record
+    return { code: "PARALLEL_RUN_REF_MISMATCH", message: "STATE parallel_run_ref does not match run record" } unless record["run_id"].to_s == workflow_state["parallel_run_ref"].to_s
+    bound_revision = Integer(record.fetch("bound_state_revision"))
+    return { code: "PARALLEL_STATE_REVISION_MISMATCH", message: "parallel run is bound to a different STATE revision", details: { expected_state_revision: bound_revision, actual_state_revision: current_revision } } unless bound_revision == current_revision.to_i
+
+    if transition_kind.to_s == "parallel_join"
+      branches = Array(record["branches"])
+      return { code: "PARALLEL_JOIN_INCOMPLETE", message: "parallel join requires every branch to succeed", details: { incomplete: branches.reject { |item| item["status"].to_s == "succeeded" }.map { |item| item["branch_id"] } } } unless branches.any? && branches.all? { |item| item["status"].to_s == "succeeded" }
+      return nil
+    end
+    return { code: "PARALLEL_CONTEXT_MISSING", message: "parallel workflow requires branch_id" } unless branch_id
+
+    branch = Array(record["branches"]).find { |item| item["branch_id"].to_s == branch_id.to_s }
+    return { code: "PARALLEL_BRANCH_NOT_FOUND", message: "branch is not registered in the parallel run", details: { branch_id: branch_id } } unless branch
+    return { code: "PARALLEL_STEP_MISMATCH", message: "branch is bound to a different workflow step", details: { branch_step: branch["workflow_step"], gate_step: contract["step_id"] } } unless branch["workflow_step"].to_s == contract["step_id"].to_s
+    expected_track = branch["track"].to_s.sub(/\Atrack_/, "").upcase
+    return { code: "PARALLEL_TRACK_MISMATCH", message: "branch track is not the requested track", details: { branch_track: expected_track, requested_track: track } } unless track.to_s.empty? || expected_track.empty? || expected_track == track.to_s
+    return { code: "PARALLEL_BRANCH_TERMINAL", message: "terminal branch cannot pass a gate; retry must create a new attempt" } if ParallelRun::TERMINAL_BRANCH_STATUSES.include?(branch["status"].to_s) && transition_kind.to_s != "parallel_branch_retry"
+    return { code: "PARALLEL_ATTEMPT_MISMATCH", message: "branch attempt does not match the current run record" } if attempt && Integer(branch.fetch("attempt", 0)) != attempt.to_i
+    return { code: "PARALLEL_BRANCH_REVISION_MISMATCH", message: "branch revision does not match the current run record" } if branch_revision && Integer(branch.fetch("branch_revision", 0)) != branch_revision.to_i
+
+    predecessor_ids = Array(contract.dig("topology", "allowed_predecessors"))
+    completed = Array(workflow_state["completed_steps"]).map(&:to_s)
+    completed.concat(Array(record["branches"]).select { |item| item["status"].to_s == "succeeded" }.map { |item| item["workflow_step"].to_s })
+    missing_predecessors = predecessor_ids.map(&:to_s).reject { |step| completed.include?(step) }
+    return { code: "PARALLEL_PREDECESSOR_INCOMPLETE", message: "parallel branch predecessor is incomplete", details: { missing: missing_predecessors } } unless missing_predecessors.empty?
+
+    if transition_kind.to_s == "parallel_branch_complete"
+      required = %w[branch_id attempt branch_revision]
+      missing = required.reject { |field| evidence.key?(field) }
+      return { code: "PARALLEL_EVIDENCE_MISSING", message: "branch completion requires independent evidence binding", details: { missing: missing } } unless missing.empty?
+      return { code: "PARALLEL_EVIDENCE_MISMATCH", message: "branch evidence does not match current branch", details: { branch_id: branch_id } } unless evidence["branch_id"].to_s == branch_id.to_s && evidence["attempt"].to_i == branch.fetch("attempt", 0).to_i && evidence["branch_revision"].to_i == branch.fetch("branch_revision", 0).to_i
+      evidence_path = evidence["evidence_path"].to_s
+      return { code: "PARALLEL_EVIDENCE_MISSING", message: "Core machine evidence file is required" } if evidence_path.empty? || !File.file?(File.expand_path(evidence_path, root))
+      begin
+        pack = JSON.parse(File.read(File.expand_path(evidence_path, root)))
+        binding = pack.dig("evidence", "parallel_binding")
+        expected = { "run_id" => record["run_id"], "branch_id" => branch["branch_id"], "attempt" => branch.fetch("attempt", 0), "branch_revision" => branch.fetch("branch_revision", 0), "state_revision" => current_revision.to_i }
+        return { code: "PARALLEL_EVIDENCE_MISMATCH", message: "machine evidence binding does not match current branch", details: { expected: expected, actual: binding } } unless binding.is_a?(Hash) && expected.all? { |key, value| binding[key].to_s == value.to_s }
+      rescue JSON::ParserError, Errno::ENOENT
+        return { code: "PARALLEL_EVIDENCE_MISMATCH", message: "machine evidence file is not valid JSON" }
+      end
+    end
+    nil
+  rescue KeyError, ArgumentError, TypeError
+    { code: "PARALLEL_RECORD_INVALID", message: "parallel run or branch record is invalid" }
+  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"

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

@@ -191,6 +191,9 @@ def active_parallel_window(workflow, state, root, step_by_id, completed_ids, pen
       step = step_by_id[step_id]
       pending_ids.include?(step_id) && step && dependencies_satisfied?(step, completed_ids)
     end
+    # A single runnable branch is an intentional serial fallback (for example
+    # when active_track limits the window to one track), not a missing window.
+    # Only a genuinely multi-branch runnable set enters the parallel scheduler.
     next unless runnable_ids.length > 1
 
     policy = window["execution_policy"] || {}

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

@@ -12,13 +12,17 @@ require_relative "control_io"
 require_relative "requirement_graph"
 require_relative "checker_registry"
 
-options = { feature: nil, step: nil, contract: nil, write: false, json: false }
+options = { feature: nil, step: nil, contract: nil, write: false, json: false, branch_id: nil, attempt: nil, branch_revision: nil, lock_held: false }
 OptionParser.new do |o|
   o.on("--feature NAME") { |v| options[:feature] = v }
   o.on("--step ID") { |v| options[:step] = v }
   o.on("--contract PATH") { |v| options[:contract] = v }
   o.on("--write") { options[:write] = true }
   o.on("--json") { options[:json] = true }
+  o.on("--parallel-branch-id ID") { |v| options[:branch_id] = v }
+  o.on("--parallel-attempt N", Integer) { |v| options[:attempt] = v }
+  o.on("--parallel-branch-revision N", Integer) { |v| options[:branch_revision] = v }
+  o.on("--lock-held") { options[:lock_held] = true }
 end.parse!
 abort "feature, step and --write are required" unless options[:feature] && options[:step] && options[:write]
 abort "invalid feature" unless RequirementGraph.valid_feature?(options[:feature])
@@ -41,7 +45,7 @@ def file_evidence(root, relative)
   { "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)
+def independent_evidence(root, feature, step, state, workflow, graph, files, checker_results, binding = nil, inputs = [])
   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"] : {}
@@ -54,7 +58,9 @@ def independent_evidence(root, feature, step, state, workflow, graph, files, che
   # 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")
+  binding_attempt = binding && binding["attempt"]
+  event_name = binding_attempt.nil? ? "#{step}.engine-events.jsonl" : "#{step}.attempt-#{binding_attempt}.engine-events.jsonl"
+  event_path = File.join(".planning", "evidence", feature, event_name)
   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|
@@ -72,10 +78,15 @@ def independent_evidence(root, feature, step, state, workflow, graph, files, che
              nil
            end
   ai_events = events ? events.select { |event| %w[ai_runtime_initialized ai_invocation].include?(event["event"]) } : []
+  dispatched_events = events ? events.select { |event| event["event"] == "engine_dispatched" } : []
+  ai_measurement_observed = !ai_events.empty?
 
   {
     "collector" => "core.machine_evidence/v1",
     "state" => { "revision" => state["revision"], "step" => step },
+    "parallel_binding" => binding,
+    "input_fingerprints" => inputs.select { |item| item["exists"] }.map { |item| item["sha256"] },
+    "output_fingerprints" => files.select { |item| item["exists"] }.map { |item| item["sha256"] },
     "source_authority" => { "status" => authority.empty? ? "unavailable" : "observed", "sources" => authority },
     "candidate_binding" => {
       "status" => "observed",
@@ -90,8 +101,13 @@ def independent_evidence(root, feature, step, state, workflow, graph, files, che
     "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,
+      # engine_dispatched proves that the harness dispatched work, but it does
+      # not prove how many model calls the child session made. Keep unknown as
+      # nil instead of manufacturing false/zero values for branch evidence.
+      "ai_runtime_initialized" => ai_measurement_observed ? ai_events.any? { |event| event["event"] == "ai_runtime_initialized" } : nil,
+      "ai_invocation_count" => ai_measurement_observed ? ai_events.count { |event| event["event"] == "ai_invocation" } : nil,
+      "engine_dispatched_count" => events ? dispatched_events.length : nil,
+      "ai_capable_engine_dispatched" => events ? dispatched_events.any? { |event| event["ai_capable"] == true } : nil,
       "evidence_status" => events ? "observed" : "unavailable"
     }
   }
@@ -156,10 +172,21 @@ rescue JSON::ParserError => error
 end
 
 root = Dir.pwd
-lock = DevflowControlIO.acquire_project_lock(root)
+lock = options[:lock_held] ? nil : DevflowControlIO.acquire_project_lock(root)
 begin
   state = state_front_matter(root)
-  unless state["current_feature"] == options[:feature] && state["current_step"] == options[:step]
+  binding = nil
+  branch = nil
+  if options[:branch_id]
+    require_relative "parallel_run"
+    record = ParallelRun.load(root, options[:feature])
+    branch = Array(record && record["branches"]).find { |item| item["branch_id"].to_s == options[:branch_id].to_s }
+    raise "parallel branch not found" unless record && branch
+    raise "parallel branch attempt mismatch" unless options[:attempt].nil? || Integer(branch.fetch("attempt", 0)) == options[:attempt]
+    raise "parallel branch revision mismatch" unless options[:branch_revision].nil? || Integer(branch.fetch("branch_revision", 0)) == options[:branch_revision]
+    binding = { "run_id" => record["run_id"], "branch_id" => branch["branch_id"], "attempt" => branch["attempt"], "branch_revision" => branch["branch_revision"], "state_revision" => state["revision"] }
+  end
+  unless state["current_feature"] == options[:feature] && (state["current_step"] == options[:step] || branch)
     result = { "ok" => false, "reason" => "state_step_mismatch", "state_feature" => state["current_feature"], "state_step" => state["current_step"] }
     puts JSON.pretty_generate(result)
     exit 1
@@ -181,6 +208,7 @@ begin
     { "path" => relative, "required" => true, "exists" => exists, "bytes" => exists ? File.size(absolute) : 0,
       "sha256" => exists ? Digest::SHA256.file(absolute).hexdigest : nil }
   end.compact
+  input_files = Array(step["inputs"]).map { |input| file_evidence(root, interpolate(input.to_s, state)) }
 
   graph, = RequirementGraph.load_graph(root, options[:feature])
   checkers = RequirementGraph.checker_results(graph)
@@ -206,13 +234,17 @@ 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)
+  independent = independent_evidence(root, options[:feature], options[:step], state, workflow, graph, files, checker_results, binding, input_files)
   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, "evidence" => independent,
+    "run_id" => binding && binding["run_id"], "branch_id" => binding && binding["branch_id"],
+    "attempt" => binding && binding["attempt"], "branch_revision" => binding && binding["branch_revision"],
+    "input_fingerprints" => input_files.select { |item| item["exists"] }.map { |item| item["sha256"] },
+    "output_fingerprints" => files.select { |item| item["exists"] }.map { |item| item["sha256"] },
+    "contract_hash" => contract_hash, "files" => files, "input_files" => input_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) } },
@@ -220,12 +252,13 @@ begin
     "evidence_complete" => evidence_complete,
     "gate_mode" => gate.empty? ? "observe" : gate
   }.compact
-  destination = File.join(root, ".planning/evidence", options[:feature], "#{options[:step]}.machine.json")
+  suffix = binding ? ".attempt-#{binding["attempt"]}.branch-#{Digest::SHA256.hexdigest(binding["branch_id"].to_s)[0, 12]}" : ""
+  destination = File.join(root, ".planning/evidence", options[:feature], "#{options[:step]}#{suffix}.machine.json")
   DevflowControlIO.atomic_write(destination, JSON.pretty_generate(pack) + "\n")
-  result = { "ok" => true, "path" => destination.sub("#{root}/", ""), "complete" => pack["complete"], "state_revision" => pack["state_revision"], "graph_revision" => pack["graph_revision"], "checkers" => checker_results }
+  result = { "ok" => true, "path" => destination.sub("#{root}/", ""), "complete" => pack["complete"], "state_revision" => pack["state_revision"], "graph_revision" => pack["graph_revision"], "checkers" => checker_results, "parallel_binding" => binding }
 rescue StandardError => error
   result = { "ok" => false, "reason" => "machine_evidence_failed", "message" => error.message }
 ensure
-  DevflowControlIO.release_lock(lock)
+  DevflowControlIO.release_lock(lock) if lock
 end
 puts JSON.pretty_generate(result)

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/validate_state.rb

@@ -12,6 +12,7 @@ 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[
@@ -80,7 +81,11 @@ 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, workflow)
     validate_waiting_checkpoint(issues, root, state, step_by_id, artifact_by_path, strict_artifact_status)
@@ -269,6 +274,76 @@ unless %w[prepared claimed consumed superseded failed].include?(status)
     end
   end
 
+  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)