@guanlin4924/devflow-pi 0.1.14 → 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/traceability_check.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""Fail-closed requirement-to-delivery traceability validation."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+STAGES = ("baseline", "design", "change-plan", "verify")
+DIMENSIONS = ("input", "output", "behavior", "orchestration", "failure", "verification")
+
+
+def fail(errors: list[str], message: str) -> None:
+    errors.append(message)
+
+
+def references(items: object) -> set[str]:
+    if not isinstance(items, list):
+        return set()
+    result = set()
+    for item in items:
+        if isinstance(item, str):
+            result.add(item)
+        elif isinstance(item, dict) and isinstance(item.get("id"), str):
+            result.add(item["id"])
+    return result
+
+
+def check(data: dict, stage: str) -> list[str]:
+    errors: list[str] = []
+    requirements = data.get("requirements")
+    if data.get("schema_version") != 1:
+        fail(errors, "schema_version must be 1")
+    if not isinstance(data.get("feature"), str) or not data["feature"].strip():
+        fail(errors, "feature is required")
+    if not isinstance(requirements, list) or not requirements:
+        return errors + ["requirements must be a non-empty array"]
+
+    active: set[str] = set()
+    known: set[str] = set()
+    for req in requirements:
+        if not isinstance(req, dict):
+            fail(errors, "every requirement must be an object")
+            continue
+        rid = req.get("id")
+        if not isinstance(rid, str) or not rid.startswith("REQ-"):
+            fail(errors, f"invalid requirement id: {rid!r}")
+            continue
+        known.add(rid)
+        if req.get("status", "confirmed") in {"confirmed", "approved"} and req.get("scope", "in") == "in":
+            active.add(rid)
+        dimensions = req.get("dimensions")
+        if not isinstance(dimensions, dict):
+            fail(errors, f"{rid}: dimensions is required")
+        else:
+            missing = [d for d in DIMENSIONS if not isinstance(dimensions.get(d), str) or not dimensions[d].strip()]
+            if missing:
+                fail(errors, f"{rid}: missing dimensions: {', '.join(missing)}")
+
+    if stage == "baseline":
+        return errors
+
+    designs = data.get("designs")
+    if not isinstance(designs, list) or not designs:
+        fail(errors, "designs must be a non-empty array after baseline")
+    covered_by_design = set()
+    for item in designs or []:
+        if not isinstance(item, dict) or not isinstance(item.get("id"), str):
+            fail(errors, "every design needs an id")
+            continue
+        refs = references(item.get("requirements"))
+        unknown = refs - known
+        if unknown:
+            fail(errors, f"{item['id']}: references unknown requirements: {', '.join(sorted(unknown))}")
+        covered_by_design |= refs
+        if item.get("kind") == "api":
+            contract = item.get("contract")
+            if not isinstance(contract, dict) or any(not contract.get(k) for k in ("request", "response", "errors", "behavior")):
+                fail(errors, f"{item['id']}: API design must include request, response, errors and behavior")
+    missing = active - covered_by_design
+    if missing:
+        fail(errors, "requirements missing design coverage: " + ", ".join(sorted(missing)))
+    if stage == "design":
+        return errors
+
+    tasks = data.get("tasks")
+    if not isinstance(tasks, list) or not tasks:
+        fail(errors, "tasks must be a non-empty array after design")
+    covered_by_task = set()
+    for task in tasks or []:
+        if not isinstance(task, dict) or not isinstance(task.get("id"), str):
+            fail(errors, "every task needs an id")
+            continue
+        refs = task.get("requirements")
+        if not isinstance(refs, list) or not refs:
+            fail(errors, f"{task['id']}: requirements is required")
+        else:
+            covered_by_task.update(refs)
+            unknown = set(refs) - known
+            if unknown:
+                fail(errors, f"{task['id']}: references unknown requirements: {', '.join(sorted(unknown))}")
+        criteria = task.get("acceptance")
+        if not isinstance(criteria, dict):
+            fail(errors, f"{task['id']}: acceptance is required")
+        else:
+            missing = [d for d in DIMENSIONS if not isinstance(criteria.get(d), str) or not criteria[d].strip()]
+            if missing:
+                fail(errors, f"{task['id']}: missing acceptance dimensions: {', '.join(missing)}")
+    missing = active - covered_by_task
+    if missing:
+        fail(errors, "requirements missing task coverage: " + ", ".join(sorted(missing)))
+    if stage == "change-plan":
+        return errors
+
+    verification = data.get("verification")
+    if not isinstance(verification, list) or not verification:
+        fail(errors, "verification must be a non-empty array after change-plan")
+    covered_by_verification = set()
+    for item in verification or []:
+        if not isinstance(item, dict) or not isinstance(item.get("id"), str):
+            fail(errors, "every verification item needs an id")
+            continue
+        refs = item.get("requirements")
+        if not isinstance(refs, list) or not refs:
+            fail(errors, f"{item['id']}: requirements is required")
+        else:
+            covered_by_verification.update(refs)
+            unknown = set(refs) - known
+            if unknown:
+                fail(errors, f"{item['id']}: references unknown requirements: {', '.join(sorted(unknown))}")
+        if not isinstance(item.get("evidence"), str) or not item["evidence"].strip():
+            fail(errors, f"{item['id']}: evidence is required")
+    missing = active - covered_by_verification
+    if missing:
+        fail(errors, "requirements missing verification coverage: " + ", ".join(sorted(missing)))
+    return errors
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--file", required=True)
+    parser.add_argument("--stage", choices=STAGES, required=True)
+    args = parser.parse_args()
+    try:
+        data = json.loads(Path(args.file).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"TRACEABILITY_FAIL: cannot read manifest: {exc}", file=sys.stderr)
+        return 2
+    if not isinstance(data, dict):
+        print("TRACEABILITY_FAIL: manifest root must be an object", file=sys.stderr)
+        return 2
+    errors = check(data, args.stage)
+    result = {"status": "passed" if not errors else "failed", "stage": args.stage, "errors": errors}
+    print(json.dumps(result, ensure_ascii=False))
+    return 0 if not errors else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())