@guanlin4924/devflow-pi 0.1.15 → 0.1.16

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

@@ -0,0 +1,471 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Core-owned requirement governance graph. Skills may submit a bounded delta,
+# but only this writer assigns IDs, computes fingerprints/impact, and persists
+# canonical graph and derived views under the project-wide control-plane lock.
+require "digest"
+require "json"
+require "optparse"
+require "pathname"
+require "set"
+require_relative "control_io"
+
+module RequirementGraph
+  SCHEMA_VERSION = 2
+  ROOT = ".planning/requirements"
+  KINDS = {
+    "source" => "SRC", "code" => "CODE", "term" => "TERM", "object" => "OBJECT",
+    "behavior" => "BEH", "requirement" => "REQ", "rule" => "BR", "boundary" => "BC",
+    "slice" => "SL", "risk" => "RISK", "decision" => "DECISION", "acceptance" => "AC",
+    "api" => "API"
+  }.freeze
+  VIEW_NAMES = %w[evidence definitions behavior-graph requirement-graph slices acceptance traceability].freeze
+  FEATURE_INVALID = /[\\\/\x00-\x1F\x7F]/
+  RESERVED_KEYS = %w[id status revision passed confirmed graph_revision stale_fingerprint severity risk_level priority p0 high_risk].freeze
+
+  module_function
+
+  def valid_feature?(value)
+    value.is_a?(String) && !value.strip.empty? && !value.match?(FEATURE_INVALID)
+  end
+
+  def graph_path(root, feature)
+    raise ArgumentError, "invalid feature" unless valid_feature?(feature)
+    relative = File.join(ROOT, feature, "governance.json")
+    absolute = File.expand_path(relative, root)
+    root_real = File.realpath(root)
+    raise ArgumentError, "graph path escapes project root" unless absolute.start_with?("#{root_real}#{File::SEPARATOR}")
+    [absolute, relative]
+  end
+
+  def feature_dir(root, feature)
+    path, = graph_path(root, feature)
+    File.dirname(path)
+  end
+
+  def empty_graph(feature)
+    { "schema_version" => SCHEMA_VERSION, "feature" => feature, "revision" => 0,
+      "nodes" => [], "edges" => [], "stale" => [], "views" => {}, "audit" => [] }
+  end
+
+  def canonical_json(value)
+    JSON.generate(value)
+  end
+
+  def fingerprint(value)
+    Digest::SHA256.hexdigest(canonical_json(value))
+  end
+
+  def normalize_legacy_graph(graph)
+    graph["schema_version"] = SCHEMA_VERSION
+    graph["views"] ||= {}
+    graph["audit"] ||= []
+    graph["stale"] = Array(graph["stale"]).map do |entry|
+      entry.is_a?(Hash) ? entry : { "node_id" => entry.to_s, "state" => "needs_recheck", "reason" => "legacy_unknown" }
+    end
+    Array(graph["nodes"]).each { |node| node["fingerprint"] ||= fingerprint(node.reject { |key, _| key == "fingerprint" }) if node.is_a?(Hash) }
+    graph
+  end
+
+  def load_graph(root, feature)
+    path, relative = graph_path(root, feature)
+    return [empty_graph(feature), path, relative] unless File.exist?(path)
+    parsed = JSON.parse(File.read(path))
+    valid_shape = parsed.is_a?(Hash) && [1, SCHEMA_VERSION].include?(parsed["schema_version"]) && parsed["feature"] == feature &&
+                  parsed["revision"].is_a?(Integer) && parsed["nodes"].is_a?(Array) && parsed["edges"].is_a?(Array) && parsed["stale"].is_a?(Array)
+    raise ArgumentError, "invalid governance graph" unless valid_shape
+    [normalize_legacy_graph(parsed), path, relative]
+  rescue JSON::ParserError
+    raise ArgumentError, "invalid governance graph"
+  end
+
+  def contains_reserved_key?(value)
+    case value
+    when Hash
+      value.any? { |key, child| RESERVED_KEYS.include?(key.to_s) || contains_reserved_key?(child) }
+    when Array then value.any? { |child| contains_reserved_key?(child) }
+    else false
+    end
+  end
+
+  def normalize_data(value)
+    raise ArgumentError, "delta data must be an object" unless value.is_a?(Hash)
+    raise ArgumentError, "delta data cannot set reserved keys: #{RESERVED_KEYS.join(", ")}" if contains_reserved_key?(value)
+    value
+  end
+
+  def next_id(graph, prefix)
+    maximum = graph["nodes"].map do |node|
+      match = node.is_a?(Hash) && node["id"].is_a?(String) ? node["id"].match(/\A#{Regexp.escape(prefix)}-(\d+)\z/) : nil
+      match && match[1].to_i
+    end.compact.max || 0
+    format("%s-%04d", prefix, maximum + 1)
+  end
+
+  def node_ids(graph)
+    graph["nodes"].map { |node| node["id"] if node.is_a?(Hash) && node["id"].is_a?(String) }.compact.to_set
+  end
+
+  def set_node_fingerprint!(node)
+    node["fingerprint"] = fingerprint(node.reject { |key, _| key == "fingerprint" })
+  end
+
+  def downstream(graph, id, mode)
+    direct = Array(graph["edges"]).map { |edge| edge["to"] if edge.is_a?(Hash) && edge["from"] == id }.compact
+    return direct.uniq if mode == "one_hop"
+    seen = Set.new([id])
+    queue = direct.dup
+    result = []
+    until queue.empty?
+      current = queue.shift
+      next if seen.include?(current)
+      seen << current
+      result << current
+      Array(graph["edges"]).each { |edge| queue << edge["to"] if edge.is_a?(Hash) && edge["from"] == current }
+    end
+    result
+  end
+
+  def mark_stale!(graph, upstream, affected)
+    affected.each do |node_id|
+      node = Array(graph["nodes"]).find { |entry| entry.is_a?(Hash) && entry["id"] == node_id }
+      graph["stale"] << { "node_id" => node_id, "state" => "needs_recheck", "reason" => "upstream_changed",
+                            "upstream" => upstream, "stale_fingerprint" => node && node["fingerprint"] }
+    end
+    graph["stale"].uniq! { |entry| [entry["node_id"], entry["upstream"], entry["stale_fingerprint"]] }
+    graph["stale"].each { |entry| entry["graph_revision"] = graph["revision"] + 1 }
+  end
+
+  # Re-submitting a changed downstream node is the explicit Core-mediated
+  # acknowledgement that its stale fingerprint was reviewed. It may itself
+  # invalidate later consumers, so only that node's stale marker is cleared.
+  def clear_stale_for!(graph, node_id)
+    graph["stale"].reject! { |entry| entry.is_a?(Hash) && entry["node_id"] == node_id }
+  end
+
+  def proposal(graph, delta, allowed_kinds = nil)
+    raise ArgumentError, "delta must be an object" unless delta.is_a?(Hash)
+    case delta["op"]
+    when "add"
+      kind = delta["kind"]
+      prefix = KINDS[kind]
+      raise ArgumentError, "unsupported node kind" unless prefix
+      raise ArgumentError, "node kind #{kind} is not allowed by the execution contract" if allowed_kinds && !allowed_kinds.include?(kind)
+      data = normalize_data(delta["data"])
+      node = { "id" => next_id(graph, prefix), "kind" => kind, "status" => "candidate", "data" => data }
+      set_node_fingerprint!(node)
+      graph["nodes"] << node
+      { "operation" => "add", "node" => node }
+    when "link"
+      from, to, relation = delta.values_at("from", "to", "relation")
+      raise ArgumentError, "link requires known from/to IDs" unless from.is_a?(String) && to.is_a?(String) && node_ids(graph).include?(from) && node_ids(graph).include?(to)
+      raise ArgumentError, "link relation is required" unless relation.is_a?(String) && relation.match?(/\A[a-z][a-z0-9_-]{0,63}\z/)
+      edge = { "from" => from, "to" => to, "relation" => relation }
+      raise ArgumentError, "duplicate graph edge" if graph["edges"].include?(edge)
+      graph["edges"] << edge
+      { "operation" => "link", "edge" => edge }
+    when "update"
+      id = delta["id"]
+      node = Array(graph["nodes"]).find { |entry| entry.is_a?(Hash) && entry["id"] == id }
+      raise ArgumentError, "update requires a known node id" unless node
+      data = normalize_data(delta["data"])
+      node["data"] = node.fetch("data", {}).merge(data)
+      set_node_fingerprint!(node)
+      clear_stale_for!(graph, id)
+      mode = delta["propagation"] || "full"
+      raise ArgumentError, "propagation must be one_hop or full" unless %w[one_hop full].include?(mode)
+      affected = downstream(graph, id, mode)
+      mark_stale!(graph, id, affected)
+      { "operation" => "update", "node" => node, "stale" => affected, "propagation" => mode }
+    else
+      raise ArgumentError, "delta op must be add, link, or update"
+    end
+  end
+
+  # Core-only 审核转换：candidate → confirmed，要求人工 CP 记录或运行证据。
+  def confirm(graph, node_id, evidence)
+    node = Array(graph["nodes"]).find { |entry| entry.is_a?(Hash) && entry["id"] == node_id }
+    raise ArgumentError, "confirm requires a known node id" unless node
+    raise ArgumentError, "node is already confirmed" if node["status"] == "confirmed"
+    unless evidence.is_a?(Hash) && (evidence["cp_record"] || evidence["evidence_ref"])
+      raise ArgumentError, "confirm requires cp_record or evidence_ref"
+    end
+    node["status"] = "confirmed"
+    node["confirmation"] = { "origin" => "core", "evidence" => evidence }
+    set_node_fingerprint!(node)
+    clear_stale_for!(graph, node_id)
+    { "operation" => "confirm", "node" => node }
+  end
+
+  def present?(value)
+    !(value.nil? || (value.respond_to?(:empty?) && value.empty?))
+  end
+
+  # 风险等级不是模型可填写的枚举，而由 Core 从图谱结构事实推导。
+  def high_risk_by_structure?(node)
+    data = node["data"].is_a?(Hash) ? node["data"] : {}
+    if node["kind"] == "behavior"
+      has_writes = present?(data["writes"]) || present?(data["side_effects"])
+      return true if has_writes && !present?(data["recovery_strategy"])
+      return true if data["concurrent"] == true && !present?(data["concurrency_control"])
+    end
+    if %w[requirement slice].include?(node["kind"])
+      scope = data["data_scope"]
+      return true if scope.is_a?(String) && !%w[current_org_only self self_only].include?(scope)
+    end
+    false
+  end
+
+  def derived_high_risk_ids(graph)
+    Array(graph["nodes"]).select { |node| node.is_a?(Hash) && high_risk_by_structure?(node) }.map { |node| node["id"] }
+  end
+
+  def required(errors, node, keys)
+    keys.each { |key| errors << "#{node["id"]}: missing #{key}" unless present?(node.dig("data", key)) }
+  end
+
+  def refs_known?(graph, refs, prefixes)
+    known = node_ids(graph)
+    Array(refs).all? { |ref| ref.is_a?(String) && known.include?(ref) && prefixes.any? { |prefix| ref.start_with?("#{prefix}-") } }
+  end
+
+  def confirmed?(graph, id)
+    node = Array(graph["nodes"]).find { |entry| entry.is_a?(Hash) && entry["id"] == id }
+    !node.nil? && node["status"] == "confirmed"
+  end
+
+  def checker_results(graph)
+    results = {
+      "requirement-graph-check" => [], "slice-independence-check" => [], "contract-coverage-check" => [],
+      "change-impact-check" => [], "acceptance-coverage-check" => [], "risk-derivation-check" => []
+    }
+    Array(graph["nodes"]).each do |node|
+      next unless node.is_a?(Hash)
+      case node["kind"]
+      when "requirement"
+        required(results["requirement-graph-check"], node, %w[source_refs outcome actor_and_authority data_scope behavior_ref failure_refs acceptance_refs])
+        results["requirement-graph-check"] << "#{node["id"]}: source_refs must reference SRC/CODE nodes" unless refs_known?(graph, node.dig("data", "source_refs"), %w[SRC CODE])
+        results["requirement-graph-check"] << "#{node["id"]}: behavior_ref must reference BEH" unless refs_known?(graph, [node.dig("data", "behavior_ref")], ["BEH"])
+        results["requirement-graph-check"] << "#{node["id"]}: acceptance_refs must reference AC" unless refs_known?(graph, node.dig("data", "acceptance_refs"), ["AC"])
+        if node["status"] == "confirmed"
+          Array(node.dig("data", "source_refs")).each do |ref|
+            results["requirement-graph-check"] << "#{node["id"]}: source_ref #{ref} must be confirmed before backing a confirmed requirement" unless confirmed?(graph, ref)
+          end
+          beh = node.dig("data", "behavior_ref")
+          results["requirement-graph-check"] << "#{node["id"]}: behavior_ref #{beh} must be confirmed" if beh && !confirmed?(graph, beh)
+        end
+      when "behavior"
+        required(results["requirement-graph-check"], node, %w[trigger actor_and_authority preconditions state_transition invariants writes side_effects failure_paths recovery_strategy])
+      when "slice"
+        required(results["slice-independence-check"], node, %w[outcome state_change actor_and_authority data_scope reads writes side_effects dependencies acceptance_refs])
+        results["slice-independence-check"] << "#{node["id"]}: technical_only slice is not an independently verifiable business result" if node.dig("data", "technical_only") == true
+      when "api"
+        required(results["contract-coverage-check"], node, %w[request response errors permission data_scope compatibility behavior_ref requirement_refs])
+        results["contract-coverage-check"] << "#{node["id"]}: behavior_ref must reference BEH" unless refs_known?(graph, [node.dig("data", "behavior_ref")], ["BEH"])
+        results["contract-coverage-check"] << "#{node["id"]}: requirement_refs must reference REQ" unless refs_known?(graph, node.dig("data", "requirement_refs"), ["REQ"])
+      when "acceptance"
+        required(results["acceptance-coverage-check"], node, %w[requirement_ref verification_types])
+        types = Array(node.dig("data", "verification_types"))
+        req = Array(graph["nodes"]).find { |entry| entry.is_a?(Hash) && entry["id"] == node.dig("data", "requirement_ref") }
+        if req && high_risk_by_structure?(req)
+          missing = %w[business contract resilience] - types
+          results["acceptance-coverage-check"] << "#{node["id"]}: high-risk acceptance missing #{missing.join(", ")}" if missing.any?
+        end
+      end
+    end
+    stale = Array(graph["stale"])
+    results["change-impact-check"] << "#{stale.length} downstream nodes need recheck" if stale.any?
+    Array(graph["nodes"]).each do |node|
+      next unless node.is_a?(Hash)
+      data = node["data"].is_a?(Hash) ? node["data"] : {}
+      %w[severity risk_level priority p0 high_risk].each do |key|
+        results["risk-derivation-check"] << "#{node["id"]}: #{key} must be Core-derived, not model-authored" if data.key?(key)
+      end
+    end
+    derived = derived_high_risk_ids(graph)
+    results["risk-derivation-check"] << "derived high-risk nodes: #{derived.join(", ")}" unless derived.empty?
+    results
+  end
+
+  def validate(graph)
+    errors = []
+    ids = []
+    Array(graph["nodes"]).each do |node|
+      unless node.is_a?(Hash) && node["id"].is_a?(String) && KINDS.key?(node["kind"]) && %w[candidate confirmed].include?(node["status"]) && node["data"].is_a?(Hash)
+        errors << "invalid node"
+        next
+      end
+      ids << node["id"]
+    end
+    errors << "duplicate node ids" unless ids.uniq.length == ids.length
+    known = ids.to_set
+    Array(graph["edges"]).each do |edge|
+      errors << "invalid edge" unless edge.is_a?(Hash) && known.include?(edge["from"]) && known.include?(edge["to"]) && edge["relation"].is_a?(String)
+    end
+    checker_results(graph).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.uniq
+  end
+
+  def view_payload(graph, name)
+    kinds = case name
+            when "evidence" then %w[source code]
+            when "definitions" then %w[term object rule boundary]
+            when "behavior-graph" then %w[behavior]
+            when "requirement-graph", "traceability" then %w[requirement rule boundary api]
+            when "slices" then %w[slice]
+            when "acceptance" then %w[acceptance risk decision]
+            else []
+            end
+    nodes = Array(graph["nodes"]).select { |node| kinds.include?(node["kind"]) }
+    { "schema_version" => 2, "origin" => "core_requirement_graph", "feature" => graph["feature"], "graph_revision" => graph["revision"],
+      "view" => name, "nodes" => nodes, "edges" => Array(graph["edges"]).select { |edge| nodes.any? { |node| node["id"] == edge["from"] || node["id"] == edge["to"] } } }
+  end
+
+  def write_views!(root, graph, stale: false)
+    directory = feature_dir(root, graph["feature"])
+    graph["views"] ||= {}
+    VIEW_NAMES.each do |name|
+      payload = view_payload(graph, name)
+      path = File.join(directory, "#{name}.json")
+      prior = graph["views"][name] || {}
+      state = stale ? "stale" : "fresh"
+      meta = { "path" => File.join(ROOT, graph["feature"], "#{name}.json"), "fingerprint" => fingerprint(payload),
+               "graph_revision" => graph["revision"], "state" => state, "needs_recheck" => stale,
+               "stale_fingerprint" => stale ? prior["fingerprint"] : nil }.compact
+      graph["views"][name] = meta
+      payload["view_meta"] = meta
+      DevflowControlIO.atomic_write(path, JSON.pretty_generate(payload) + "\n")
+    end
+    meta = { "schema_version" => 2, "feature" => graph["feature"], "graph_revision" => graph["revision"],
+             "content_fingerprint" => fingerprint(graph.reject { |key, _| %w[views audit].include?(key) }), "views" => graph["views"], "stale" => graph["stale"] }
+    DevflowControlIO.atomic_write(File.join(directory, "graph.meta.json"), JSON.pretty_generate(meta) + "\n")
+  end
+
+  def append_audit!(root, graph, event)
+    event = event.merge("schema_version" => 2, "origin" => "core_requirement_graph", "graph_revision" => graph["revision"])
+    graph["audit"] << event
+    graph["audit"] = graph["audit"].last(200)
+    path = File.join(feature_dir(root, graph["feature"]), "control-events.jsonl")
+    existing = File.exist?(path) ? File.read(path) : ""
+    DevflowControlIO.atomic_write(path, existing + JSON.generate(event) + "\n")
+  end
+
+  def context(graph, slice_id)
+    raise ArgumentError, "slice_id is required" unless slice_id.is_a?(String) && slice_id.match?(/\ASL-\d+\z/)
+    ids = Set.new([slice_id])
+    Array(graph["edges"]).each do |edge|
+      next unless edge.is_a?(Hash)
+      ids << edge["to"] if edge["from"] == slice_id
+      ids << edge["from"] if edge["to"] == slice_id
+    end
+    nodes = Array(graph["nodes"]).select { |node| ids.include?(node["id"]) }
+    payload = { "schema_version" => 2, "origin" => "core_requirement_graph", "feature" => graph["feature"], "graph_revision" => graph["revision"],
+                "slice_id" => slice_id, "nodes" => nodes, "edges" => Array(graph["edges"]).select { |edge| ids.include?(edge["from"]) && ids.include?(edge["to"]) } }
+    payload["fingerprint"] = fingerprint(payload)
+    payload
+  end
+
+  # 消费者读已持久化 L2 包并强制校验 revision/fingerprint。
+  def load_context_package(root, feature, slice_id)
+    directory = File.join(feature_dir(root, feature), "context")
+    path = File.join(directory, "#{slice_id}.json")
+    return nil unless File.exist?(path)
+    JSON.parse(File.read(path))
+  rescue JSON::ParserError
+    nil
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  options = { feature: nil, expected_revision: nil, delta_json: nil, slice_id: nil, node_id: nil, evidence_json: nil, allowed_kinds: nil, write: false, read: false, json: false }
+  command = ARGV.shift
+  OptionParser.new do |opts|
+    opts.banner = "Usage: requirement_graph.rb propose|inspect|validate|context --feature NAME [options]"
+    opts.on("--feature NAME") { |value| options[:feature] = value }
+    opts.on("--expected-revision N", Integer) { |value| options[:expected_revision] = value }
+    opts.on("--delta-json JSON") { |value| options[:delta_json] = value }
+    opts.on("--slice-id ID") { |value| options[:slice_id] = value }
+    opts.on("--node-id ID") { |value| options[:node_id] = value }
+    opts.on("--evidence-json JSON") { |value| options[:evidence_json] = value }
+    opts.on("--allowed-kinds LIST") { |value| options[:allowed_kinds] = value }
+    opts.on("--write") { options[:write] = true }
+    opts.on("--read") { options[:read] = true }
+    opts.on("--json") { options[:json] = true }
+  end.parse!
+  root = Dir.pwd
+  lock = %w[propose context confirm].include?(command) && options[:write] ? DevflowControlIO.acquire_project_lock(root) : nil
+  begin
+    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) }
+             when "validate"
+               errors = RequirementGraph.validate(graph)
+               { "ok" => errors.empty?, "path" => relative, "revision" => graph["revision"], "errors" => errors, "checkers" => RequirementGraph.checker_results(graph), "stale" => graph["stale"] }
+             when "context"
+               if options[:read]
+                 pkg = RequirementGraph.load_context_package(root, graph["feature"], options[:slice_id])
+                 if pkg.nil?
+                   { "ok" => false, "reason" => "context_package_missing", "slice_id" => options[:slice_id] }
+                 elsif pkg["graph_revision"] != graph["revision"] || pkg["fingerprint"].nil?
+                   { "ok" => false, "reason" => "stale_context_package", "slice_id" => options[:slice_id], "package_revision" => pkg["graph_revision"], "graph_revision" => graph["revision"] }
+                 else
+                   { "ok" => true, "path" => relative, "context" => pkg, "fresh" => true }
+                 end
+               else
+                 ctx = RequirementGraph.context(graph, options[:slice_id])
+                 if options[:write]
+                   destination = File.join(RequirementGraph.feature_dir(root, graph["feature"]), "context", "#{options[:slice_id]}.json")
+                   DevflowControlIO.atomic_write(destination, JSON.pretty_generate(ctx) + "\n")
+                   ctx["path"] = File.join(RequirementGraph::ROOT, graph["feature"], "context", "#{options[:slice_id]}.json")
+                 end
+                 { "ok" => true, "path" => relative, "context" => ctx }
+               end
+             when "propose"
+               raise ArgumentError, "--write is required" unless options[:write]
+               raise ArgumentError, "--expected-revision is required" if options[:expected_revision].nil?
+               if graph["revision"] != options[:expected_revision]
+                 { "ok" => false, "reason" => "stale_graph_revision", "expected_revision" => options[:expected_revision], "actual_revision" => graph["revision"] }
+               else
+                 delta = JSON.parse(options[:delta_json].to_s)
+                 allowed_kinds = options[:allowed_kinds]&.split(",")&.map(&:strip)
+                 applied = RequirementGraph.proposal(graph, delta, allowed_kinds)
+                 graph["revision"] += 1
+                 stale = Array(graph["stale"]).any?
+                 RequirementGraph.write_views!(root, graph, stale: stale)
+                 RequirementGraph.append_audit!(root, graph, { "event" => "graph_delta", "operation" => applied["operation"], "node_id" => applied.dig("node", "id"), "stale_count" => Array(applied["stale"]).length })
+                 DevflowControlIO.atomic_write(path, JSON.pretty_generate(graph) + "\n")
+                 { "ok" => true, "path" => relative, "revision" => graph["revision"], "applied" => applied, "validation_errors" => RequirementGraph.validate(graph), "checkers" => RequirementGraph.checker_results(graph), "views" => graph["views"] }
+               end
+             when "confirm"
+               raise ArgumentError, "--write is required" unless options[:write]
+               raise ArgumentError, "--node-id is required" unless options[:node_id]
+               raise ArgumentError, "--evidence-json is required" unless options[:evidence_json]
+               raise ArgumentError, "--expected-revision is required" if options[:expected_revision].nil?
+               if graph["revision"] != options[:expected_revision]
+                 { "ok" => false, "reason" => "stale_graph_revision", "expected_revision" => options[:expected_revision], "actual_revision" => graph["revision"] }
+               else
+                 evidence = JSON.parse(options[:evidence_json].to_s)
+                 applied = RequirementGraph.confirm(graph, options[:node_id], evidence)
+                 graph["revision"] += 1
+                 stale = Array(graph["stale"]).any?
+                 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"] }
+               end
+             else
+               { "ok" => false, "reason" => "invalid_command", "message" => "command must be propose, inspect, validate, context, or confirm" }
+             end
+  rescue ArgumentError, JSON::ParserError => error
+    result = { "ok" => false, "reason" => "invalid_requirement_graph_input", "message" => error.message }
+  ensure
+    DevflowControlIO.release_lock(lock)
+  end
+  puts JSON.pretty_generate(result)
+end

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

@@ -6,6 +6,7 @@ require "optparse"
 require "yaml"
 require_relative "control_io"
 require_relative "phase_ownership"
+require_relative "requirement_graph"
 
 module WorkflowStateValidator
   REQUIRED_STATE_FIELDS = %w[
@@ -76,6 +77,26 @@ module WorkflowStateValidator
     validate_completed_outputs(issues, root, state, step_by_id, completed_ids, artifact_by_path, strict_artifact_status)
     validate_waiting_checkpoint(issues, root, state, step_by_id, artifact_by_path, strict_artifact_status)
     validate_current_in_progress_output_drift(issues, root, state, step_by_id, artifact_by_path)
+    graph_gate = workflow.dig("governance", "requirement_graph_gate").to_s
+    governed_steps = %w[requirement-baseline api-contract integration-verify change-plan execute verify]
+    # A historical completed state is never rolled back solely because it has
+    # no v2 graph/evidence. Its first new governed step, however, must satisfy
+    # the new contract before it can advance.
+    strict_requirement_graph = graph_gate == "enforced" && (governed_steps.include?(state["current_step"]) || completed_ids.any? { |id| governed_steps.include?(id) })
+    observe_requirement_graph(issues, root, state, strict: strict_requirement_graph)
+    # Migration is intentionally non-destructive: pre-v2 completed steps are
+    # visible as unattested, never rewritten, rolled back, or auto-rerun.
+    if state["governance_started_revision"].nil?
+      legacy_steps = completed_ids.select { |id| governed_steps.include?(id) }
+      if legacy_steps.any?
+        issues << issue(
+          "warning",
+          "legacy_unattested",
+          "Historical governed steps predate Evidence Pack v2 and are report-only",
+          steps: legacy_steps
+        )
+      end
+    end
 
     ok = issues.none? { |entry| entry["severity"] == "error" }
     result(ok, state_path, workflow_path, registry_path, issues)
@@ -263,6 +284,43 @@ module WorkflowStateValidator
     end
   end
 
+  # P1 observation mode: existing projects must not become invalid merely
+  # because they predate governance graphs. Once a graph exists, surface its
+  # structural failures through state inspection so operators can fix them
+  # before the corresponding checkpoint is upgraded to fail-closed.
+  def observe_requirement_graph(issues, root, state, strict: false)
+    path, relative = RequirementGraph.graph_path(root, state["current_feature"])
+    unless File.exist?(path)
+      issues << issue(strict ? "error" : "warning", "requirement_graph_missing", "Requirement governance graph is missing", path: relative) if strict
+      return
+    end
+
+    graph, = RequirementGraph.load_graph(root, state["current_feature"])
+    errors = RequirementGraph.validate(graph)
+    if errors.any?
+      issues << issue(
+        strict ? "error" : "warning",
+        "requirement_graph_observe_failed",
+        "Requirement governance graph has structural gaps (observation mode)",
+        path: relative,
+        graph_revision: graph["revision"],
+        errors: errors
+      )
+    end
+    return if Array(graph["stale"]).empty?
+
+    issues << issue(
+      strict ? "error" : "warning",
+      "requirement_graph_needs_recheck",
+      "Requirement governance graph has downstream nodes awaiting recheck (observation mode)",
+      path: relative,
+      graph_revision: graph["revision"],
+      stale: graph["stale"]
+    )
+  rescue ArgumentError => error
+    issues << issue("warning", "requirement_graph_observe_failed", error.message)
+  end
+
   def validate_step_outputs(issues, root, state, step, artifact_by_path, strict_artifact_status, waiting_checkpoint)
     Array(step["outputs"]).each do |output|
       next unless output["required"]

package/plugins/devflow-core/skills/workflow-orchestrator/templates/feature-development.yaml

@@ -13,6 +13,40 @@ phase_scope:
   failure_branch_enabled: true
   parallel_window_enabled: true
 
+# P2 preset: new work fail-closes at the defined checkpoints. Existing STATE
+# files without governance_started_revision remain legacy_unattested and are
+# only reported until their next newly-started governed step.
+governance:
+  requirement_graph_gate: enforced
+  enforced_checkpoints:
+    - CP-1
+    - CP-API
+    - CP-2
+    - CP-3
+  step_checkers:
+    requirement-baseline:
+      - requirement-graph-check
+      - slice-independence-check
+      - acceptance-coverage-check
+      - change-impact-check
+    api-contract:
+      - requirement-graph-check
+      - contract-coverage-check
+      - change-impact-check
+    integration-verify:
+      - requirement-graph-check
+      - slice-independence-check
+      - contract-coverage-check
+      - change-impact-check
+    change-plan:
+      - requirement-graph-check
+      - slice-independence-check
+      - contract-coverage-check
+      - change-impact-check
+    verify:
+      - acceptance-coverage-check
+      - change-impact-check
+
 artifact_registry:
   source: ".planning/artifacts/index.yaml"
   path_key: path

package/plugins/devflow-requirements/skills/requirement-feasibility-review/SKILL.md

@@ -204,6 +204,10 @@ Before accepting the rebuttal or retracting the finding, re-open the cited raw s
 
 ## Quality Bar
 
+## Governance Graph Candidate
+
+Submit `risk` and `decision` candidates through `devflow_requirement_graph`, and add missing `behavior` candidates only when backed by a cited source. A `pass` review cannot promote candidates, clear stale nodes, or claim machine validation; it supplies structured candidates and evidence for the Core gate and human checkpoint.
+
 The review must make it easy to trace every conclusion back to evidence. Include:
 
 - flow inventory and critical capability chains;

package/plugins/devflow-requirements/skills/workflow-domain-modeling/SKILL.md

@@ -130,6 +130,10 @@ Accepted
 
 ## Meta Output
 
+## Governance Graph Candidate
+
+Submit bounded candidates through `devflow_requirement_graph`: use `term` for shared language and `behavior` for actor, precondition, state transition, invariant, writes, side effects, failure, and recovery. Link candidates only with returned IDs. Never directly edit the canonical graph or mark a node confirmed; unresolved ownership remains a candidate and is reported in metadata.
+
 `领域模型记录.meta.json` minimum fields:
 
 ```json

package/plugins/devflow-requirements/skills/workflow-requirement-baseline/SKILL.md

@@ -727,6 +727,10 @@ Completion gate: baseline and baseline.meta.json are written and contain no unre
 
 ### 7.4 产物完整性检查
 
+### 7.4.1 Governance Graph Candidate
+
+Before claiming baseline readiness, submit `requirement`、`rule`、`boundary`、`slice` and `acceptance` candidates through `devflow_requirement_graph`. Each requirement candidate must cite source IDs and reference behavior/acceptance IDs returned by the writer. Run `devflow_requirement_graph(action="validate")` and record its result in baseline metadata. Do not directly create `governance.json`, allocate IDs, or set candidate status to `confirmed`.
+
 ```markdown
 - [ ] 每个原始需求映射到 FP-*/BR-*/BC-* 或 out-of-scope
 - [ ] 追溯表完整，来源→FP 映射可验证

package/plugins/devflow-requirements/skills/workflow-requirement-triage/SKILL.md

@@ -191,6 +191,10 @@ Ask at most one question, only when route cannot be decided without it. If the n
 
 ## Completion Rule
 
+## Governance Graph Candidate
+
+Before completion, inspect `devflow_requirement_graph` for the current feature. Submit only `source` or `code` candidate deltas for source material and repository facts discovered here. Read the returned graph revision after every accepted delta. Do not invent stable IDs, set a candidate to `confirmed`, or write `governance.json` directly.
+
 Only tell `workflow-orchestrator` to complete `requirement-triage` after writing:
 
 ```json

package/src/cli.ts

@@ -14,7 +14,7 @@ function usage(): string {
     "  devflow-pi init [project]",
     "  devflow-pi doctor [project]",
     "  devflow-pi usage [project]",
-    "  devflow-pi [project] [--resume [session-id]] [--prompt <text>] [--mcp]",
+    "  devflow-pi [project] [--resume [session-id]] [--prompt <text>] [--mcp] [--yolo]",
   ].join("\n");
 }
 
@@ -76,6 +76,7 @@ async function main(): Promise<void> {
     originalOmpAgentDir,
     resume: optionalOption(args, "--resume"),
     enableMCP: args.includes("--mcp"),
+    approvalMode: args.includes("--yolo") ? "yolo" : "write",
   });
 }