@guanlin4924/devflow-pi 0.1.39 → 0.1.47

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

@@ -0,0 +1,386 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Recover a legacy parallel window whose workers produced valid artifacts but
+# whose terminal lifecycle events were lost. This is deliberately a Core-only
+# writer: it validates every candidate branch before changing any branch, uses
+# ParallelRun's locked run-revision CAS for branch transitions, and delegates
+# the workflow/STATE mutation to advance_state.rb's existing join action.
+
+require "date"
+require "digest"
+require "json"
+require "open3"
+require "optparse"
+require "time"
+require "yaml"
+require_relative "control_io"
+require_relative "parallel_run"
+
+options = {
+  feature: nil,
+  expected_state_revision: nil,
+  expected_run_revision: nil,
+  reason: "legacy_parallel_lifecycle_event_lost",
+  write: false,
+  json: false,
+}
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: parallel_recover.rb [options]"
+  opts.on("--feature NAME", "Active feature whose parallel window is recovered") { |value| options[:feature] = value }
+  opts.on("--expected-state-revision REV", Integer, "CAS revision from STATE.md") { |value| options[:expected_state_revision] = value }
+  opts.on("--expected-run-revision REV", Integer, "CAS revision from branches.yaml") { |value| options[:expected_run_revision] = value }
+  opts.on("--reason TEXT", "Audit reason for the recovery") { |value| options[:reason] = value }
+  opts.on("--write", "Apply validated branch transitions and controlled join") { options[:write] = true }
+  opts.on("--json", "Print JSON output") { options[:json] = true }
+end.parse!
+
+def front_matter(markdown)
+  markdown.match(/\A---\n(.*?)\n---\n/m)&.[](1)
+end
+
+def load_yaml_mapping(path, label)
+  value = YAML.safe_load(File.read(path), permitted_classes: [Date, Time], aliases: false)
+  raise ArgumentError, "#{label} must be a mapping" unless value.is_a?(Hash)
+
+  value
+end
+
+def interpolate_path(path, state)
+  path.to_s
+      .gsub("{feature}", state.fetch("current_feature", "").to_s)
+      .gsub("{phase}", state.fetch("current_phase", "").to_s)
+end
+
+def required_output_specs(step)
+  outputs = Array(step["outputs"]).select { |item| item.is_a?(Hash) && item["required"] == true }
+  outputs << step["meta_output"] if step["meta_output"].is_a?(Hash)
+  outputs
+end
+
+def actual_content_issues(path, checks)
+  issues = []
+  min_bytes = checks["min_bytes"]
+  required_header = checks["required_header"]
+  issues << "below_min_bytes(#{File.size(path)} < #{min_bytes})" if min_bytes && File.size(path) < Integer(min_bytes)
+  if required_header
+    head = File.read(path, [required_header.to_s.length + 50, 200].min)
+    issues << "missing_required_header(#{required_header.inspect})" unless head.include?(required_header.to_s)
+  end
+  issues
+end
+
+def validate_registered_outputs(root, workflow, state, step, registry_by_path)
+  checks = workflow.dig("artifact_registry", "content_checks") || {}
+  required_output_specs(step).map do |spec|
+    relative = interpolate_path(spec["path"], state)
+    errors = []
+    errors << "required output path missing from workflow" if relative.empty?
+    registry = registry_by_path[relative]
+    errors << "artifact registry entry missing" unless registry
+
+    absolute = nil
+    begin
+      absolute, = DevflowControlIO.resolve_control_path(root, relative, :artifact) unless relative.empty?
+    rescue DevflowControlIO::InvalidControlPath => error
+      errors << error.message
+    end
+    errors << "artifact file missing" unless absolute && File.file?(absolute)
+
+    if registry
+      errors << "registry workflow_step mismatch" unless registry["workflow_step"].to_s == step["id"].to_s
+      errors << "registry type mismatch" if spec["type"] && registry["type"].to_s != spec["type"].to_s
+      errors << "registry exists metadata is not true" unless registry["exists"] == true
+      errors << "registry content_valid metadata is not true" unless registry["content_valid"] == true
+      errors << "registry reports content issues" unless Array(registry["content_issues"]).empty?
+    end
+    errors.concat(actual_content_issues(absolute, checks)) if absolute && File.file?(absolute)
+
+    {
+      "path" => relative,
+      "workflow_step" => step["id"],
+      "registry_status" => registry && registry["status"],
+      "exists" => absolute && File.file?(absolute),
+      "sha256" => absolute && File.file?(absolute) ? Digest::SHA256.file(absolute).hexdigest : nil,
+      "valid" => errors.empty?,
+      "errors" => errors,
+    }.compact
+  end
+end
+
+def generate_machine_evidence(root, feature, state_revision, branch, expected_paths)
+  script = File.join(__dir__, "machine_evidence.rb")
+  stdout, stderr, status = Open3.capture3(
+    "ruby", script,
+    "--feature", feature,
+    "--step", branch.fetch("workflow_step").to_s,
+    "--parallel-branch-id", branch.fetch("branch_id").to_s,
+    "--parallel-attempt", Integer(branch.fetch("attempt", 0)).to_s,
+    "--parallel-branch-revision", Integer(branch.fetch("branch_revision", 0)).to_s,
+    "--lock-held", "--write", "--json",
+    chdir: root,
+  )
+  payload = JSON.parse(stdout)
+  raise ArgumentError, (stderr.strip.empty? ? payload["message"] || "machine evidence failed" : stderr.strip) unless status.success? && payload.is_a?(Hash) && payload["ok"] == true
+
+  evidence_path = payload.fetch("path")
+  absolute, = DevflowControlIO.resolve_control_path(root, evidence_path, :artifact)
+  pack = JSON.parse(File.read(absolute))
+  binding = pack.dig("evidence", "parallel_binding")
+  expected_binding = {
+    "branch_id" => branch.fetch("branch_id").to_s,
+    "attempt" => Integer(branch.fetch("attempt", 0)),
+    "branch_revision" => Integer(branch.fetch("branch_revision", 0)),
+    "state_revision" => state_revision,
+  }
+  errors = []
+  errors << "machine evidence pack is incomplete" unless payload["complete"] == true && pack["complete"] == true
+  errors << "machine evidence origin is not Core" unless pack["origin"] == "core_machine"
+  errors << "machine evidence feature mismatch" unless pack["feature"].to_s == feature.to_s
+  errors << "machine evidence step mismatch" unless pack["step"].to_s == branch["workflow_step"].to_s
+  errors << "machine evidence binding mismatch" unless binding.is_a?(Hash) && expected_binding.all? { |key, value| binding[key].to_s == value.to_s }
+  packed_paths = Array(pack["files"]).select { |item| item.is_a?(Hash) && item["required"] == true }.map { |item| item["path"].to_s }.sort
+  errors << "machine evidence required outputs mismatch" unless packed_paths == expected_paths.sort
+  errors << "machine evidence contains a missing required file" unless Array(pack["files"]).all? { |item| item.is_a?(Hash) && item["exists"] == true && item["sha256"].to_s.match?(/\A[0-9a-f]{64}\z/) }
+  raise ArgumentError, errors.join("; ") unless errors.empty?
+
+  output_fingerprint = Digest::SHA256.hexdigest(
+    Array(pack["files"]).map { |item| [item["path"].to_s, item["sha256"].to_s] }.sort.to_json,
+  )
+  {
+    "evidence_path" => evidence_path,
+    "evidence_sha256" => Digest::SHA256.file(absolute).hexdigest,
+    "output_fingerprint" => output_fingerprint,
+    "checkers" => Array(pack["checkers"]).map { |item| item.slice("id", "passed", "exit_code") },
+  }
+rescue JSON::ParserError => error
+  raise ArgumentError, "machine evidence is not valid JSON: #{error.message}"
+end
+
+def audit_path(root, feature)
+  DevflowControlIO.resolve_control_path(root, ".planning/evidence/#{feature}/parallel-recovery.jsonl", :artifact).first
+end
+
+def append_audit(root, feature, payload, lock: nil)
+  owned_lock = lock.nil?
+  lock ||= DevflowControlIO.acquire_project_lock(root)
+  DevflowControlIO.append_audit(audit_path(root, feature), payload.merge("timestamp" => Time.now.utc.iso8601))
+ensure
+  DevflowControlIO.release_lock(lock) if owned_lock
+end
+
+def recovery_id(run, expected_state_revision, expected_run_revision)
+  material = [run["run_id"], expected_state_revision, expected_run_revision].join(":")
+  "REC-#{Digest::SHA256.hexdigest(material)[0, 20]}"
+end
+
+def prior_validation(root, feature, recovery, run)
+  path = audit_path(root, feature)
+  return nil unless File.file?(path)
+
+  events = File.foreach(path).each_with_object([]) do |line, parsed|
+    next if line.strip.empty?
+    begin
+      parsed << JSON.parse(line)
+    rescue JSON::ParserError
+      # A malformed historical line cannot authorize a resumed recovery.
+    end
+  end
+  validated = events.reverse.find do |event|
+    event["origin"] == "core.parallel_recovery/v1" && event["event"] == "validated" &&
+      event["recovery_id"] == recovery && event["run_id"].to_s == run["run_id"].to_s
+  end
+  return nil unless validated
+
+  logged = Array(validated["branches"]).to_h { |branch| [branch["branch_id"].to_s, branch] }
+  Array(run["branches"]).each do |branch|
+    next unless branch["status"] == "succeeded" && logged.key?(branch["branch_id"].to_s)
+
+    machine = logged.fetch(branch["branch_id"].to_s)["machine_evidence"] || {}
+    return nil unless branch["evidence_path"].to_s == machine["evidence_path"].to_s
+    return nil unless branch["output_fingerprint"].to_s == machine["output_fingerprint"].to_s
+  end
+  validated
+end
+
+def parse_json_result(stdout, stderr, status)
+  payload = JSON.parse(stdout)
+  return payload if payload.is_a?(Hash)
+
+  { "ok" => false, "reason" => "join_returned_invalid_payload", "message" => stderr.strip, "exit_status" => status.exitstatus }
+rescue JSON::ParserError => error
+  { "ok" => false, "reason" => "join_returned_invalid_json", "message" => error.message, "stderr" => stderr.strip, "exit_status" => status.exitstatus }
+end
+
+root = Dir.pwd
+feature = options[:feature].to_s
+result = nil
+exit_status = 0
+
+begin
+  raise ArgumentError, "--feature is required" if feature.empty?
+  ParallelRun.safe_feature(feature)
+  raise ArgumentError, "--expected-state-revision is required" if options[:expected_state_revision].nil?
+  raise ArgumentError, "--expected-run-revision is required" if options[:expected_run_revision].nil?
+  raise ArgumentError, "--write is required" unless options[:write]
+  raise ArgumentError, "--reason must not be empty" if options[:reason].to_s.strip.empty?
+
+  state_revision = nil
+  current_run_revision = nil
+  recovery = nil
+  recovered_branches = []
+  validation_records = []
+  project_lock = DevflowControlIO.acquire_project_lock(root)
+  begin
+    state_path, = DevflowControlIO.resolve_control_path(root, ".planning/STATE.md", :state)
+    state_yaml = front_matter(File.read(state_path))
+    raise ArgumentError, "STATE.md has no YAML front matter" unless state_yaml
+    state = YAML.safe_load(state_yaml, permitted_classes: [Date, Time], aliases: false)
+    raise ArgumentError, "STATE.md must contain a mapping" unless state.is_a?(Hash)
+    raise ArgumentError, "feature is not active: requested=#{feature}, current=#{state['current_feature']}" unless state["current_feature"].to_s == feature
+
+    run = ParallelRun.load(root, feature)
+    raise ArgumentError, "parallel run not found" unless run
+    recovery = recovery_id(run, options[:expected_state_revision], options[:expected_run_revision])
+    branches = Array(run["branches"])
+    already_joined = state["parallel_run_ref"].nil? && run["status"] == "completed" && branches.any? && branches.all? { |branch| branch["status"] == "succeeded" }
+    if already_joined
+      append_audit(root, feature, {
+        "schema_version" => 1, "origin" => "core.parallel_recovery/v1", "event" => "idempotent_noop",
+        "recovery_id" => recovery, "reason" => options[:reason], "run_id" => run["run_id"],
+        "state_revision" => state["revision"], "run_revision" => run["run_revision"],
+      }, lock: project_lock)
+      result = {
+        "ok" => true, "written" => false, "idempotent" => true, "recovery_id" => recovery,
+        "actions" => ["parallel_recovery_already_joined"], "state_revision" => state["revision"],
+        "run_revision" => run["run_revision"], "audit_path" => audit_path(root, feature).sub("#{root}/", ""),
+      }
+    else
+      state_revision = Integer(state.fetch("revision", 0))
+      current_run_revision = Integer(run.fetch("run_revision", 0))
+      raise ArgumentError, "stale STATE revision: expected=#{options[:expected_state_revision]}, actual=#{state_revision}" unless state_revision == options[:expected_state_revision]
+      raise ArgumentError, "STATE parallel_run_ref does not match run" unless state["parallel_run_ref"].to_s == run["run_id"].to_s
+      raise ArgumentError, "parallel run is bound to stale STATE revision" unless Integer(run.fetch("bound_state_revision")) == state_revision
+      raise ArgumentError, "parallel run has no branches" if branches.empty?
+      ineligible = branches.select { |branch| %w[failed aborted].include?(branch["status"].to_s) }
+      raise ArgumentError, "failed/aborted branches require explicit retry: #{ineligible.map { |branch| branch['branch_id'] }.join(', ')}" unless ineligible.empty?
+      previous_validation = prior_validation(root, feature, recovery, run)
+      unless current_run_revision == options[:expected_run_revision] || previous_validation
+        raise ArgumentError, "stale parallel run revision: expected=#{options[:expected_run_revision]}, actual=#{current_run_revision}"
+      end
+
+    workflow_path, = DevflowControlIO.resolve_control_path(root, state.fetch("workflow_config"), :workflow)
+    workflow = load_yaml_mapping(workflow_path, "workflow")
+    registry_source = workflow.dig("artifact_registry", "source").to_s
+    raise ArgumentError, "workflow artifact_registry.source is required for recovery" if registry_source.empty?
+    registry_path, = DevflowControlIO.resolve_control_path(root, registry_source, :registry)
+    registry = load_yaml_mapping(registry_path, "artifact registry")
+    raise ArgumentError, "artifact registry revision mismatch" unless Integer(registry.fetch("state_revision")) == state_revision
+    raise ArgumentError, "artifact registry feature mismatch" unless registry.dig("registry_scope", "feature").to_s == feature
+    registry_by_path = Array(registry["artifacts"]).each_with_object({}) do |artifact, index|
+      raise ArgumentError, "artifact registry entry must be a mapping" unless artifact.is_a?(Hash)
+      path = artifact["path"].to_s
+      raise ArgumentError, "artifact registry contains duplicate path: #{path}" if index.key?(path)
+      index[path] = artifact
+    end
+    steps = Array(workflow["steps"]).each_with_object({}) { |step, index| index[step["id"].to_s] = step if step.is_a?(Hash) }
+
+    candidates = branches.select { |branch| %w[pending running].include?(branch["status"].to_s) }
+    candidates.each do |branch|
+      step = steps[branch["workflow_step"].to_s]
+      raise ArgumentError, "parallel branch workflow step is unknown: #{branch['workflow_step']}" unless step
+      artifacts = validate_registered_outputs(root, workflow, state, step, registry_by_path)
+      invalid = artifacts.reject { |artifact| artifact["valid"] }
+      raise ArgumentError, "branch #{branch['branch_id']} artifact validation failed: #{invalid.to_json}" unless invalid.empty?
+      machine = generate_machine_evidence(root, feature, state_revision, branch, artifacts.map { |artifact| artifact["path"] })
+      validation_records << {
+        "branch_id" => branch["branch_id"], "workflow_step" => branch["workflow_step"],
+        "attempt" => branch.fetch("attempt", 0), "branch_revision" => branch.fetch("branch_revision", 0),
+        "artifacts" => artifacts, "machine_evidence" => machine,
+      }
+    end
+
+    append_audit(root, feature, {
+      "schema_version" => 1, "origin" => "core.parallel_recovery/v1", "event" => previous_validation ? "validated_resume" : "validated",
+      "recovery_id" => recovery, "reason" => options[:reason], "run_id" => run["run_id"],
+      "state_revision" => state_revision, "run_revision" => current_run_revision,
+      "branches" => validation_records,
+    }, lock: project_lock)
+
+    validation_records.each do |validated|
+      machine = validated.fetch("machine_evidence")
+      updated = ParallelRun.update_branch(
+        root: root, feature: feature, branch_id: validated.fetch("branch_id"),
+        expected_revision: current_run_revision, status: "succeeded",
+        evidence_path: machine.fetch("evidence_path"), output_fingerprint: machine.fetch("output_fingerprint"),
+        lock: project_lock,
+      )
+      current_run_revision = Integer(updated.fetch("run").fetch("run_revision"))
+      recovered_branches << validated.fetch("branch_id")
+    end
+    final_run = ParallelRun.load(root, feature)
+    unless Array(final_run["branches"]).all? { |branch| branch["status"] == "succeeded" }
+      raise ArgumentError, "recovery did not produce an all-succeeded run"
+    end
+      append_audit(root, feature, {
+        "schema_version" => 1, "origin" => "core.parallel_recovery/v1", "event" => "branches_recovered",
+        "recovery_id" => recovery, "reason" => options[:reason], "run_id" => final_run["run_id"],
+        "state_revision" => state_revision, "run_revision" => final_run["run_revision"],
+        "recovered_branch_ids" => recovered_branches,
+      }, lock: project_lock)
+    end
+  ensure
+    DevflowControlIO.release_lock(project_lock)
+  end
+
+  unless result
+    advance = File.join(__dir__, "advance_state.rb")
+    stdout, stderr, status = Open3.capture3(
+      "ruby", advance, "--write", "--parallel-action", "join",
+      "--expected-revision", state_revision.to_s, "--json", chdir: root,
+    )
+    joined = parse_json_result(stdout, stderr, status)
+    if status.success? && joined["ok"] == true
+      joined_run = ParallelRun.load(root, feature)
+      append_audit(root, feature, {
+        "schema_version" => 1, "origin" => "core.parallel_recovery/v1", "event" => "joined",
+        "recovery_id" => recovery, "reason" => options[:reason], "run_id" => joined_run && joined_run["run_id"],
+        "state_revision_before" => state_revision, "state_revision_after" => joined.dig("state", "revision"),
+        "run_revision" => joined_run && joined_run["run_revision"], "recovered_branch_ids" => recovered_branches,
+      })
+      result = {
+        "ok" => true, "written" => true, "idempotent" => false, "recovery_id" => recovery,
+        "actions" => ["parallel_branches_recovered", "parallel_window_joined"],
+        "recovered_branch_ids" => recovered_branches, "state" => joined["state"], "run" => joined_run,
+        "audit_path" => audit_path(root, feature).sub("#{root}/", ""),
+      }
+    else
+      append_audit(root, feature, {
+        "schema_version" => 1, "origin" => "core.parallel_recovery/v1", "event" => "join_refused",
+        "recovery_id" => recovery, "reason" => options[:reason], "state_revision" => state_revision,
+        "run_revision" => current_run_revision, "join_result" => joined,
+      })
+      result = { "ok" => false, "reason" => "controlled_join_failed", "recovery_id" => recovery, "details" => joined }
+      exit_status = 1
+    end
+  end
+rescue StandardError => error
+  exit_status = 1
+  begin
+    run = feature.empty? ? nil : ParallelRun.load(root, feature)
+    recovery ||= recovery_id(run, options[:expected_state_revision], options[:expected_run_revision]) if run
+    append_audit(root, feature, {
+      "schema_version" => 1, "origin" => "core.parallel_recovery/v1", "event" => "refused",
+      "recovery_id" => recovery, "reason" => options[:reason], "error_class" => error.class.name,
+      "message" => error.message, "expected_state_revision" => options[:expected_state_revision],
+      "expected_run_revision" => options[:expected_run_revision],
+    }) unless feature.empty?
+  rescue StandardError
+    # Preserve the original refusal when even the audit path is unavailable.
+  end
+  result = { "ok" => false, "reason" => "parallel_recovery_refused", "message" => error.message, "recovery_id" => recovery }
+end
+
+puts(options[:json] ? JSON.generate(result) : JSON.pretty_generate(result))
+exit exit_status

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

@@ -0,0 +1,248 @@
+#!/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
+
+  # STATE.md is the source of truth for the workflow revision.  A parallel
+  # window remains valid across ordinary state writes, so its optimistic
+  # revision bindings must move forward atomically with STATE.  Callers must
+  # hold the project lock when passing one; the helper acquires it otherwise.
+  def rebase_state_revision(root:, feature:, state_revision:, lock: nil)
+    owned_lock = lock.nil?
+    lock ||= DevflowControlIO.acquire_project_lock(root)
+    begin
+      record = load(root, feature)
+      return nil unless record
+
+      revision = Integer(state_revision)
+      record["bound_state_revision"] = revision
+      Array(record["branches"]).each { |branch| branch["expected_state_revision"] = revision }
+      record["updated_at"] = Time.now.utc.iso8601
+      write(root, feature, record)
+      record
+    ensure
+      DevflowControlIO.release_lock(lock) if owned_lock
+    end
+  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 rebase]) { |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])
+           when "rebase"
+             raise ArgumentError, "--state-revision is required" if options[:state_revision].nil?
+             ParallelRun.rebase_state_revision(root: Dir.pwd, feature: options[:feature], state_revision: options[:state_revision])
+               .then { |run| run ? { "ok" => true, "run" => run } : { "ok" => false, "reason" => "parallel_run_not_found" } }
+           else
+             raise ArgumentError, "--action must be inspect, prepare, update, retry, or rebase"
+           end
+  puts(options[:json] ? JSON.generate(result) : YAML.dump(result))
+  rescue StandardError => e
+    warn e.message
+    exit 1
+  end
+end