@guanlin4924/devflow-pi 0.1.15 → 0.1.17

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

@@ -0,0 +1,646 @@
+#!/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"
+require_relative "architecture_constraints"
+
+module RequirementGraph
+  # v3 adds the two narrowly-scoped architecture inputs. Existing v1/v2
+  # graphs are migrated in memory and re-written only by this Core writer.
+  SCHEMA_VERSION = 3
+  SUPPORTED_SCHEMA_VERSIONS = [1, 2, SCHEMA_VERSION].freeze
+  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", "workload_shape" => "WSH", "workload_constraint" => "WLC"
+  }.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")
+    root_real = File.realpath(root)
+    absolute = File.expand_path(relative, root_real)
+    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) && SUPPORTED_SCHEMA_VERSIONS.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 }
+      candidate_errors = workload_node_errors(graph, node) + architecture_decision_errors(graph, node) + architecture_risk_errors(graph, node)
+      raise ArgumentError, candidate_errors.join("; ") if candidate_errors.any?
+      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
+      if (%w[workload_shape workload_constraint].include?(node["kind"]) || architecture_control_node?(node)) && node["status"] == "confirmed"
+        raise ArgumentError, "confirmed workload nodes and architecture decisions are immutable; add a new candidate and relink consumers"
+      end
+      data = normalize_data(delta["data"])
+      node["data"] = node.fetch("data", {}).merge(data)
+      candidate_errors = workload_node_errors(graph, node) + architecture_decision_errors(graph, node) + architecture_risk_errors(graph, node)
+      raise ArgumentError, candidate_errors.join("; ") if candidate_errors.any?
+      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, confirmed_interactively: false)
+    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
+    if (%w[workload_shape workload_constraint].include?(node["kind"]) || architecture_control_node?(node)) && !confirmed_interactively
+      raise ArgumentError, "workload and architecture-control confirmation requires --confirmed-interactively from the Core confirmation dialog"
+    end
+    confirmation_errors = workload_confirmation_errors(graph, node, evidence) + architecture_decision_confirmation_errors(graph, node) + architecture_risk_confirmation_errors(graph, node)
+    raise ArgumentError, confirmation_errors.join("; ") if confirmation_errors.any?
+    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 incoming_edge?(graph, from, to, relation)
+    Array(graph["edges"]).any? do |edge|
+      edge.is_a?(Hash) && edge["from"] == from && edge["to"] == to && edge["relation"] == relation
+    end
+  end
+
+  # WSH/WLC are graph-owned facts, not a second unbounded document schema.
+  # The candidate validator owns field rules; this layer adds only the facts
+  # it can prove: graph references, traceability edges, and confirmation state.
+  def workload_node_errors(graph, node, require_edges: false, require_confirmed_inputs: false)
+    return [] unless %w[workload_shape workload_constraint].include?(node["kind"])
+
+    data = node["data"].is_a?(Hash) ? node["data"] : {}
+    payload = data.merge("feature" => graph["feature"], "status" => node["status"])
+    errors =
+      if node["kind"] == "workload_shape"
+        ArchitectureConstraints.validate_shape(payload, allow_confirmed: true)
+      else
+        ArchitectureConstraints.validate_constraint(payload, allow_confirmed: true)
+      end
+    errors = errors.map { |error| "#{node["id"]}: #{error}" }
+
+    if node["kind"] == "workload_shape"
+      refs = Array(data["source_refs"]) + Array(data["behavior_refs"])
+      refs.uniq.each do |ref|
+        expected = ref.to_s.start_with?("BEH-") ? %w[BEH] : %w[REQ BEH API]
+        errors << "#{node["id"]}: workload source #{ref} must exist in the graph" unless refs_known?(graph, [ref], expected)
+        errors << "#{node["id"]}: workload source #{ref} must link with shapes_workload" if require_edges && !incoming_edge?(graph, ref, node["id"], "shapes_workload")
+        errors << "#{node["id"]}: workload source #{ref} must be confirmed" if require_confirmed_inputs && !confirmed?(graph, ref)
+      end
+    else
+      workload_ref = data["workload_ref"]
+      errors << "#{node["id"]}: workload_ref #{workload_ref} must exist in the graph" unless refs_known?(graph, [workload_ref], %w[BEH SL API])
+      errors << "#{node["id"]}: workload_ref #{workload_ref} must link with constrains_workload" if require_edges && !incoming_edge?(graph, workload_ref, node["id"], "constrains_workload")
+      errors << "#{node["id"]}: workload_ref #{workload_ref} must be confirmed" if require_confirmed_inputs && !confirmed?(graph, workload_ref)
+
+      evidence = data["evidence"]
+      if evidence.is_a?(Hash) && evidence["kind"] == "source_file"
+        evidence_ref = evidence["ref"]
+        errors << "#{node["id"]}: source_file evidence.ref must reference SRC/CODE" unless refs_known?(graph, [evidence_ref], %w[SRC CODE])
+        errors << "#{node["id"]}: source_file evidence.ref must be confirmed" if require_confirmed_inputs && !confirmed?(graph, evidence_ref)
+      end
+    end
+    errors.uniq
+  end
+
+  def workload_confirmation_errors(graph, node, evidence)
+    errors = workload_node_errors(graph, node, require_edges: true, require_confirmed_inputs: true)
+    if node["kind"] == "workload_constraint" && %w[approved_assumption unknown].include?(node.dig("data", "source_status")) && !evidence["cp_record"]
+      errors << "#{node["id"]}: #{node.dig("data", "source_status")} confirmation requires cp_record"
+    end
+    errors
+  end
+
+  def architecture_option_decision?(node)
+    node["kind"] == "decision" && node.dig("data", "decision_type") == "architecture_option_comparison"
+  end
+
+  # Keep architecture comparison inside the existing DECISION vocabulary. The
+  # typed payload prevents a prose-only "A/B" list from masquerading as a
+  # decision: every option needs a mechanism, fact-bound evidence and tradeoffs.
+  def architecture_decision_errors(graph, node, require_edges: false, require_confirmed_inputs: false)
+    return [] unless architecture_option_decision?(node)
+
+    data = node.fetch("data", {})
+    errors = []
+    subject_refs = data["subject_refs"]
+    errors << "#{node["id"]}: architecture decision subject_refs must be a non-empty array" unless subject_refs.is_a?(Array) && !subject_refs.empty?
+    Array(subject_refs).each do |ref|
+      errors << "#{node["id"]}: architecture decision subject_ref #{ref} must reference WSH/WLC" unless refs_known?(graph, [ref], %w[WSH WLC])
+      relation = ref.to_s.start_with?("WSH-") ? "informs_decision" : "constrains_decision"
+      errors << "#{node["id"]}: architecture decision subject_ref #{ref} must link with #{relation}" if require_edges && !incoming_edge?(graph, ref, node["id"], relation)
+      errors << "#{node["id"]}: architecture decision subject_ref #{ref} must be confirmed" if require_confirmed_inputs && !confirmed?(graph, ref)
+    end
+
+    comparison = data["comparison"]
+    unless comparison.is_a?(Hash)
+      errors << "#{node["id"]}: architecture decision comparison is required"
+      return errors.uniq
+    end
+    mode = comparison["mode"]
+    errors << "#{node["id"]}: architecture decision comparison.mode is invalid" unless %w[multiple_options single_path].include?(mode)
+    options = comparison["options"]
+    errors << "#{node["id"]}: architecture decision comparison.options must be an array" unless options.is_a?(Array)
+    options = Array(options)
+    errors << "#{node["id"]}: multiple_options requires at least two materially different options" if mode == "multiple_options" && options.length < 2
+    errors << "#{node["id"]}: single_path requires exactly one option" if mode == "single_path" && options.length != 1
+    option_ids = []
+    options.each do |option|
+      unless option.is_a?(Hash)
+        errors << "#{node["id"]}: comparison option must be an object"
+        next
+      end
+      option_key = option["option_key"].to_s
+      option_ids << option_key unless option_key.empty?
+      label = option_key.empty? ? "<missing>" : option_key
+      errors << "#{node["id"]}: comparison option option_key is required" if option_key.empty?
+      errors << "#{node["id"]}: option #{label} requires mechanism" unless present?(option["mechanism"])
+      errors << "#{node["id"]}: option #{label} requires non-empty tradeoffs" unless option["tradeoffs"].is_a?(Array) && !option["tradeoffs"].empty?
+      refs = option["fact_refs"]
+      errors << "#{node["id"]}: option #{label} requires fact_refs" unless refs.is_a?(Array) && !refs.empty?
+      Array(refs).each do |ref|
+        errors << "#{node["id"]}: option #{label} fact_ref #{ref} must reference WSH/WLC" unless refs_known?(graph, [ref], %w[WSH WLC])
+      end
+    end
+    errors << "#{node["id"]}: architecture decision option ids must be unique" unless option_ids.uniq.length == option_ids.length
+    recommendation = comparison["recommendation_option_id"]
+    errors << "#{node["id"]}: architecture decision recommendation_option_id must name a listed option" unless option_ids.include?(recommendation)
+    errors.uniq
+  end
+
+  def architecture_decision_confirmation_errors(graph, node)
+    architecture_decision_errors(graph, node, require_edges: true, require_confirmed_inputs: true)
+  end
+
+  def architecture_option_risk?(node)
+    node["kind"] == "risk" && node.dig("data", "risk_type") == "architecture_option_risk"
+  end
+
+  def architecture_risk_errors(graph, node, require_edges: false, require_confirmed_inputs: false)
+    return [] unless architecture_option_risk?(node)
+
+    data = node.fetch("data", {})
+    errors = []
+    refs = data["subject_refs"]
+    errors << "#{node["id"]}: architecture risk subject_refs must be a non-empty array" unless refs.is_a?(Array) && !refs.empty?
+    Array(refs).each do |ref|
+      errors << "#{node["id"]}: architecture risk subject_ref #{ref} must reference DECISION/WSH/WLC" unless refs_known?(graph, [ref], %w[DECISION WSH WLC])
+      errors << "#{node["id"]}: architecture risk subject_ref #{ref} must link with has_architecture_risk" if require_edges && !incoming_edge?(graph, ref, node["id"], "has_architecture_risk")
+      errors << "#{node["id"]}: architecture risk subject_ref #{ref} must be confirmed" if require_confirmed_inputs && !confirmed?(graph, ref)
+    end
+    %w[failure_mode impact mitigation owner review_condition].each do |field|
+      errors << "#{node["id"]}: architecture risk requires #{field}" unless present?(data[field])
+    end
+    errors << "#{node["id"]}: architecture risk treatment is invalid" unless %w[mitigate accept].include?(data["treatment"])
+    errors.uniq
+  end
+
+  def architecture_risk_confirmation_errors(graph, node)
+    architecture_risk_errors(graph, node, require_edges: true, require_confirmed_inputs: true)
+  end
+
+  def architecture_control_node?(node)
+    architecture_option_decision?(node) || architecture_option_risk?(node)
+  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 "decision"
+        results["requirement-graph-check"].concat(
+          architecture_decision_errors(graph, node, require_edges: true, require_confirmed_inputs: node["status"] == "confirmed")
+        )
+      when "risk"
+        results["requirement-graph-check"].concat(
+          architecture_risk_errors(graph, node, require_edges: true, require_confirmed_inputs: node["status"] == "confirmed")
+        )
+      when "workload_shape", "workload_constraint"
+        results["requirement-graph-check"].concat(
+          workload_node_errors(graph, node, require_edges: true, require_confirmed_inputs: node["status"] == "confirmed")
+        )
+      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 workload_shape workload_constraint]
+            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" => SCHEMA_VERSION, "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" => SCHEMA_VERSION, "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" => SCHEMA_VERSION, "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" => SCHEMA_VERSION, "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, confirmed_interactively: false, 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("--confirmed-interactively") { options[:confirmed_interactively] = true }
+    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, confirmed_interactively: options[:confirmed_interactively])
+                 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