@guanlin4924/devflow-pi 0.1.105 → 0.1.107

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

@@ -0,0 +1,504 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+require "digest"
+require "securerandom"
+require "open3"
+require "timeout"
+require_relative "control_io"
+
+# STATE is the only mutable authority. Documents own intent, never verdicts.
+module DynamicPlan
+  SKILLS = {
+    "discover" => "workflow-requirement-triage",
+    "implement" => "workflow-execute-phase",
+    "repair" => "workflow-bug-fix",
+    "verify" => "workflow-run-acceptance-tests",
+    "review" => "code-review"
+  }.freeze
+  module_function
+
+  def digest(value)
+    Digest::SHA256.hexdigest(JSON.generate(value))
+  end
+
+  def normalize(text)
+    text.to_s.split.join(" ")
+  end
+
+  def path(root, relative)
+    raise ArgumentError, "project-relative path required" unless relative.is_a?(String) && !relative.empty? && !relative.start_with?("/") && !relative.split(/[\\\/]/).include?("..")
+    absolute = File.expand_path(relative, root)
+    cursor = absolute
+    cursor = File.dirname(cursor) until File.exist?(cursor) || File.symlink?(cursor)
+    real = File.realpath(cursor)
+    raise ArgumentError, "path escapes project" unless real == File.realpath(root) || real.start_with?(File.realpath(root) + "/")
+    absolute
+  end
+
+  def clauses(root, plan)
+    text = File.read(path(root, plan.fetch("document")))
+    result = {}
+    text.scan(/^### (R-[A-Za-z0-9_-]+)[:：]([^\n]*\n(?:(?!^### |^## ).*\n?)*)/).each do |id, body|
+      raise ArgumentError, "duplicate requirement #{id}" if result.key?(id)
+      result[id] = normalize(body)
+    end
+    result
+  end
+
+  def file_pin(root, relative)
+    absolute = path(root, relative)
+    return "missing" unless File.exist?(absolute)
+    return Digest::SHA256.file(absolute).hexdigest if File.file?(absolute)
+    entries = Dir.glob(File.join(absolute, "**", "*"), File::FNM_DOTMATCH).sort.filter_map do |entry|
+      next if entry.sub(absolute + "/", "").split("/").any? { |part| %w[.git node_modules .devflow __pycache__].include?(part) }
+      next unless File.file?(entry)
+      safe = path(root, entry.sub(File.expand_path(root) + "/", ""))
+      [entry.sub(absolute + "/", ""), Digest::SHA256.file(safe).hexdigest]
+    end
+    digest(entries)
+  end
+
+  def pins(root, plan, task)
+    requirements = clauses(root, plan)
+    {
+      "requirements" => task.fetch("requirements").to_h { |id| [id, requirements[id]] },
+      "inputs" => task.fetch("inputs").to_h { |file| [file, file_pin(root, file)] },
+      "spec" => digest(task.slice("kind", "requirements", "inputs", "outputs", "checks"))
+    }
+  end
+
+  def validate!(root, plan)
+    tasks = plan.fetch("tasks")
+    raise ArgumentError, "tasks must be an array" unless tasks.is_a?(Array)
+    ids = tasks.map { |task| task.fetch("id") }
+    raise ArgumentError, "duplicate task ids" unless ids.uniq == ids
+    tasks.each do |task|
+      raise ArgumentError, "invalid task id" unless task["id"].match?(/\A[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}\z/)
+      raise ArgumentError, "unknown capability" unless SKILLS.key?(task["kind"])
+      raise ArgumentError, "task title required" if task["title"].to_s.strip.empty?
+      %w[dependencies requirements inputs outputs checks].each { |key| raise ArgumentError, "#{key} must be an array" unless task[key].is_a?(Array) }
+      raise ArgumentError, "unknown dependency" unless (task["dependencies"] - ids).empty?
+      (task["inputs"] + task["outputs"]).each { |file| path(root, file) }
+      raise ArgumentError, "verification needs inputs and executable checks" if task["kind"] == "verify" && (task["checks"].empty? || task["inputs"].empty?)
+      raise ArgumentError, "review needs source inputs" if task["kind"] == "review" && task["inputs"].empty?
+      task["checks"].each do |check|
+        argv = check["argv"]
+        raise ArgumentError, "checks require nonempty argv arrays" unless argv.is_a?(Array) && argv.any? && argv.all? { |arg| arg.is_a?(String) && !arg.include?("\0") }
+      end
+      next unless task["status"] == "cancelled"
+      raise ArgumentError, "cancellation reason required" if task["reason"].to_s.strip.empty?
+      raise ArgumentError, "cancelled task still has consumers" if tasks.any? { |other| other["status"] != "cancelled" && other["dependencies"].include?(task["id"]) }
+    end
+    visited, visiting = [], []
+    visit = lambda do |id|
+      raise ArgumentError, "cyclic task dependencies" if visiting.include?(id)
+      return if visited.include?(id)
+      visiting << id
+      tasks.find { |task| task["id"] == id }["dependencies"].each { |dependency| visit.call(dependency) }
+      visiting.delete(id)
+      visited << id
+    end
+    ids.each { |id| visit.call(id) }
+    requirements = clauses(root, plan)
+    active = tasks.reject { |task| task["status"] == "cancelled" }
+    active.each do |task|
+      raise ArgumentError, "unknown requirement" unless (task["requirements"] - requirements.keys).empty?
+    end
+    unless tasks.empty? || plan["cancelled"]
+      raise ArgumentError, "requirement clauses missing from main document" if requirements.empty?
+      requirements.each_key do |id|
+        raise ArgumentError, "#{id} has no verification task" unless active.any? { |task| task["kind"] == "verify" && task["requirements"].include?(id) }
+      end
+      if active.any? { |task| %w[implement repair].include?(task["kind"]) }
+        raise ArgumentError, "code changes require independent review" unless active.any? { |task| task["kind"] == "review" }
+      end
+      ancestors = lambda do |task|
+        task["dependencies"].flat_map do |id|
+          [id, *ancestors.call(tasks.find { |other| other["id"] == id })]
+        end.uniq
+      end
+      active.select { |task| task["kind"] == "verify" }.each do |task|
+        producers = active.select { |other| other["kind"] == "implement" && (other["requirements"] & task["requirements"]).any? }
+        raise ArgumentError, "verification must depend on its implementation" unless (producers.map { |item| item["id"] } - ancestors.call(task)).empty?
+      end
+      if active.any? { |task| %w[implement repair].include?(task["kind"]) }
+        changed_requirements = active.select { |task| %w[implement repair].include?(task["kind"]) }.flat_map { |task| task["requirements"] }.uniq
+        changed_requirements.each do |id|
+          verifiers = active.select { |task| task["kind"] == "verify" && task["requirements"].include?(id) }
+          covered = active.any? do |task|
+            task["kind"] == "review" && task["requirements"].include?(id) && (verifiers.map { |item| item["id"] } - ancestors.call(task)).empty?
+          end
+          raise ArgumentError, "#{id} needs review after verification" unless covered
+        end
+      end
+    end
+    true
+  end
+
+  def refresh!(root, plan)
+    plan["tasks"].each do |task|
+      next unless task["status"] == "completed" && task["evidence"]
+      current_pins = pins(root, plan, task)
+      observed_pins = task["evidence"]["pins"]
+      unchanged = if %w[implement repair].include?(task["kind"])
+                    observed_pins.slice("requirements", "spec") == current_pins.slice("requirements", "spec")
+                  else
+                    observed_pins == current_pins
+                  end
+      next if unchanged
+      task["status"] = "pending"
+      task["verification"] = "stale"
+    end
+    loop do
+      changed = false
+      plan["tasks"].each do |task|
+        next unless task["status"] == "completed"
+        next if task["dependencies"].all? { |id| plan["tasks"].find { |other| other["id"] == id }&.dig("status") == "completed" }
+        task["status"], task["verification"], changed = "pending", "stale", true
+      end
+      break unless changed
+    end
+  end
+
+  def snapshot(root, state)
+    plan = state.fetch("plan")
+    refresh!(root, plan)
+    validation_error = begin
+      validate!(root, plan)
+      nil
+    rescue ArgumentError, KeyError => error
+      error.message
+    end
+    tasks = plan["tasks"]
+    ready = tasks.find do |task|
+      task["status"] == "pending" && task["dependencies"].all? { |id| tasks.find { |other| other["id"] == id }&.dig("status") == "completed" }
+    end
+    running = tasks.find { |task| %w[running checking].include?(task["status"]) }
+    complete = tasks.any? && tasks.all? { |task| %w[completed cancelled].include?(task["status"]) } && plan.fetch("decisions", []).none? { |item| item["status"] == "pending" }
+    action = if plan["cancelled"] then "workflow_cancelled"
+             elsif validation_error then "reconcile_plan"
+             elsif tasks.empty? then "plan_work"
+             elsif running then "resume_task"
+             elsif ready then "run_task"
+             elsif complete then "workflow_complete"
+             else "waiting" end
+    selected = running || ready
+    {
+      "ok" => true, "mode" => "dynamic", "action" => action, "revision" => state["revision"],
+      "current_flow" => "dynamic", "current_feature" => state["current_feature"], "current_phase" => state["current_phase"],
+      "status" => plan["cancelled"] ? "cancelled" : (complete && !validation_error ? "completed" : "in_progress"),
+      "document" => plan["document"], "plan_revision" => plan["revision"], "reason" => validation_error,
+      "progress_key" => digest(tasks.map { |task| task.slice("id", "status", "verification", "attempt").merge("results" => task.fetch("history", []).length) }),
+      "delivery" => plan["cancelled"] ? "cancelled" : (complete && !validation_error ? "ready" : "incomplete"),
+      "current_step" => selected && selected.merge("label" => selected["title"], "skill" => SKILLS[selected["kind"]]),
+      "workflow_steps" => tasks.map { |task| task.slice("id", "status", "verification", "reason").merge("label" => task["title"]) },
+      "tasks" => tasks, "decisions" => plan.fetch("decisions", [])
+    }
+  end
+
+  def read_state(root)
+    file, = DevflowControlIO.resolve_control_path(root, ".devflow/planning/STATE.md", :state)
+    return nil unless File.file?(file)
+    YAML.safe_load(File.read(file)[/\A---\n(.*?)\n---\n/m, 1], permitted_classes: [], aliases: false)
+  end
+
+  def save(root, state)
+    state["revision"] += 1
+    view = snapshot(root, state)
+    state["status"] = view["status"]
+    state["current_step"] = view.dig("current_step", "id")
+    state["completed_steps"] = state["plan"]["tasks"].select { |task| task["status"] == "completed" }.map { |task| task["id"] }
+    state["pending_steps"] = state["plan"]["tasks"].reject { |task| %w[completed cancelled].include?(task["status"]) }.map { |task| task["id"] }
+    file, = DevflowControlIO.resolve_control_path(root, ".devflow/planning/STATE.md", :state)
+    # JSON round-trip removes shared object identities; safe YAML readers must
+    # never need aliases to read a runtime state snapshot.
+    DevflowControlIO.atomic_write(file, JSON.parse(JSON.generate(state)).to_yaml + "---\n\n# Runtime state\n\nManaged by Core. Edit the requirement document to change intent.\n")
+    snapshot(root, state)
+  end
+
+  def transact(root, expected)
+    lock = DevflowControlIO.acquire_project_lock(root)
+    state = read_state(root)
+    raise ArgumentError, "dynamic plan not initialized" unless state && state["current_flow"] == "dynamic"
+    raise ArgumentError, "REVISION_CONFLICT: inspect again" unless expected.is_a?(Integer) && expected == state["revision"]
+    before = digest(state)
+    refresh!(root, state["plan"])
+    yield state
+    return snapshot(root, state) if digest(state) == before
+    save(root, state)
+  ensure
+    DevflowControlIO.release_lock(lock)
+  end
+
+  def run_check(root, check)
+    output, status, timed_out = +"", nil, false
+    seconds = [[Integer(check.fetch("timeout", 120)), 1].max, 600].min
+    Open3.popen2e(*check.fetch("argv"), chdir: root, pgroup: true) do |stdin, stream, wait|
+      stdin.close
+      reader = Thread.new do
+        loop do
+          chunk = stream.readpartial(4096)
+          output << chunk if output.bytesize < 32_768
+        end
+      rescue EOFError, IOError
+        nil
+      end
+      begin
+        Timeout.timeout(seconds) { status = wait.value.exitstatus }
+      rescue Timeout::Error
+        timed_out = true
+        Process.kill("KILL", -wait.pid) rescue nil
+        wait.value
+      ensure
+        # Drain the exited child's buffered output before closing the pipe.
+        # A descendant retaining the pipe cannot keep recovery waiting forever.
+        reader.join(1)
+        stream.close unless stream.closed?
+        reader.join
+      end
+    end
+    { "argv" => check["argv"], "exit_code" => status, "timeout" => timed_out, "output" => output.encode("UTF-8", invalid: :replace, undef: :replace), "passed" => status == 0 && !timed_out }
+  rescue SystemCallError => error
+    { "argv" => check["argv"], "passed" => false, "output" => error.message }
+  end
+
+  def failure!(plan, task, evidence)
+    task["status"], task["verification"] = "failed", "fail"
+    fingerprint = digest(evidence["checks"]&.map { |check| check.slice("argv", "exit_code", "output") } || evidence["review"])
+    previous = task.fetch("history", [])[0...-1].last
+    attempts = task.fetch("repair_attempts", 0)
+    if attempts >= 2 || (previous && previous["finding"] == fingerprint && previous["pins"] == evidence["pins"])
+      task["reason"] = "自动修复已停止：达到次数上限或没有进展；保留失败结果。"
+      return
+    end
+    evidence["finding"] = fingerprint
+    task["repair_attempts"] = attempts + 1
+    repair_id = "repair-#{digest(task['id'])[0, 12]}-#{attempts + 1}"
+    task["status"] = "pending"
+    task["dependencies"] << repair_id
+    plan["tasks"] << {
+      "id" => repair_id, "title" => "修复：#{task['title']}", "kind" => "repair", "requirements" => task["requirements"].dup,
+      "inputs" => task["inputs"].dup, "outputs" => [], "checks" => [], "dependencies" => [], "status" => "pending",
+      "verification" => "not_run", "finding" => evidence, "repairs" => task["id"], "history" => []
+    }
+    unless plan["tasks"].any? { |item| item["kind"] == "review" && item["status"] != "cancelled" && (task["requirements"] - item["requirements"]).empty? }
+      plan["tasks"] << {
+        "id" => "review-#{digest(task['id'])[0, 12]}-#{attempts + 1}", "title" => "独立审查修复结果", "kind" => "review", "requirements" => task["requirements"].dup,
+        "inputs" => task["inputs"].dup, "outputs" => [], "checks" => [], "dependencies" => plan["tasks"].select { |item| item["kind"] == "verify" && item["status"] != "cancelled" && (item["requirements"] & task["requirements"]).any? }.map { |item| item["id"] },
+        "status" => "pending", "verification" => "not_run", "history" => []
+      }
+    end
+    plan["revision"] += 1
+  end
+
+  def dispatch(root, request)
+    action = request.fetch("action")
+    if action == "inspect"
+      state = read_state(root)
+      return { "ok" => true, "mode" => "legacy" } unless state && state["current_flow"] == "dynamic"
+      return snapshot(root, state)
+    end
+    if action == "initialize"
+      lock = DevflowControlIO.acquire_project_lock(root)
+      begin
+        old = read_state(root)
+        raise ArgumentError, "active workflow exists; continue it or explicitly migrate" if old && !%w[completed cancelled].include?(old["status"])
+        feature = request.fetch("feature").to_s.strip
+        raise ArgumentError, "feature required" if feature.empty?
+        if old
+          archive = path(root, ".devflow/runs/plans/#{Digest::SHA256.hexdigest(old['current_phase'].to_s)[0, 16]}-#{SecureRandom.uuid}.json")
+          DevflowControlIO.atomic_write(archive, JSON.pretty_generate(old))
+        end
+        phase = request["phase"] || "feature-#{Digest::SHA256.hexdigest(feature)[0, 12]}-#{SecureRandom.hex(3)}"
+        raise ArgumentError, "invalid phase identifier" unless phase.is_a?(String) && phase.match?(/\A[A-Za-z0-9][A-Za-z0-9_-]{0,63}\z/)
+        document = ".devflow/planning/features/#{phase}/需求.md"
+        absolute = path(root, document)
+        raise ArgumentError, "requirement document already exists; choose a new phase or resume" if File.exist?(absolute)
+        DevflowControlIO.atomic_write(absolute, "# #{feature}\n\n## 目标与范围\n\n#{request.fetch('description', feature)}\n\n## 验收要求\n\n在需求核实后，将可验证要求写成 `### R-1: 要求描述`，每条保留稳定编号。\n\n## 方案与决定\n\n执行进度由 Core 展示；此处不手工记录通过状态。\n")
+        state = { "state_schema_version" => 3, "revision" => old ? old["revision"] : -1, "current_flow" => "dynamic", "current_feature" => feature, "current_phase" => phase,
+                  "plan" => { "version" => 1, "revision" => 0, "document" => document, "tasks" => [], "decisions" => [], "changes" => [] } }
+        return save(root, state)
+      ensure
+        DevflowControlIO.release_lock(lock)
+      end
+    end
+    if action == "verify"
+      claim = transact(root, request["expected_revision"]) do |state|
+        task = state["plan"]["tasks"].find { |item| item["id"] == request["task_id"] }
+        raise ArgumentError, "running verification attempt required" unless task && task["kind"] == "verify" && task["status"] == "running" && task["attempt"] == request["attempt"]
+        task["status"] = "checking"
+        task["runner_pid"] = Process.pid
+        task["check_pins"] = pins(root, state["plan"], task)
+      end
+      task = claim["tasks"].find { |item| item["id"] == request["task_id"] }
+      checks = task["checks"].map { |check| run_check(root, check) }
+      return transact(root, claim["revision"]) do |state|
+        current = state["plan"]["tasks"].find { |item| item["id"] == task["id"] }
+        raise ArgumentError, "verification inputs changed during execution" unless current["attempt"] == task["attempt"] && task["check_pins"] == pins(root, state["plan"], current)
+        evidence = { "attempt" => task["attempt"], "pins" => task["check_pins"], "checks" => checks, "at" => Time.now.utc.iso8601 }
+        current["history"] << evidence
+        current["evidence"] = evidence
+        if checks.all? { |check| check["passed"] }
+          current["status"], current["verification"] = "completed", "pass"
+        else
+          failure!(state["plan"], current, evidence)
+        end
+      end
+    end
+    transact(root, request["expected_revision"]) do |state|
+      plan = state["plan"]
+      raise ArgumentError, "workflow was cancelled; create a new requirement" if plan["cancelled"]
+      case action
+      when "cancel"
+        raise ArgumentError, "cancellation must come from user runtime action" unless request["runtime_cancel"] == true
+        plan["cancelled"] = true
+        plan["cancel_reason"] = request.fetch("reason")
+        plan["tasks"].each do |task|
+          next if task["status"] == "completed"
+          task["status"], task["reason"] = "cancelled", plan["cancel_reason"]
+          task.delete("attempt")
+        end
+      when "revise"
+        old_tasks = plan["tasks"].to_h { |task| [task["id"], task] }
+        new_requirements = clauses(root, plan)
+        scope_decision = plan["decisions"].find { |item| item["id"] == request["scope_decision_id"] }
+        permitted_removals = if scope_decision && scope_decision["status"] == "answered" && scope_decision["choice"] == scope_decision["approval_option"] && scope_decision["requirements_pin"] == digest(plan.fetch("requirements", {}))
+                              scope_decision.fetch("remove_requirements", [])
+                            else [] end
+        proposal = request.fetch("tasks")
+        raise ArgumentError, "keep removed tasks as cancelled with reasons" unless (old_tasks.keys - proposal.map { |task| task["id"] }).empty?
+        new_tasks = proposal.map do |item|
+          spec = item.slice("id", "title", "kind", "requirements", "inputs", "outputs", "checks", "dependencies")
+          %w[requirements inputs outputs checks dependencies].each { |key| spec[key] ||= [] }
+          old = old_tasks[item["id"]]
+          candidate = (old || { "status" => "pending", "verification" => "not_run", "history" => [] }).merge(spec)
+          changed = old && spec.any? { |key, value| key != "title" && old[key] != value }
+          if changed
+            candidate["status"], candidate["verification"] = "pending", "stale"
+            candidate.delete("attempt")
+          end
+          if item["cancelled"] == true
+            if old && old["verification"] == "fail"
+              withdrawn = (old["requirements"] - permitted_removals).empty? && (old["requirements"] & new_requirements.keys).empty?
+              raise ArgumentError, "cannot cancel a failing obligation without its explicit scope withdrawal" unless withdrawn
+            end
+            candidate["status"], candidate["reason"] = "cancelled", item["reason"]
+            candidate.delete("attempt")
+          end
+          candidate
+        end
+        plan["tasks"] = new_tasks
+        validate!(root, plan)
+        old_requirements = plan.fetch("requirements", {})
+        removed = old_requirements.keys - new_requirements.keys
+        raise ArgumentError, "removing acceptance requirements needs an explicit scope decision for those clauses" unless (removed - permitted_removals).empty?
+        plan["requirements"] = new_requirements
+        plan["revision"] += 1
+        plan["changes"] << { "revision" => plan["revision"], "reason" => request.fetch("reason"), "at" => Time.now.utc.iso8601 }
+      when "claim"
+        view = snapshot(root, state)
+        raise ArgumentError, "no runnable task" unless view["action"] == "run_task"
+        task = plan["tasks"].find { |item| item["id"] == view.dig("current_step", "id") }
+        task["status"], task["attempt"] = "running", SecureRandom.uuid
+        task["started_at"] = Time.now.utc.iso8601
+        task["dispatch_pins"] = pins(root, plan, task)
+      when "report", "review_result"
+        task = plan["tasks"].find { |item| item["id"] == request["task_id"] }
+        raise ArgumentError, "stale or missing task attempt" unless task && task["status"] == "running" && task["attempt"] == request["attempt"]
+        raise ArgumentError, "verification must run through Core" if task["kind"] == "verify"
+        if task["kind"] == "review"
+          raise ArgumentError, "independent reviewer result required" unless action == "review_result" && request["runtime_review"] == true
+          raise ArgumentError, "review inputs changed" unless task["dispatch_pins"] == pins(root, plan, task)
+          report = request.fetch("report")
+          raise ArgumentError, "invalid reviewer report" unless report["findings"].is_a?(Array) && report["summary"].is_a?(String)
+          evidence = { "pins" => pins(root, plan, task), "review" => report, "task_call_id" => request.fetch("task_call_id"), "attempt" => task["attempt"] }
+          task["history"] << evidence
+          task["evidence"] = evidence
+          if report["findings"].empty?
+            task["status"], task["verification"] = "completed", "pass"
+          else
+            failure!(plan, task, evidence)
+          end
+        else
+          raise ArgumentError, "requirements changed during execution" unless task["dispatch_pins"]["requirements"] == pins(root, plan, task)["requirements"]
+          raise ArgumentError, "result summary required" if request["summary"].to_s.strip.empty?
+          raise ArgumentError, "expected output missing" unless task["outputs"].all? { |file| File.exist?(path(root, file)) }
+          # Implementation is an activity result, never an acceptance pass.
+          evidence = { "pins" => pins(root, plan, task), "summary" => request["summary"], "attempt" => task["attempt"] }
+          task["evidence"] = evidence
+          task["history"] << evidence
+          task["status"], task["verification"] = "completed", "not_run"
+        end
+      when "recover"
+        task = plan["tasks"].find { |item| item["id"] == request["task_id"] }
+        raise ArgumentError, "only an interrupted attempt may recover" unless task && %w[running checking].include?(task["status"])
+        if task["status"] == "checking" && task["runner_pid"]
+          alive = begin
+            Process.kill(0, task["runner_pid"])
+            true
+          rescue Errno::ESRCH
+            false
+          end
+          raise ArgumentError, "verification process is still running" if alive
+        end
+        raise ArgumentError, "inspect actual effects and provide a recovery reason" if request["reason"].to_s.strip.empty?
+        task["history"] << { "attempt" => task["attempt"], "interrupted" => true, "reason" => request["reason"] }
+        task["status"] = "pending"
+        task.delete("attempt")
+      when "wait"
+        task = plan["tasks"].find { |item| item["id"] == request["task_id"] }
+        raise ArgumentError, "running attempt required" unless task && task["status"] == "running" && task["attempt"] == request["attempt"]
+        raise ArgumentError, "external dependency reason required" if request["reason"].to_s.strip.empty?
+        task["status"], task["reason"] = "waiting_external", request["reason"]
+      when "resume"
+        task = plan["tasks"].find { |item| item["id"] == request["task_id"] }
+        raise ArgumentError, "external waiting task required" unless task && task["status"] == "waiting_external"
+        raise ArgumentError, "evidence that external dependency is ready required" if request["reason"].to_s.strip.empty?
+        task["history"] << { "resumed" => true, "reason" => request["reason"] }
+        task["status"] = "pending"
+        task.delete("attempt")
+      when "decision"
+        options = request.fetch("options")
+        raise ArgumentError, "provide two or three concrete options" unless options.is_a?(Array) && (2..3).include?(options.length) && options.all? { |item| item.is_a?(String) && !item.strip.empty? }
+        question = request.fetch("question")
+        removals = request.fetch("remove_requirements", [])
+        raise ArgumentError, "scope removal must name existing requirement IDs" unless removals.is_a?(Array) && (removals - plan.fetch("requirements", {}).keys).empty?
+        raise ArgumentError, "scope removal needs an explicit approving option" if removals.any? && !options.include?(request["approval_option"])
+        binding = file_pin(root, plan["document"])
+        unless plan["decisions"].any? { |item| item["question"] == question && item["document_pin"] == binding }
+          plan["decisions"].select { |item| item["question"] == question && item["status"] == "pending" }.each { |item| item["status"] = "superseded" }
+          affected = request["task_ids"] || [snapshot(root, state).dig("current_step", "id")].compact
+          raise ArgumentError, "unknown affected decision task" unless (affected - plan["tasks"].map { |task| task["id"] }).empty?
+          blocked = plan["tasks"].select { |task| affected.include?(task["id"]) && !%w[completed cancelled].include?(task["status"]) }
+          prior = blocked.to_h { |task| [task["id"], task["status"] == "waiting_decision" ? "pending" : task["status"]] }
+          blocked.each { |task| task["status"] = "waiting_decision" }
+          plan["decisions"] << { "id" => SecureRandom.uuid, "question" => question, "options" => options, "status" => "pending", "document_pin" => binding, "requirements_pin" => digest(plan.fetch("requirements", {})), "blocked_tasks" => prior, "remove_requirements" => removals, "approval_option" => request["approval_option"] }
+        end
+      when "decide"
+        raise ArgumentError, "user response must come from runtime UI" unless request["runtime_decision"] == true
+        decision = plan["decisions"].find { |item| item["id"] == request["decision_id"] }
+        raise ArgumentError, "decision expired" unless decision && decision["status"] == "pending" && decision["document_pin"] == file_pin(root, plan["document"])
+        raise ArgumentError, "invalid option" unless decision["options"].include?(request["choice"])
+        decision["status"], decision["choice"] = "answered", request["choice"]
+        decision.fetch("blocked_tasks", {}).each do |id, prior|
+          task = plan["tasks"].find { |item| item["id"] == id }
+          still_blocked = plan["decisions"].any? { |item| item["status"] == "pending" && item.fetch("blocked_tasks", {}).key?(id) }
+          task["status"] = prior if task && task["status"] == "waiting_decision" && !still_blocked
+        end
+      else
+        raise ArgumentError, "unknown dynamic plan action"
+      end
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  begin
+    puts JSON.generate(DynamicPlan.dispatch(Dir.pwd, JSON.parse(STDIN.read)))
+  rescue StandardError => error
+    puts JSON.generate({ "ok" => false, "reason" => error.message })
+    exit 1
+  end
+end

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

@@ -10,6 +10,7 @@ require "yaml"
 require_relative "control_io"
 require_relative "requirement_graph"
 require_relative "checker_registry"
+require_relative "parallel_run"
 
 POLICY = {
   "domain-modeling" => { "checkers" => %w[requirement-graph-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[term object behavior rule boundary] },
@@ -134,10 +135,46 @@ begin
       devflow_architecture_constraint devflow_architecture_feasibility devflow_architecture_brief
       devflow_approval
     ],
-    "tool_budget" => policy["budget"], "hard_gate_mode" => (workflow.dig("governance", "hard_gate_mode").to_s.empty? ? "chain" : workflow.dig("governance", "hard_gate_mode").to_s), "acceptance" => Array(graph["nodes"]).select { |node| node["kind"] == "acceptance" }.map { |node| node["id"] },
+    "tool_budget" => policy["budget"], "acceptance" => Array(graph["nodes"]).select { |node| node["kind"] == "acceptance" }.map { |node| node["id"] },
     "allowed_graph_delta" => Array(policy["allowed_graph_delta"]),
     "on_unknown" => "block_and_escalate"
   }
+  # While a durable parallel run is attached, current_step is the join
+  # anchor, not permission to execute the join before its branches finish.
+  if state["parallel_run_ref"]
+    run = ParallelRun.load(root, options[:feature])
+    raise ArgumentError, "parallel run reference mismatch" unless run && run["run_id"] == state["parallel_run_ref"]
+    raise ArgumentError, "parallel run state revision mismatch" unless run["bound_state_revision"] == state["revision"]
+    window = Array(workflow["parallel_windows"]).find { |item| item["id"] == run["workflow_window"] }
+    raise ArgumentError, "parallel window unavailable" unless window && Array(state["completed_steps"]).include?(window["after_step"])
+    declared = window.fetch("branches", {}).values.flatten
+    branches = Array(run["branches"])
+    raise ArgumentError, "parallel run has no branches" if branches.empty?
+    branch_contracts = branches.map do |branch|
+      id = branch["workflow_step"]
+      raise ArgumentError, "parallel branch outside declared window" unless declared.include?(id)
+      definition = Array(workflow["steps"]).find { |item| item["id"] == id }
+      branch_policy = POLICY.fetch(id)
+      raise ArgumentError, "parallel branch definition unavailable" unless definition
+      {
+        "branch_id" => branch["branch_id"], "step" => id,
+        "allowed_agents" => branch_policy.fetch("agents"),
+        "allowed_paths" => (Array(definition["outputs"]).map { |output| output["path"] } + [definition.dig("meta_output", "path")]).compact.map { |value| interpolate(value, state) }.uniq,
+        "tool_budget" => branch_policy.fetch("budget"),
+        "allowed_graph_delta" => Array(branch_policy["allowed_graph_delta"])
+      }
+    end
+    contract.merge!(
+      "scope" => "parallel_window", "parallel_run_id" => run["run_id"],
+      "parallel_window_id" => window["id"], "join_step" => window["join_step"],
+      "branch_contracts" => branch_contracts,
+      "allowed_paths" => branch_contracts.flat_map { |item| item["allowed_paths"] }.uniq,
+      "allowed_agents" => branch_contracts.flat_map { |item| item["allowed_agents"] }.uniq,
+      "tool_budget" => branch_contracts.sum { |item| item["tool_budget"] },
+      "allowed_graph_delta" => branch_contracts.flat_map { |item| item["allowed_graph_delta"] }.uniq,
+      "checker_ids" => []
+    )
+  end
   frozen = contract.merge("frozen_hash" => Digest::SHA256.hexdigest(JSON.generate(contract)))
   contract_id = "EC-#{frozen["frozen_hash"][0, 16]}"
   frozen["contract_id"] = contract_id

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# One policy for workflow diagnostics. Failed checks retain their evidence;
+# advisory execution never changes a failed test/check into a passing result.
+module GatePolicy
+  module_function
+
+  def advisory(entry)
+    entry.merge("severity" => "warning", "soft_gate" => true)
+  end
+end

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

@@ -1,6 +1,8 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+require_relative "gate_policy"
+
 module GateResult
   VERDICTS = %w[allow allow_with_warning await_user waiting_external_input block_unsafe].freeze
   CONTROL_PLANE_ERROR = "control_plane_error"
@@ -11,6 +13,16 @@ module GateResult
     valid = VERDICTS.include?(verdict.to_s) || verdict.to_s == CONTROL_PLANE_ERROR
     raise ArgumentError, "invalid gate verdict: #{verdict}" unless valid
 
+    if !%w[allow allow_with_warning].include?(verdict.to_s)
+      codes = Array(errors).map { |entry| entry.is_a?(Hash) ? entry["code"].to_s : "" }
+      structural = codes.any? { |code| %w[REVISION_CONFLICT BUSINESS_GATE_POLICY_INVALID].include?(code) }
+      unless structural
+        warnings = Array(warnings) + Array(errors).map { |entry| GatePolicy.advisory(entry.is_a?(Hash) ? entry : { "message" => entry.to_s }) }
+        warnings << { "code" => "SOFT_GATE", "original_verdict" => verdict.to_s } if warnings.empty?
+        errors = []
+        verdict = "allow_with_warning"
+      end
+    end
     {
       "ok" => %w[allow allow_with_warning].include?(verdict.to_s),
       "verdict" => verdict.to_s,

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

@@ -32,14 +32,6 @@ module GateRuntime
     gate_id = contract.fetch("gate_id")
     step_id = contract.fetch("step_id")
     base = { gate_id: gate_id, step_id: step_id, evidence: evidence.merge("collector" => source), revisions: { "state" => current_revision } }
-    # During the chain-skill migration Core is diagnostic-only. It still
-    # validates the contract shape above, but never blocks a transition on
-    # graph, artifact, output, checker, review, or topology observations.
-    # Checkpoint confirmation remains fail-closed because approval-path outputs
-    # do not exist until the user approves the waiting checkpoint.
-    if contract.fetch("hard_gate_mode", "core").to_s == "chain" && transition_kind.to_s != "confirm_checkpoint"
-      return GateResult.allow(**base.merge(evidence: base.fetch(:evidence).merge("core_hard_gate_mode" => "chain", "core_hard_gate_bypassed" => true)))
-    end
     return GateResult.block(**base, code: "REVISION_CONFLICT", message: "current revision does not match expected revision", recovery: { "kind" => "reinspect", "expected_revision" => expected_revision }) unless expected_revision.nil? || current_revision.to_i == expected_revision.to_i
     unless WORKFLOW_STATUSES.include?(workflow_state["status"].to_s)
       return GateResult.block(**base, code: "WORKFLOW_STATUS_INVALID", message: "workflow status is not recognized")
@@ -191,10 +183,13 @@ module GateRuntime
 
   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"
+    return boundary unless boundary["ok"]
     result = checker.call
     raise ArgumentError, "checker must return a GateResult hash" unless result.is_a?(Hash) && result["verdict"]
+    warnings = Array(boundary["warnings"]) + Array(result["warnings"])
     result.merge(
+      "warnings" => warnings,
+      "verdict" => result["verdict"] == "allow" && warnings.any? ? "allow_with_warning" : result["verdict"],
       "gate_id" => result["gate_id"] || boundary["gate_id"],
       "step_id" => result["step_id"] || boundary["step_id"],
       "evidence" => boundary.fetch("evidence", {}).merge(result.fetch("evidence", {})),