@guanlin4924/devflow-pi 0.1.39 → 0.1.47

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

@@ -9,6 +9,7 @@ require "json"
 require "optparse"
 require "pathname"
 require "set"
+require "yaml"
 require_relative "control_io"
 require_relative "architecture_constraints"
 
@@ -54,6 +55,22 @@ module RequirementGraph
     File.dirname(path)
   end
 
+  def active_feature(root)
+    state_path = File.join(root, ".planning", "STATE.md")
+    return nil unless File.file?(state_path)
+    front = File.read(state_path).match(/\A---\n(.*?)\n---/m)&.[](1)
+    return nil unless front
+    YAML.safe_load(front, permitted_classes: [], aliases: false)["current_feature"]
+  rescue Psych::Exception
+    nil
+  end
+
+  def assert_active_feature!(root, feature)
+    current = active_feature(root)
+    return if current.nil? || current == feature
+    raise ArgumentError, "feature is not active: requested=#{feature}, current=#{current}; bootstrap the feature before writing its requirement graph"
+  end
+
   def empty_graph(feature)
     { "schema_version" => SCHEMA_VERSION, "feature" => feature, "revision" => 0,
       "nodes" => [], "edges" => [], "stale" => [], "views" => {}, "audit" => [] }
@@ -373,15 +390,76 @@ module RequirementGraph
     node["kind"] == "test_case" && node["status"] == "confirmed" && !Array(graph["stale"]).any? { |entry| entry.is_a?(Hash) && entry["node_id"] == node["id"] }
   end
 
+  TEST_PREREQUISITE_FIELDS = %w[acceptance_refs requirement_refs api_refs workload_refs risk_refs metric_refs read_model_refs].freeze
+  CP3_CONFIRMABLE_PREREQUISITE_KINDS = %w[source behavior requirement rule boundary acceptance].freeze
+
+  def test_prerequisite_nodes(graph)
+    by_id = Array(graph["nodes"]).select { |node| node.is_a?(Hash) && node["id"].is_a?(String) }.to_h { |node| [node["id"], node] }
+    ids = Array(graph["nodes"]).select { |node| node.is_a?(Hash) && node["kind"] == "test_case" }.flat_map do |node|
+      data = node["data"].is_a?(Hash) ? node["data"] : {}
+      TEST_PREREQUISITE_FIELDS.flat_map { |field| Array(data[field]) }
+    end.compact.uniq
+
+    # A reviewed TC may point at a requirement whose own source/behavior facts
+    # were introduced by a legacy backfill. Include that small dependency
+    # closure so the user sees every fact that the CP-3 recovery will confirm.
+    queue = ids.dup
+    until queue.empty?
+      node = by_id[queue.shift]
+      next unless node && node["kind"] == "requirement"
+      data = node["data"].is_a?(Hash) ? node["data"] : {}
+      dependencies = Array(data["source_refs"]) + Array(data["behavior_ref"])
+      dependencies.each do |ref|
+        next unless ref.is_a?(String) && !ids.include?(ref)
+        ids << ref
+        queue << ref
+      end
+    end
+    ids.map { |id| by_id[id] }.compact
+  end
+
+  def candidate_test_prerequisites(graph)
+    test_prerequisite_nodes(graph).select { |node| node["status"] != "confirmed" }
+  end
+
+  def confirm_test_prerequisites!(graph, cp_record)
+    candidates = candidate_test_prerequisites(graph)
+    unsupported = candidates.reject { |node| CP3_CONFIRMABLE_PREREQUISITE_KINDS.include?(node["kind"]) }
+    if unsupported.any?
+      return {
+        "ok" => false,
+        "reason" => "test_prerequisite_requires_earlier_gate",
+        "errors" => unsupported.map { |node| "#{node["id"]}: #{node["kind"]} must be confirmed by its owning checkpoint" }
+      }
+    end
+
+    order = { "source" => 0, "behavior" => 1, "rule" => 2, "boundary" => 3, "requirement" => 4, "acceptance" => 5 }
+    confirmed = []
+    candidates.sort_by { |node| [order.fetch(node["kind"], 99), node["id"]] }.each do |node|
+      confirm(graph, node["id"], { "cp_record" => cp_record })
+      confirmed << node["id"]
+    end
+    { "ok" => true, "confirmed_prerequisite_ids" => confirmed }
+  rescue ArgumentError => error
+    { "ok" => false, "reason" => "test_prerequisite_confirmation_failed", "message" => error.message }
+  end
+
   # CP-3 is the single freeze point. Keep it here instead of in a Skill so the
   # graph revision, TC statuses, views and audit entry commit atomically under
   # the caller's control-plane lock.
-  def freeze_test_cases!(root, graph, cp_record)
+  def freeze_test_cases!(root, graph, cp_record, confirm_prerequisites: false, persist: true)
     cases = Array(graph["nodes"]).select { |node| node.is_a?(Hash) && node["kind"] == "test_case" }
     return { "ok" => false, "reason" => "test_suite_empty", "message" => "cannot freeze an empty TC suite" } if cases.empty?
     return { "ok" => false, "reason" => "test_suite_already_frozen", "message" => "confirmed test cases require a new candidate suite" } if cases.any? { |node| node["status"] == "confirmed" }
     return { "ok" => false, "reason" => "test_suite_graph_stale", "message" => "cannot freeze TC suite while the requirement graph has stale downstream nodes" } if Array(graph["stale"]).any?
 
+    prerequisite_confirmation = if confirm_prerequisites
+                                  confirm_test_prerequisites!(graph, cp_record)
+                                else
+                                  { "ok" => true, "confirmed_prerequisite_ids" => [] }
+                                end
+    return prerequisite_confirmation unless prerequisite_confirmation["ok"]
+
     checkers = checker_results(graph)
     errors = checkers.fetch("test-coverage-check", []).dup
     errors.concat(checkers.fetch("test-obligation-check", []))
@@ -395,12 +473,26 @@ module RequirementGraph
       clear_stale_for!(graph, node["id"])
     end
     graph["revision"] += 1
+    event = {
+      "event" => "test_suite_freeze",
+      "node_ids" => cases.map { |node| node["id"] },
+      "confirmed_prerequisite_ids" => prerequisite_confirmation["confirmed_prerequisite_ids"],
+      "cp_record" => cp_record
+    }
+    persist_test_suite_freeze!(root, graph, event) if persist
+    path, = graph_path(root, graph["feature"])
+    { "ok" => true, "path" => path.sub("#{File.realpath(root)}/", ""), "graph_revision" => graph["revision"],
+      "frozen_case_ids" => cases.map { |node| node["id"] },
+      "confirmed_prerequisite_ids" => prerequisite_confirmation["confirmed_prerequisite_ids"],
+      "tests_view" => persist ? graph.dig("views", "tests") : view_payload(graph, "tests"),
+      "audit_event" => event }
+  end
+
+  def persist_test_suite_freeze!(root, graph, event)
     write_views!(root, graph, stale: false)
     path, = graph_path(root, graph["feature"])
-    append_audit!(root, graph, { "event" => "test_suite_freeze", "node_ids" => cases.map { |node| node["id"] }, "cp_record" => cp_record })
+    append_audit!(root, graph, event)
     DevflowControlIO.atomic_write(path, JSON.pretty_generate(graph) + "\n")
-    { "ok" => true, "path" => path.sub("#{File.realpath(root)}/", ""), "graph_revision" => graph["revision"],
-      "frozen_case_ids" => cases.map { |node| node["id"] }, "tests_view" => graph.dig("views", "tests") }
   end
 
   # The matrix compiler is Core-owned and deterministic; this importer is the
@@ -854,6 +946,33 @@ module RequirementGraph
     results
   end
 
+  # Requirement construction deliberately precedes acceptance-test design.
+  # These checkers describe obligations that must be materialized later; they
+  # are diagnostics, not baseline blockers. Keep them explicit in the output
+  # so callers cannot mistake a deferred obligation for a current failure.
+  DEFERRED_CHECKERS = %w[test-coverage-check test-obligation-check].freeze
+
+  def validation_report(graph)
+    checkers = checker_results(graph)
+    blocking = []
+    checkers.each do |id, issues|
+      next if DEFERRED_CHECKERS.include?(id)
+      blocking.concat(issues)
+    end
+    Array(graph["nodes"]).each do |node|
+      next unless node.is_a?(Hash) && high_risk_by_structure?(node)
+      blocking << "#{node["id"]}: derived high-risk node must be confirmed and provable" unless node["status"] == "confirmed"
+    end
+    {
+      "blocking_errors" => blocking.uniq,
+      "deferred_checkers" => DEFERRED_CHECKERS.to_h { |id| [id, Array(checkers[id])] }
+    }
+  end
+
+  def candidate_validation_errors(graph)
+    validation_report(graph).fetch("blocking_errors")
+  end
+
   def validate(graph)
     errors = []
     ids = []
@@ -872,11 +991,7 @@ module RequirementGraph
     # Test coverage becomes enforced only at acceptance-test-design and later
     # workflow steps. Baseline construction itself must remain valid before
     # any derived TC candidates exist.
-    checker_results(graph).reject { |id, _| %w[test-coverage-check test-obligation-check].include?(id) }.each_value { |issues| errors.concat(issues) }
-    Array(graph["nodes"]).each do |node|
-      next unless node.is_a?(Hash) && high_risk_by_structure?(node)
-      errors << "#{node["id"]}: derived high-risk node must be confirmed and provable" unless node["status"] == "confirmed"
-    end
+    errors.concat(validation_report(graph).fetch("blocking_errors"))
     errors.uniq
   end
 
@@ -975,15 +1090,23 @@ if __FILE__ == $PROGRAM_NAME
     opts.on("--json") { options[:json] = true }
   end.parse!
   root = Dir.pwd
+  mutating_command = (%w[propose import-test-cases confirm].include?(command) && options[:write]) || (command == "context" && options[:write])
   lock = %w[propose import-test-cases context confirm].include?(command) && options[:write] ? DevflowControlIO.acquire_project_lock(root) : nil
   begin
+    RequirementGraph.assert_active_feature!(root, options[:feature]) if mutating_command
     graph, path, relative = RequirementGraph.load_graph(root, options[:feature])
     result = case command
              when "inspect"
-               { "ok" => true, "path" => relative, "graph" => graph, "errors" => RequirementGraph.validate(graph), "checkers" => RequirementGraph.checker_results(graph) }
+               report = RequirementGraph.validation_report(graph)
+               { "ok" => report.fetch("blocking_errors").empty?, "path" => relative, "graph" => graph,
+                 "errors" => report.fetch("blocking_errors"), "checkers" => RequirementGraph.checker_results(graph),
+                 "deferred_checkers" => report.fetch("deferred_checkers") }
              when "validate"
-               errors = RequirementGraph.validate(graph)
-               { "ok" => errors.empty?, "path" => relative, "revision" => graph["revision"], "errors" => errors, "checkers" => RequirementGraph.checker_results(graph), "stale" => graph["stale"] }
+               report = RequirementGraph.validation_report(graph)
+               errors = report.fetch("blocking_errors")
+               { "ok" => errors.empty?, "path" => relative, "revision" => graph["revision"], "errors" => errors,
+                 "checkers" => RequirementGraph.checker_results(graph), "deferred_checkers" => report.fetch("deferred_checkers"),
+                 "stale" => graph["stale"] }
              when "context"
                if options[:read]
                  pkg = RequirementGraph.load_context_package(root, graph["feature"], options[:slice_id])
@@ -1019,7 +1142,8 @@ if __FILE__ == $PROGRAM_NAME
                    RequirementGraph.append_audit!(root, candidate, { "event" => "graph_delta", "operation" => applied["operation"], "node_id" => applied.dig("node", "id"), "stale_count" => Array(applied["stale"]).length })
                    DevflowControlIO.atomic_write(path, JSON.pretty_generate(candidate) + "\n")
                  end
-                 { "ok" => true, "path" => relative, "written" => options[:write], "revision" => options[:write] ? candidate["revision"] : graph["revision"], "applied" => applied, "validation_errors" => RequirementGraph.validate(candidate), "checkers" => RequirementGraph.checker_results(candidate), "views" => candidate["views"] }
+                 report = RequirementGraph.validation_report(candidate)
+                 { "ok" => true, "path" => relative, "written" => options[:write], "revision" => options[:write] ? candidate["revision"] : graph["revision"], "applied" => applied, "validation_errors" => report.fetch("blocking_errors"), "checkers" => RequirementGraph.checker_results(candidate), "deferred_checkers" => report.fetch("deferred_checkers"), "views" => candidate["views"] }
                end
              when "import-test-cases"
                raise ArgumentError, "--write is required" unless options[:write]
@@ -1045,7 +1169,8 @@ if __FILE__ == $PROGRAM_NAME
                  RequirementGraph.write_views!(root, graph, stale: stale)
                  RequirementGraph.append_audit!(root, graph, { "event" => "graph_confirm", "node_id" => options[:node_id] })
                  DevflowControlIO.atomic_write(path, JSON.pretty_generate(graph) + "\n")
-                 { "ok" => true, "path" => relative, "revision" => graph["revision"], "applied" => applied, "validation_errors" => RequirementGraph.validate(graph), "checkers" => RequirementGraph.checker_results(graph), "views" => graph["views"] }
+                 report = RequirementGraph.validation_report(graph)
+                 { "ok" => true, "path" => relative, "revision" => graph["revision"], "applied" => applied, "validation_errors" => report.fetch("blocking_errors"), "checkers" => RequirementGraph.checker_results(graph), "deferred_checkers" => report.fetch("deferred_checkers"), "views" => graph["views"] }
                end
              else
                { "ok" => false, "reason" => "invalid_command", "message" => "command must be propose, import-test-cases, inspect, validate, context, or confirm" }

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

@@ -0,0 +1,143 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Core-owned, idempotent requirement-graph backfill. Renumbers existing node
+# IDs (and every in-graph string reference to them), appends seed nodes/edges,
+# then regenerates all derived views through the same writer the graph normally
+# uses. It never hand-edits JSON: every mutation happens under the project lock
+# and is persisted via DevflowControlIO.atomic_write.
+require "json"
+require "optparse"
+require "set"
+require_relative "requirement_graph"
+require_relative "control_io"
+
+options = { root: ".", feature: nil, seed: nil, write: false, json: false }
+OptionParser.new do |opts|
+  opts.banner = "Usage: requirement_graph_backfill.rb --feature NAME --seed PATH [--write]"
+  opts.on("--root PATH") { |value| options[:root] = value }
+  opts.on("--feature NAME") { |value| options[:feature] = value }
+  opts.on("--seed PATH") { |value| options[:seed] = value }
+  opts.on("--write") { options[:write] = true }
+  opts.on("--json") { options[:json] = true }
+end.parse!
+
+def deep_replace(value, from, to)
+  case value
+  when Hash
+    value.each { |key, item| value[key] = deep_replace(item, from, to) }
+    value
+  when Array
+    value.map { |item| deep_replace(item, from, to) }
+  when String
+    value.include?(from) ? value.gsub(from, to) : value
+  else
+    value
+  end
+end
+
+root = File.realpath(options[:root])
+lock = options[:write] ? DevflowControlIO.acquire_project_lock(root) : nil
+
+begin
+  raise ArgumentError, "--feature is required" if options[:feature].to_s.empty?
+  raise ArgumentError, "--seed is required" if options[:seed].to_s.empty?
+  seed_path = File.expand_path(options[:seed], root)
+  raise ArgumentError, "seed file is missing: #{options[:seed]}" unless File.file?(seed_path)
+
+  seed = JSON.parse(File.read(seed_path))
+  raise ArgumentError, "seed must be an object" unless seed.is_a?(Hash)
+  renumber = seed["renumber"] || {}
+  raise ArgumentError, "renumber must be an object" unless renumber.is_a?(Hash)
+  new_nodes = seed["nodes"] || []
+  new_edges = seed["edges"] || []
+  raise ArgumentError, "nodes must be an array" unless new_nodes.is_a?(Array)
+  raise ArgumentError, "edges must be an array" unless new_edges.is_a?(Array)
+
+  graph, path, relative = RequirementGraph.load_graph(root, options[:feature])
+  existing_ids = graph["nodes"].map { |node| node["id"] }.to_set
+
+  # 1. Renumber: update the node id and every string reference (data, confirmation, edges).
+  renumber.each do |from, to|
+    raise ArgumentError, "renumber key is invalid: #{from}" unless from.is_a?(String) && from.match?(/\A[A-Z][A-Z0-9_]*-\d+\z/)
+    raise ArgumentError, "renumber target is invalid: #{to}" unless to.is_a?(String) && to.match?(/\A[A-Z][A-Z0-9_]*-\d+\z/)
+    raise ArgumentError, "renumber source node not found: #{from}" unless existing_ids.include?(from)
+    raise ArgumentError, "renumber target already exists: #{to}" if existing_ids.include?(to)
+    graph["nodes"].each do |node|
+      node["data"] = deep_replace(node["data"], from, to) if node["data"].is_a?(Hash)
+      node["confirmation"] = deep_replace(node["confirmation"], from, to) if node["confirmation"].is_a?(Hash)
+      node["id"] = to if node["id"] == from
+    end
+    graph["edges"].each do |edge|
+      edge["from"] = to if edge["from"] == from
+      edge["to"] = to if edge["to"] == from
+    end
+    existing_ids = graph["nodes"].map { |node| node["id"] }.to_set
+  end
+
+  # Fingerprints are content-addressed; recompute after the renumber mutates data.
+  graph["nodes"].each { |node| RequirementGraph.set_node_fingerprint!(node) }
+
+  # 2. Append seed nodes with explicit IDs (idempotency: refuse duplicates).
+  new_nodes.each do |node|
+    raise ArgumentError, "seed node must be an object" unless node.is_a?(Hash)
+    id = node["id"]
+    kind = node["kind"]
+    raise ArgumentError, "seed node requires id and kind" unless id.is_a?(String) && !id.empty? && kind.is_a?(String)
+    raise ArgumentError, "seed node kind is unsupported: #{kind}" unless RequirementGraph::KINDS.key?(kind)
+    raise ArgumentError, "seed node id already exists: #{id}" if existing_ids.include?(id)
+    node["status"] = "candidate" unless %w[candidate confirmed].include?(node["status"])
+    node["data"] = {} unless node["data"].is_a?(Hash)
+    RequirementGraph.set_node_fingerprint!(node)
+    graph["nodes"] << node
+    existing_ids << id
+  end
+
+  # 3. Append edges, deduping against the existing edge set.
+  graph["edges"] = graph["edges"].uniq { |edge| [edge["from"], edge["to"], edge["relation"]] }
+  edge_added = 0
+  new_edges.each do |edge|
+    raise ArgumentError, "seed edge must be an object" unless edge.is_a?(Hash)
+    %w[from to relation].each do |key|
+      raise ArgumentError, "seed edge requires #{key}" unless edge[key].is_a?(String) && !edge[key].empty?
+    end
+    raise ArgumentError, "seed edge from/to must reference known nodes" unless existing_ids.include?(edge["from"]) && existing_ids.include?(edge["to"])
+    next if graph["edges"].any? { |existing| existing["from"] == edge["from"] && existing["to"] == edge["to"] && existing["relation"] == edge["relation"] }
+
+    graph["edges"] << edge
+    edge_added += 1
+  end
+
+  # 4. Advance the graph revision once for the whole backfill.
+  graph["revision"] = graph["revision"].to_i + 1
+
+  # 5. Regenerate derived views and persist under the project lock.
+  if options[:write]
+    stale = Array(graph["stale"]).any?
+    RequirementGraph.write_views!(root, graph, stale: stale)
+    RequirementGraph.append_audit!(root, graph, {
+      "event" => "graph_backfill",
+      "renumber" => renumber,
+      "added_node_ids" => new_nodes.map { |node| node["id"] },
+      "added_edge_count" => edge_added
+    })
+    DevflowControlIO.atomic_write(path, JSON.pretty_generate(graph) + "\n")
+  end
+
+  result = {
+    "ok" => true,
+    "written" => options[:write],
+    "path" => relative,
+    "revision" => graph["revision"],
+    "renumber" => renumber,
+    "added_node_ids" => new_nodes.map { |node| node["id"] },
+    "added_edge_count" => edge_added,
+    "validation_errors" => RequirementGraph.validate(graph)
+  }
+  puts JSON.pretty_generate(result)
+rescue ArgumentError, JSON::ParserError => error
+  puts JSON.pretty_generate({ "ok" => false, "reason" => "requirement_graph_backfill_failed", "message" => error.message })
+  exit 1
+ensure
+  DevflowControlIO.release_lock(lock)
+end

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

@@ -13,6 +13,7 @@ require "securerandom"
 require "time"
 require "yaml"
 require_relative "control_io"
+require_relative "parallel_run"
 
 DEFAULT_LEASE_SECONDS = 60
 options = { json: false, write: false, lease_seconds: DEFAULT_LEASE_SECONDS }
@@ -46,6 +47,15 @@ def write_state(path, state, previous)
   DevflowControlIO.atomic_write(path, "---\n#{front}---\n#{body}")
 end
 
+def rebase_parallel_run(root, state, lock)
+  feature = state["current_feature"]
+  return if feature.to_s.empty?
+
+  ParallelRun.rebase_state_revision(
+    root: root, feature: feature, state_revision: state.fetch("revision"), lock: lock
+  )
+end
+
 def valid_session_id?(value)
   value.is_a?(String) && value.match?(/\A[A-Za-z0-9][A-Za-z0-9._:-]{0,255}\z/)
 end
@@ -151,6 +161,7 @@ result = catch(:transition_done) do
       }
       state["revision"] = revision + 1
       write_state(state_path, state, raw)
+      rebase_parallel_run(root, state, lock)
     end
     result = { "ok" => true, "written" => options[:write], "rollover" => options[:write] ? state["rollover"] : payload.merge("handoff_sha256" => digest), "revision" => options[:write] ? revision + 1 : revision }
   when "claim"
@@ -178,7 +189,7 @@ result = catch(:transition_done) do
     end
     if options[:write]
       rollover["status"] = "claimed"; rollover["target_session_id"] = options[:target_session_id]; rollover["claimed_at"] = iso_now; rollover["lease_expires_at"] = lease_expiry(options[:lease_seconds])
-      state["rollover"] = rollover; state["revision"] = revision + 1; write_state(state_path, state, raw)
+      state["rollover"] = rollover; state["revision"] = revision + 1; write_state(state_path, state, raw); rebase_parallel_run(root, state, lock)
     end
     result = { "ok" => true, "written" => options[:write], "rollover" => rollover, "revision" => options[:write] ? revision + 1 : revision }
   when "renew"
@@ -194,7 +205,7 @@ result = catch(:transition_done) do
     if options[:write]
       rollover["lease_expires_at"] = lease_expiry(options[:lease_seconds])
       rollover["last_renewed_at"] = iso_now
-      state["rollover"] = rollover; state["revision"] = revision + 1; write_state(state_path, state, raw)
+      state["rollover"] = rollover; state["revision"] = revision + 1; write_state(state_path, state, raw); rebase_parallel_run(root, state, lock)
     end
     result = { "ok" => true, "written" => options[:write], "rollover" => rollover, "revision" => options[:write] ? revision + 1 : revision }
   when "recover"
@@ -214,7 +225,7 @@ result = catch(:transition_done) do
     end
     if options[:write]
       rollover["status"] = "prepared"; rollover["target_session_id"] = nil; rollover["claimed_at"] = nil; rollover.delete("lease_expires_at"); rollover.delete("last_renewed_at")
-      state["rollover"] = rollover; state["revision"] = revision + 1; write_state(state_path, state, raw)
+      state["rollover"] = rollover; state["revision"] = revision + 1; write_state(state_path, state, raw); rebase_parallel_run(root, state, lock)
     end
     result = { "ok" => true, "written" => options[:write], "rollover" => rollover, "revision" => options[:write] ? revision + 1 : revision }
   when "consume"
@@ -228,7 +239,7 @@ result = catch(:transition_done) do
     end
     if options[:write]
       rollover["status"] = "consumed"; rollover["consumed_at"] = iso_now
-      state["rollover"] = rollover; state["revision"] = revision + 1; write_state(state_path, state, raw)
+      state["rollover"] = rollover; state["revision"] = revision + 1; write_state(state_path, state, raw); rebase_parallel_run(root, state, lock)
     end
     result = { "ok" => true, "written" => options[:write], "rollover" => rollover, "revision" => options[:write] ? revision + 1 : revision }
   else

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

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "date"
+require "digest"
 require "fileutils"
 require "json"
 require "optparse"
@@ -109,6 +110,40 @@ def content_validity(root, path, checks)
   { "valid" => issues.empty?, "issues" => issues }
 end
 
+def questions_registry_entry(root, state, existing_by_path)
+  feature = state.fetch("current_feature", "").to_s
+  path = ".planning/features/#{feature}/questions.yaml"
+  absolute, = DevflowControlIO.resolve_control_path(root, path, :artifact)
+  exists = File.exist?(absolute)
+  entry = {
+    "path" => path,
+    "type" => "wireframe-questions",
+    "workflow_step" => "wireframe-proposal",
+    "produced_by" => "wireframe Skill",
+    "status" => "candidate",
+    "exists" => exists,
+    "content_valid" => false,
+    "content_issues" => exists ? nil : ["file_missing"],
+    "questions_status" => exists ? "present" : "unavailable"
+  }
+  if exists
+    entry["fingerprint"] = "sha256:#{Digest::SHA256.file(absolute).hexdigest}"
+    begin
+      questions = load_yaml_file(absolute)
+      list = questions.is_a?(Hash) ? Array(questions["questions"]) : []
+      entry["unresolved_count"] = list.count do |question|
+        question.is_a?(Hash) && question["kind"] == "blocking" && question["status"] == "open"
+      end
+      entry["content_valid"] = true
+      entry.delete("content_issues")
+    rescue StandardError => error
+      entry["questions_status"] = "invalid"
+      entry["content_issues"] = ["yaml_parse_error:#{error.message}"]
+    end
+  end
+  entry
+end
+
 artifacts = collect_outputs(workflow).map do |step, output|
   path = interpolate_path(output.fetch("path"), state)
   existing = existing_by_path[path] || {}
@@ -145,6 +180,15 @@ artifacts = collect_outputs(workflow).map do |step, output|
   }.reject { |_, value| value.nil? || value == [] }
 end
 
+questions_path = ".planning/features/#{state.fetch("current_feature", "")}/questions.yaml"
+questions_entry = questions_registry_entry(root, state, existing_by_path)
+question_index = artifacts.index { |artifact| artifact["path"] == questions_path }
+if question_index
+  artifacts[question_index] = questions_entry
+else
+  artifacts << questions_entry
+end
+
 registry = {
   "schema_version" => 1,
   "state_revision" => state.fetch("revision", 0),
@@ -154,7 +198,7 @@ registry = {
     "feature" => state["current_feature"],
     "phase" => state["current_phase"]
   },
-  "status_values" => %w[planned generated approved completed passed pending_rerun stale failed],
+  "status_values" => %w[planned generated candidate approved completed passed pending_rerun stale failed],
   "artifacts" => artifacts
 }
 

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

@@ -9,9 +9,11 @@ require_relative "control_io"
 require_relative "phase_ownership"
 require_relative "requirement_graph"
 require_relative "architecture_feasibility"
+require_relative "architecture_brief"
 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 +82,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 +275,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)
@@ -665,7 +741,15 @@ unless %w[prepared claimed consumed superseded failed].include?(status)
 
     graph, = RequirementGraph.load_graph(root, feature)
     if brief["graph_revision"] != graph["revision"]
-      issues << issue("error", "architecture_brief_graph_stale", "Architecture brief was derived from a stale graph revision", step: step["id"], brief_revision: brief["graph_revision"], graph_revision: graph["revision"])
+      brief_markdown_path = File.join(root, ".planning", "features", feature, "architecture-brief.md")
+      current_markdown = ArchitectureBrief.build(root, feature)[3]
+      normalize_revision = lambda do |markdown|
+        markdown.to_s.gsub(/需求图谱：schema v(\d+) \/ revision \d+/, '需求图谱：schema v\1 / revision <current>')
+      end
+      semantically_current = File.file?(brief_markdown_path) && normalize_revision.call(File.read(brief_markdown_path)) == normalize_revision.call(current_markdown)
+      unless semantically_current
+        issues << issue("error", "architecture_brief_graph_stale", "Architecture brief inputs changed after it was derived", step: step["id"], brief_revision: brief["graph_revision"], graph_revision: graph["revision"])
+      end
     end
     current_context = ArchitectureFeasibility.safe_static_context(root)
     current_context_revision = current_context["available"] ? current_context["snapshot_revision"] : nil