@guanlin4924/devflow-pi 0.1.16 → 0.1.18

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

@@ -10,15 +10,19 @@ require "optparse"
 require "pathname"
 require "set"
 require_relative "control_io"
+require_relative "architecture_constraints"
 
 module RequirementGraph
-  SCHEMA_VERSION = 2
+  # 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"
+    "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]/
@@ -33,8 +37,8 @@ module RequirementGraph
   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)
+    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
@@ -72,7 +76,7 @@ module RequirementGraph
     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 &&
+    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]
@@ -154,6 +158,8 @@ module RequirementGraph
       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 }
@@ -169,8 +175,13 @@ module RequirementGraph
       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"
@@ -184,13 +195,18 @@ module RequirementGraph
   end
 
   # Core-only 审核转换：candidate → confirmed，要求人工 CP 记录或运行证据。
-  def confirm(graph, node_id, evidence)
+  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)
@@ -230,6 +246,152 @@ module RequirementGraph
     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"
@@ -264,6 +426,18 @@ module RequirementGraph
         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"))
@@ -316,13 +490,13 @@ module RequirementGraph
             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 "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" => 2, "origin" => "core_requirement_graph", "feature" => graph["feature"], "graph_revision" => graph["revision"],
+    { "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
 
@@ -341,13 +515,13 @@ module RequirementGraph
       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"],
+    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" => 2, "origin" => "core_requirement_graph", "graph_revision" => graph["revision"])
+    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")
@@ -364,7 +538,7 @@ module RequirementGraph
       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"],
+    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
@@ -382,7 +556,7 @@ module RequirementGraph
 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 }
+  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]"
@@ -393,6 +567,7 @@ if __FILE__ == $PROGRAM_NAME
     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 }
@@ -451,7 +626,7 @@ if __FILE__ == $PROGRAM_NAME
                  { "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)
+                 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)

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

@@ -0,0 +1,210 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Repository-declared runtime context collector (P0).
+# It reads manifest content from one immutable Git revision rather than the
+# working tree, so every inventory entry and every absence claim is replayable.
+require "digest"
+require "json"
+require "open3"
+require "optparse"
+require "rexml/document"
+require "rexml/xpath"
+require_relative "control_io"
+
+module RuntimeContextCollector
+  SCHEMA_VERSION = 1
+  HISTORY_DIR = File.join(".context", "runtime-context", "revisions")
+  POINTER = File.join(".context", "runtime-context.json")
+  EXTRACTORS = {
+    "package.json" => :extract_package_json,
+    "requirements.txt" => :extract_requirements_txt,
+    "pom.xml" => :extract_pom_xml
+  }.freeze
+  EXCLUDED_ROOTS = %w[node_modules vendor dist build .git].freeze
+
+  module_function
+
+  def safe_version(value)
+    text = value.to_s.strip
+    # A dependency version is useful evidence, but a direct URL can carry an
+    # access token. P0 does not consume versions, so redact unsafe forms.
+    return nil if text.empty? || text.match?(%r{[:/@]})
+
+    text
+  end
+
+  def extract_package_json(content)
+    parsed = JSON.parse(content)
+    deps = parsed["dependencies"].is_a?(Hash) ? parsed["dependencies"] : {}
+    deps.map { |name, version| { "subject" => name.to_s.downcase.strip, "version" => safe_version(version) } }
+  rescue JSON::ParserError
+    raise "parse_error"
+  end
+
+  def extract_requirements_txt(content)
+    content.lines.map(&:strip).reject { |line| line.empty? || line.start_with?("#", "-e", "--", "-r", "-f") }.map do |line|
+      name = line.split(/[<>=!\[\s]/, 2).first.to_s.downcase.strip
+      version = line.match(/\A[^<>=!\[\s]+\s*(?:==|>=|<=|~=|>|<)\s*([^\s;]+)\z/)&.[](1)
+      { "subject" => name, "version" => safe_version(version) }
+    end
+  end
+
+  def extract_pom_xml(content)
+    document = REXML::Document.new(content)
+    REXML::XPath.match(document, "//dependency").map do |dependency|
+      group = dependency.elements["groupId"]&.text.to_s.strip
+      artifact = dependency.elements["artifactId"]&.text.to_s.strip
+      next if group.empty? || artifact.empty?
+
+      { "subject" => "#{group}:#{artifact}".downcase, "version" => safe_version(dependency.elements["version"]&.text) }
+    end.compact
+  rescue REXML::ParseException
+    raise "parse_error"
+  end
+
+  def git_capture(root, *args)
+    stdout, stderr, status = Open3.capture3("git", "-C", root, *args)
+    [stdout, stderr, status.success?]
+  end
+
+  def git_revision(root)
+    output, _error, success = git_capture(root, "rev-parse", "HEAD")
+    success ? output.strip : ""
+  end
+
+  def excluded_path?(path)
+    path.split("/").any? { |segment| EXCLUDED_ROOTS.include?(segment) }
+  end
+
+  def git_file_list(root, revision)
+    output, error, success = git_capture(root, "ls-tree", "-r", "--name-only", revision)
+    raise "git_tree_unavailable: #{error.strip}" unless success
+
+    supported = output.lines.map(&:strip).select { |path| EXTRACTORS.key?(File.basename(path)) }.sort
+    included, excluded = supported.partition { |path| !excluded_path?(path) }
+    [included, excluded]
+  end
+
+  def git_file_content(root, revision, path)
+    output, error, success = git_capture(root, "show", "#{revision}:#{path}")
+    raise "git_show_failed: #{error.strip}" unless success
+
+    output
+  end
+
+  # Enumerates every supported manifest in the committed tree. Files not
+  # matching the explicit P0 allowlist are outside the declared collector
+  # scope; every matching file has a scanned or failed entry.
+  def discover_and_extract(root, revision)
+    files = []
+    inventory = {}
+    paths, excluded_paths = git_file_list(root, revision)
+    excluded_paths.each do |path|
+      files << { "path" => path, "status" => "excluded", "reason" => "third_party_or_build_output" }
+    end
+    paths.each do |path|
+      extractor = EXTRACTORS.fetch(File.basename(path))
+      begin
+        content = git_file_content(root, revision, path)
+        entries = send(extractor, content)
+        evidence = {
+          "path" => path,
+          "git_revision" => revision,
+          "sha256" => Digest::SHA256.hexdigest(content),
+          "extractor" => extractor.to_s
+        }
+        entries.each do |entry|
+          subject = entry["subject"].to_s.downcase.strip
+          next if subject.empty?
+
+          inventory[subject] ||= {
+            "kind" => "runtime_dep", "subject" => subject,
+            "version" => entry["version"], "evidence" => evidence
+          }
+        end
+        files << { "path" => path, "status" => "scanned" }
+      rescue StandardError => error
+        files << { "path" => path, "status" => "failed", "error" => error.message }
+      end
+    end
+    [files, inventory.values]
+  rescue StandardError => error
+    [[{ "path" => "<repository>", "status" => "failed", "error" => error.message }], []]
+  end
+
+  def current_revision(root)
+    pointer = File.join(root, POINTER)
+    return 0 unless File.exist?(pointer)
+
+    JSON.parse(File.read(pointer))["current_revision"].to_i
+  rescue JSON::ParserError
+    raise ArgumentError, "runtime-context pointer is invalid JSON: #{pointer}"
+  end
+
+  def collect(root)
+    repository_revision = git_revision(root)
+    files, inventory =
+      if repository_revision.empty?
+        [[{ "path" => "<repository>", "status" => "failed", "error" => "git_revision_unavailable" }], []]
+      else
+        discover_and_extract(root, repository_revision)
+      end
+    coverage_status = files.any? { |file| file["status"] == "failed" } ? "incomplete" : "complete"
+    revision = current_revision(root) + 1
+    snapshot = {
+      "schema_version" => SCHEMA_VERSION,
+      "context_id" => "repo-default",
+      "snapshot_revision" => revision,
+      "scope" => "repository-default:package.json|requirements.txt|pom.xml",
+      "repository_revision" => repository_revision,
+      "discovery_hash" => Digest::SHA256.hexdigest(JSON.generate(files)),
+      "collector" => {
+        "version" => "git-manifest-allowlist-v1",
+        "discovery" => { "rules" => EXTRACTORS.keys.sort, "files" => files }
+      },
+      "inventory_hash" => Digest::SHA256.hexdigest(JSON.generate(inventory)),
+      "coverage_status" => coverage_status,
+      "inventory" => inventory
+    }
+    history = File.join(root, HISTORY_DIR, "#{revision}.json")
+    DevflowControlIO.atomic_create(history, JSON.pretty_generate(snapshot) + "\n")
+    DevflowControlIO.atomic_write(File.join(root, POINTER), JSON.pretty_generate({ "current_revision" => revision, "path" => history.sub("#{root}/", "") }) + "\n")
+    DevflowControlIO.append_audit(File.join(root, ".context", "runtime-context", "audit.jsonl"), {
+      "event" => "snapshot_collected", "snapshot_revision" => revision,
+      "repository_revision" => repository_revision, "coverage_status" => coverage_status
+    })
+    DevflowControlIO.register_control_artifact(root, {
+      "path" => history.sub("#{root}/", ""), "type" => "runtime_context_snapshot",
+      "produced_by" => "core", "snapshot_revision" => revision,
+      "coverage_status" => coverage_status, "repository_revision" => repository_revision
+    })
+    snapshot
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  options = { json: false }
+  command = ARGV.shift
+  OptionParser.new do |o|
+    o.on("--json") { options[:json] = true }
+  end.parse!
+  root = Dir.pwd
+  lock = command == "collect" ? DevflowControlIO.acquire_project_lock(root) : nil
+  begin
+    raise ArgumentError, "command must be collect or inspect" unless %w[collect inspect].include?(command)
+    result =
+      if command == "collect"
+        snapshot = RuntimeContextCollector.collect(root)
+        { "ok" => true, "snapshot_revision" => snapshot["snapshot_revision"], "coverage_status" => snapshot["coverage_status"], "inventory_count" => snapshot["inventory"].length, "repository_revision" => snapshot["repository_revision"] }
+      else
+        pointer = File.join(root, RuntimeContextCollector::POINTER)
+        { "ok" => true, "current_revision" => RuntimeContextCollector.current_revision(root), "pointer_exists" => File.exist?(pointer) }
+      end
+  rescue StandardError => error
+    result = { "ok" => false, "reason" => "runtime_context_collector_failed", "message" => error.message }
+  ensure
+    DevflowControlIO.release_lock(lock)
+  end
+  puts JSON.pretty_generate(result)
+end

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

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Field-level staleness check (P1). A downstream consumer pins the exact
+# evidence paths it consumed plus the snapshot revision it read; this checker
+# compares evidence sha256 across revisions and reports only the changed
+# paths — not a whole-snapshot invalidation.
+require "json"
+require "optparse"
+require_relative "runtime_context_collector"
+
+module StaleCheck
+  module_function
+
+  def evidence_map(snapshot)
+    map = {}
+    Array(snapshot["inventory"]).each do |item|
+      evidence = item["evidence"]
+      next unless evidence.is_a?(Hash) && evidence["path"]
+      map[evidence["path"]] = evidence["sha256"]
+    end
+    map
+  end
+
+  def changed_paths(old_snapshot, new_snapshot, evidence_paths)
+    old_map = evidence_map(old_snapshot)
+    new_map = evidence_map(new_snapshot)
+    Array(evidence_paths).select { |path| old_map[path] != new_map[path] }
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  options = { consumed_revision: nil, evidence_paths: nil }
+  command = ARGV.shift
+  OptionParser.new do |o|
+    o.on("--consumed-revision N", Integer) { |v| options[:consumed_revision] = v }
+    o.on("--evidence-paths JSON") { |v| options[:evidence_paths] = v }
+    o.on("--json") { options[:json] = true }
+  end.parse!
+  root = Dir.pwd
+  begin
+    raise ArgumentError, "command must be check" unless command == "check"
+    raise ArgumentError, "--consumed-revision is required" if options[:consumed_revision].nil?
+    current = RuntimeContextCollector.current_revision(root)
+    old_path = File.join(root, RuntimeContextCollector::HISTORY_DIR, "#{options[:consumed_revision]}.json")
+    new_path = File.join(root, RuntimeContextCollector::HISTORY_DIR, "#{current}.json")
+    raise ArgumentError, "consumed snapshot not found" unless File.exist?(old_path)
+    old = JSON.parse(File.read(old_path))
+    new = JSON.parse(File.read(new_path))
+    paths = JSON.parse(options[:evidence_paths].to_s)
+    changed = StaleCheck.changed_paths(old, new, paths)
+    { "ok" => true, "consumed_revision" => options[:consumed_revision], "current_revision" => current, "changed_paths" => changed }
+  rescue StandardError => error
+    { "ok" => false, "reason" => "stale_check_failed", "message" => error.message }
+  end.tap { |r| puts JSON.pretty_generate(r) }
+end