@guanlin4924/devflow-pi 0.1.24 → 0.1.26

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

@@ -78,6 +78,21 @@ module ArchitectureFeasibility
       data = node.fetch("data")
       if node["kind"] == "workload_shape"
         facts = data.fetch("facts")
+        case facts["archetype"]
+        when "analytics_query"
+          level = promote(level, "full")
+          triggers << { "code" => "ARC_ANALYTICS_QUERY", "node_id" => node["id"] }
+        when "analytics_projection"
+          level = promote(level, "full")
+          triggers << { "code" => "ARC_ANALYTICS_PROJECTION", "node_id" => node["id"] }
+        when "transactional_command"
+          level = promote(level, "lightweight")
+          triggers << { "code" => "ARC_TRANSACTIONAL_COMMAND", "node_id" => node["id"] }
+        end
+        if facts["consistency"] == "unknown"
+          level = promote(level, "lightweight")
+          unresolved << { "code" => "ARC_CONSISTENCY_UNKNOWN", "node_id" => node["id"] }
+        end
         case facts["data_effect"]
         when "migration"
           level = promote(level, "full")
@@ -121,10 +136,19 @@ module ArchitectureFeasibility
       end
     end
 
+    Array(graph["nodes"]).each do |node|
+      next unless node.is_a?(Hash) && node["kind"] == "read_model" && node["status"] == "confirmed"
+      data = node.fetch("data", {})
+      if data.dig("rebuild", "method") == "unknown" || data["late_data_policy"] == "unknown"
+        level = promote(level, "lightweight")
+        unresolved << { "code" => "ARC_READ_MODEL_RECOVERY_UNKNOWN", "node_id" => node["id"] }
+      end
+    end
+
     unless static_context["available"]
       unresolved << { "code" => static_context["code"], "detail" => static_context["detail"] }.compact
     end
-    workload_errors = graph_errors.grep(/\A(?:WSH|WLC)-/)
+    workload_errors = graph_errors.grep(/\A(?:WSH|WLC|METRIC|RM)-/)
     unresolved << { "code" => "ARC_WORKLOAD_GRAPH_INVALID", "count" => workload_errors.length } if workload_errors.any?
 
     # P2 deliberately uses no numeric threshold. A numeric constraint is a

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

@@ -31,6 +31,10 @@ module DevflowControlIO
               when :workflow then normalized.match?(%r{\A\.planning/workflows/[A-Za-z0-9][A-Za-z0-9_-]*\.yaml\z})
               when :registry then normalized == ".planning/artifacts/index.yaml"
               when :artifact then normalized.start_with?(".planning/") || normalized.start_with?(".context/")
+              # Feature names are user-facing and may be Unicode. `cleanpath`
+              # and the parent-traversal check above own containment; this
+              # matcher only fixes the handoff namespace and immutable name.
+              when :handoff then normalized.match?(%r{\A\.planning/handoffs/[^/]+/ROL-[0-9a-f-]+\.json\z})
               else false
               end
     raise InvalidControlPath, "invalid #{kind} control path" unless allowed

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

@@ -13,7 +13,7 @@ require_relative "requirement_graph"
 POLICY = {
   "requirement-baseline" => { "checkers" => %w[requirement-graph-check slice-independence-check acceptance-coverage-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[requirement rule boundary slice acceptance] },
   "api-contract" => { "checkers" => %w[requirement-graph-check contract-coverage-check api-test-schema-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[api] },
-  "architecture-feasibility" => { "checkers" => %w[requirement-graph-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[workload_shape workload_constraint decision risk] },
+  "architecture-feasibility" => { "checkers" => %w[requirement-graph-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[workload_shape workload_constraint decision risk metric read_model] },
   "integration-verify" => { "checkers" => %w[requirement-graph-check slice-independence-check contract-coverage-check change-impact-check], "agents" => ["verification-runner"], "budget" => 1, "allowed_graph_delta" => %w[requirement risk decision] },
   "acceptance-test-design" => { "checkers" => %w[requirement-graph-check contract-coverage-check acceptance-coverage-check api-test-matrix-check test-coverage-check test-obligation-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[test_case] },
   "change-plan" => { "checkers" => %w[requirement-graph-check slice-independence-check contract-coverage-check api-test-matrix-check test-coverage-check test-obligation-check test-task-binding-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[acceptance] },

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

@@ -13,16 +13,17 @@ require_relative "control_io"
 require_relative "architecture_constraints"
 
 module RequirementGraph
-  # v4 adds derived TC verification nodes. Existing v1-v3
+  # v5 adds workload archetypes plus METRIC/RM nodes. Existing v1-v4
   # graphs are migrated in memory and re-written only by this Core writer.
-  SCHEMA_VERSION = 4
-  SUPPORTED_SCHEMA_VERSIONS = [1, 2, 3, SCHEMA_VERSION].freeze
+  SCHEMA_VERSION = 5
+  SUPPORTED_SCHEMA_VERSIONS = [1, 2, 3, 4, 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", "test_case" => "TC"
+    "api" => "API", "workload_shape" => "WSH", "workload_constraint" => "WLC", "metric" => "METRIC",
+    "read_model" => "RM", "test_case" => "TC"
   }.freeze
   VIEW_NAMES = %w[evidence definitions behavior-graph requirement-graph slices acceptance tests traceability].freeze
   FEATURE_INVALID = /[\\\/\x00-\x1F\x7F]/
@@ -176,7 +177,7 @@ 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) + test_case_errors(graph, node)
+      candidate_errors = workload_node_errors(graph, node) + metric_node_errors(graph, node) + read_model_node_errors(graph, node) + architecture_decision_errors(graph, node) + architecture_risk_errors(graph, node) + test_case_errors(graph, node)
       raise ArgumentError, candidate_errors.join("; ") if candidate_errors.any?
       set_node_fingerprint!(node)
       graph["nodes"] << node
@@ -193,12 +194,12 @@ 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 test_case].include?(node["kind"]) || architecture_control_node?(node)) && node["status"] == "confirmed"
-        raise ArgumentError, "confirmed workload nodes and architecture decisions are immutable; confirmed test cases are also immutable; add a new candidate and relink consumers"
+      if (%w[workload_shape workload_constraint metric read_model test_case].include?(node["kind"]) || architecture_control_node?(node)) && node["status"] == "confirmed"
+        raise ArgumentError, "confirmed workload, metric/read-model, and architecture decision nodes are immutable; confirmed test cases are also 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) + test_case_errors(graph, node)
+      candidate_errors = workload_node_errors(graph, node) + metric_node_errors(graph, node) + read_model_node_errors(graph, node) + architecture_decision_errors(graph, node) + architecture_risk_errors(graph, node) + test_case_errors(graph, node)
       raise ArgumentError, candidate_errors.join("; ") if candidate_errors.any?
       set_node_fingerprint!(node)
       clear_stale_for!(graph, id)
@@ -221,10 +222,10 @@ module RequirementGraph
     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"
+    if (%w[workload_shape workload_constraint metric read_model].include?(node["kind"]) || architecture_control_node?(node)) && !confirmed_interactively
+      raise ArgumentError, "workload and architecture-control confirmation requires --confirmed-interactively from the Core confirmation dialog; metric/read-model candidates use the same dialog"
     end
-    confirmation_errors = workload_confirmation_errors(graph, node, evidence) + architecture_decision_confirmation_errors(graph, node) + architecture_risk_confirmation_errors(graph, node)
+    confirmation_errors = workload_confirmation_errors(graph, node, evidence) + metric_confirmation_errors(graph, node) + read_model_confirmation_errors(graph, node) + 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 }
@@ -271,8 +272,14 @@ module RequirementGraph
     end
   end
 
-  TEST_CASE_TYPES = %w[api page permission boundary resilience migration performance].freeze
+  TEST_CASE_TYPES = %w[api page permission boundary resilience migration performance analytics freshness reconciliation].freeze
   TEST_AUTOMATION_MODES = %w[automated manual blocked].freeze
+  # A verification strategy says what would constitute trustworthy evidence.
+  # It is intentionally separate from automation_mode: a page test may be
+  # replayable yet initially manual, while an intermittent incident may be
+  # causally proven without a deterministic replay.
+  TEST_EVIDENCE_STRATEGIES = %w[replay causal observation].freeze
+  REPLAY_SCOPES = %w[component page api integration].freeze
 
   # TC nodes are derived verification intent. They deliberately store only
   # externally observable setup, operation and oracle; implementation paths,
@@ -282,7 +289,7 @@ module RequirementGraph
 
     data = node["data"].is_a?(Hash) ? node["data"] : {}
     errors = []
-    %w[acceptance_refs requirement_refs test_type target preconditions steps oracle automation_mode].each do |field|
+    %w[acceptance_refs requirement_refs test_type target preconditions steps oracle automation_mode evidence_strategy].each do |field|
       errors << "#{node["id"]}: missing #{field}" unless present?(data[field])
     end
     errors << "#{node["id"]}: acceptance_refs must be a non-empty array" unless data["acceptance_refs"].is_a?(Array) && !data["acceptance_refs"].empty?
@@ -291,6 +298,25 @@ module RequirementGraph
     errors << "#{node["id"]}: steps must be a non-empty array" unless data["steps"].is_a?(Array) && !data["steps"].empty?
     errors << "#{node["id"]}: invalid test_type" unless TEST_CASE_TYPES.include?(data["test_type"])
     errors << "#{node["id"]}: invalid automation_mode" unless TEST_AUTOMATION_MODES.include?(data["automation_mode"])
+    errors << "#{node["id"]}: invalid evidence_strategy" unless TEST_EVIDENCE_STRATEGIES.include?(data["evidence_strategy"])
+    case data["evidence_strategy"]
+    when "replay"
+      errors << "#{node["id"]}: replay tests require replay_scope" unless REPLAY_SCOPES.include?(data["replay_scope"])
+    when "causal"
+      refs = data["causal_evidence_refs"]
+      errors << "#{node["id"]}: causal tests require non-empty causal_evidence_refs" unless refs.is_a?(Array) && !refs.empty?
+      Array(refs).each do |ref|
+        errors << "#{node["id"]}: causal evidence ref #{ref} must reference SRC/CODE" unless refs_known?(graph, [ref], %w[SRC CODE])
+      end
+      errors << "#{node["id"]}: causal tests require first_divergence" unless present?(data["first_divergence"])
+    when "observation"
+      plan = data["observation_plan"]
+      errors << "#{node["id"]}: observation tests require observation_plan" unless plan.is_a?(Hash)
+      %w[signal owner window alert_condition].each do |field|
+        errors << "#{node["id"]}: observation_plan requires #{field}" unless plan.is_a?(Hash) && present?(plan[field])
+      end
+      errors << "#{node["id"]}: observation tests must remain blocked until Core-observed evidence exists" unless data["automation_mode"] == "blocked"
+    end
     if data.key?("test_obligation_refs")
       errors << "#{node["id"]}: test_obligation_refs must be a non-empty string array when present" unless data["test_obligation_refs"].is_a?(Array) && !data["test_obligation_refs"].empty? && data["test_obligation_refs"].all? { |ref| ref.is_a?(String) && ref.match?(/\AOBL-[A-Z0-9-]+\z/) }
     end
@@ -322,7 +348,9 @@ module RequirementGraph
     {
       "api_refs" => %w[API],
       "workload_refs" => %w[WSH WLC],
-      "risk_refs" => %w[RISK]
+      "risk_refs" => %w[RISK],
+      "metric_refs" => %w[METRIC],
+      "read_model_refs" => %w[RM]
     }.each do |field, prefixes|
       next unless data.key?(field)
 
@@ -504,6 +532,16 @@ module RequirementGraph
         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
+      { "metric_refs" => %w[METRIC], "read_model_refs" => %w[RM] }.each do |field, prefixes|
+        next unless data.key?(field)
+        errors << "#{node["id"]}: #{field} must be a non-empty array when present" unless data[field].is_a?(Array) && !data[field].empty?
+        Array(data[field]).each do |ref|
+          errors << "#{node["id"]}: #{field} #{ref} must exist in the graph" unless refs_known?(graph, [ref], prefixes)
+          relation = field == "metric_refs" ? "defines_metric" : "uses_read_model"
+          errors << "#{node["id"]}: #{field} #{ref} must link with #{relation}" if require_edges && !incoming_edge?(graph, ref, node["id"], relation)
+          errors << "#{node["id"]}: #{field} #{ref} must be confirmed" if require_confirmed_inputs && !confirmed?(graph, ref)
+        end
+      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])
@@ -528,6 +566,74 @@ module RequirementGraph
     errors
   end
 
+  # A metric is a business contract, not a free-text label on a dashboard.
+  # It deliberately has no status/ID input: those remain Core-owned.
+  def metric_node_errors(graph, node, require_edges: false, require_confirmed_inputs: false)
+    return [] unless node["kind"] == "metric"
+
+    data = node.fetch("data", {})
+    errors = []
+    %w[name grain measure inclusion_rule_refs exclusion_rule_refs dimensions time_basis timezone correction_policy owner].each do |field|
+      errors << "#{node["id"]}: metric missing #{field}" unless present?(data[field])
+    end
+    %w[inclusion_rule_refs exclusion_rule_refs dimensions].each do |field|
+      errors << "#{node["id"]}: #{field} must be a non-empty array" unless data[field].is_a?(Array) && !data[field].empty?
+    end
+    Array(data["inclusion_rule_refs"]) .concat(Array(data["exclusion_rule_refs"])).each do |ref|
+      errors << "#{node["id"]}: metric rule #{ref} must reference BR" unless refs_known?(graph, [ref], %w[BR])
+      errors << "#{node["id"]}: metric rule #{ref} must link with defines_metric" if require_edges && !incoming_edge?(graph, ref, node["id"], "defines_metric")
+      errors << "#{node["id"]}: metric rule #{ref} must be confirmed" if require_confirmed_inputs && !confirmed?(graph, ref)
+    end
+    errors.uniq
+  end
+
+  def metric_confirmation_errors(graph, node)
+    metric_node_errors(graph, node, require_edges: true, require_confirmed_inputs: true)
+  end
+
+  READ_MODEL_MODES = %w[direct_query materialized_view scheduled_aggregate event_projection warehouse].freeze
+  REBUILD_METHODS = %w[replay_from_fact full_recompute unknown].freeze
+  LATE_DATA_POLICIES = %w[recompute_window correction_event reject unknown].freeze
+
+  def read_model_node_errors(graph, node, require_edges: false, require_confirmed_inputs: false)
+    return [] unless node["kind"] == "read_model"
+
+    data = node.fetch("data", {})
+    errors = []
+    %w[source_of_truth_refs serves metric_contract_refs projection_mode rebuild late_data_policy reconciliation owner].each do |field|
+      errors << "#{node["id"]}: read model missing #{field}" unless present?(data[field])
+    end
+    %w[source_of_truth_refs serves metric_contract_refs].each do |field|
+      errors << "#{node["id"]}: #{field} must be a non-empty array" unless data[field].is_a?(Array) && !data[field].empty?
+    end
+    errors << "#{node["id"]}: invalid projection_mode" unless READ_MODEL_MODES.include?(data["projection_mode"])
+    errors << "#{node["id"]}: rebuild must be an object" unless data["rebuild"].is_a?(Hash)
+    errors << "#{node["id"]}: invalid rebuild.method" unless REBUILD_METHODS.include?(data.dig("rebuild", "method"))
+    errors << "#{node["id"]}: invalid late_data_policy" unless LATE_DATA_POLICIES.include?(data["late_data_policy"])
+    errors << "#{node["id"]}: reconciliation must be an object" unless data["reconciliation"].is_a?(Hash)
+    %w[method frequency].each { |field| errors << "#{node["id"]}: reconciliation missing #{field}" unless present?(data.dig("reconciliation", field)) }
+    Array(data["source_of_truth_refs"]).each do |ref|
+      errors << "#{node["id"]}: source #{ref} must reference BEH/OBJECT" unless refs_known?(graph, [ref], %w[BEH OBJECT])
+      errors << "#{node["id"]}: source #{ref} must link with derives_read_model" if require_edges && !incoming_edge?(graph, ref, node["id"], "derives_read_model")
+      errors << "#{node["id"]}: source #{ref} must be confirmed" if require_confirmed_inputs && !confirmed?(graph, ref)
+    end
+    Array(data["serves"]).each do |ref|
+      errors << "#{node["id"]}: serves #{ref} must reference API" unless refs_known?(graph, [ref], %w[API])
+      errors << "#{node["id"]}: serves #{ref} must link with serves_query" if require_edges && !incoming_edge?(graph, node["id"], ref, "serves_query")
+      errors << "#{node["id"]}: serves #{ref} must be confirmed" if require_confirmed_inputs && !confirmed?(graph, ref)
+    end
+    Array(data["metric_contract_refs"]).each do |ref|
+      errors << "#{node["id"]}: metric #{ref} must reference METRIC" unless refs_known?(graph, [ref], %w[METRIC])
+      errors << "#{node["id"]}: metric #{ref} must link with defines_read_model" if require_edges && !incoming_edge?(graph, ref, node["id"], "defines_read_model")
+      errors << "#{node["id"]}: metric #{ref} must be confirmed" if require_confirmed_inputs && !confirmed?(graph, ref)
+    end
+    errors.uniq
+  end
+
+  def read_model_confirmation_errors(graph, node)
+    read_model_node_errors(graph, node, require_edges: true, require_confirmed_inputs: true)
+  end
+
   def architecture_option_decision?(node)
     node["kind"] == "decision" && node.dig("data", "decision_type") == "architecture_option_comparison"
   end
@@ -666,6 +772,14 @@ module RequirementGraph
         results["requirement-graph-check"].concat(
           workload_node_errors(graph, node, require_edges: true, require_confirmed_inputs: node["status"] == "confirmed")
         )
+      when "metric"
+        results["requirement-graph-check"].concat(
+          metric_node_errors(graph, node, require_edges: true, require_confirmed_inputs: node["status"] == "confirmed")
+        )
+      when "read_model"
+        results["requirement-graph-check"].concat(
+          read_model_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"))
@@ -705,6 +819,13 @@ module RequirementGraph
         if node["kind"] == "workload_shape" && node.dig("data", "facts", "data_effect") == "migration"
           results["test-obligation-check"] << "#{node["id"]}: migration workload requires a migration TC with workload_refs" unless covered_by.call("migration", "workload_refs", node["id"])
         end
+        if node["kind"] == "workload_shape" && %w[analytics_query analytics_projection].include?(node.dig("data", "facts", "archetype"))
+          results["test-obligation-check"] << "#{node["id"]}: analytics workload requires an analytics TC with workload_refs" unless covered_by.call("analytics", "workload_refs", node["id"])
+        end
+      when "metric"
+        results["test-obligation-check"] << "#{node["id"]}: metric requires a reconciliation TC with metric_refs" unless covered_by.call("reconciliation", "metric_refs", node["id"])
+      when "read_model"
+        results["test-obligation-check"] << "#{node["id"]}: read model requires a freshness TC with read_model_refs" unless covered_by.call("freshness", "read_model_refs", node["id"])
       when "risk"
         if architecture_option_risk?(node)
           results["test-obligation-check"] << "#{node["id"]}: architecture risk requires a resilience TC with risk_refs" unless covered_by.call("resilience", "risk_refs", node["id"])
@@ -760,7 +881,7 @@ 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 workload_shape workload_constraint test_case]
+            when "requirement-graph", "traceability" then %w[requirement rule boundary api workload_shape workload_constraint metric read_model test_case]
             when "slices" then %w[slice]
             when "acceptance" then %w[acceptance risk decision]
             when "tests" then %w[test_case]

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

@@ -0,0 +1,159 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Controlled, content-addressed session handoff state. This script is the only
+# writer for STATE.rollover; callers must hold no assumptions about a
+# filesystem "latest" handoff. STATE is the authority and immutable handoff
+# JSON is the evidence it points to.
+
+require "digest"
+require "json"
+require "optparse"
+require "securerandom"
+require "time"
+require "yaml"
+require_relative "control_io"
+
+options = { json: false, write: false }
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: session_rollover.rb prepare|claim|consume|inspect [options]"
+  opts.on("--write", "Apply the requested transition") { options[:write] = true }
+  opts.on("--json", "Print JSON") { options[:json] = true }
+  opts.on("--expected-revision N", Integer, "STATE revision compare-and-swap") { |v| options[:expected_revision] = v }
+  opts.on("--source-session-id ID", "Source OMP session id") { |v| options[:source_session_id] = v }
+  opts.on("--target-session-id ID", "Target OMP session id") { |v| options[:target_session_id] = v }
+  opts.on("--reason TEXT", "Auditable rollover reason") { |v| options[:reason] = v }
+end
+action = ARGV.shift
+parser.parse!
+
+def fail_result(reason, details = {})
+  { "ok" => false, "reason" => reason }.merge(details)
+end
+
+def parse_state(path)
+  raw = File.read(path)
+  match = raw.match(/\A---\n(.*?)\n---\n/m)
+  raise "STATE.md is missing YAML front matter" unless match
+  [YAML.safe_load(match[1], permitted_classes: [], aliases: false), raw]
+end
+
+def write_state(path, state, previous)
+  body = previous.sub(/\A---\n.*?\n---\n/m, "")
+  front = state.to_yaml.sub(/\A---\n/, "")
+  DevflowControlIO.atomic_write(path, "---\n#{front}---\n#{body}")
+end
+
+def valid_session_id?(value)
+  value.is_a?(String) && value.match?(/\A[A-Za-z0-9][A-Za-z0-9._:-]{0,255}\z/)
+end
+
+def iso_now
+  Time.now.utc.iso8601(3)
+end
+
+root = Dir.pwd
+state_path, = DevflowControlIO.resolve_control_path(root, ".planning/STATE.md", :state)
+result = catch(:transition_done) do
+  lock = DevflowControlIO.acquire_project_lock(root)
+  begin
+  unless File.exist?(state_path)
+    result = fail_result("missing_state")
+    throw :transition_done, result
+  end
+  state, raw = parse_state(state_path)
+  revision = Integer(state.fetch("revision", 0))
+  if !options[:expected_revision].nil? && revision != options[:expected_revision]
+    result = fail_result("stale_revision", "expected_revision" => options[:expected_revision], "actual_revision" => revision)
+    throw :transition_done, result
+  end
+  rollover = state["rollover"]
+
+  case action
+  when "inspect"
+    result = { "ok" => true, "revision" => revision, "rollover" => rollover }
+  when "prepare"
+    unless valid_session_id?(options[:source_session_id])
+      result = fail_result("invalid_source_session_id")
+      throw :transition_done, result
+    end
+    if rollover && %w[prepared claimed].include?(rollover["status"])
+      result = fail_result("rollover_in_progress", "rollover" => rollover)
+      throw :transition_done, result
+    end
+    rollover_id = "ROL-#{SecureRandom.uuid}"
+    relative_path = ".planning/handoffs/#{state.fetch("current_feature")}/#{rollover_id}.json"
+    absolute_path, = DevflowControlIO.resolve_control_path(root, relative_path, :handoff)
+    payload = {
+      "schema_version" => 1,
+      "rollover_id" => rollover_id,
+      "created_at" => iso_now,
+      "reason" => options[:reason].to_s.empty? ? "workflow_step_boundary" : options[:reason],
+      "source_session_id" => options[:source_session_id],
+      "state" => {
+        "revision" => revision,
+        "current_flow" => state["current_flow"], "current_feature" => state["current_feature"],
+        "current_phase" => state["current_phase"], "current_step" => state["current_step"],
+        "status" => state["status"], "completed_steps" => state["completed_steps"], "pending_steps" => state["pending_steps"]
+      },
+      "references" => {
+        "state_path" => ".planning/STATE.md",
+        "workflow_path" => state["workflow_config"],
+        "artifact_registry" => ".planning/artifacts/index.yaml"
+      }
+    }
+    serialized = JSON.generate(payload) + "\n"
+    digest = Digest::SHA256.hexdigest(serialized)
+    if options[:write]
+      DevflowControlIO.atomic_create(absolute_path, serialized)
+      state["rollover"] = {
+        "id" => rollover_id, "status" => "prepared", "handoff_path" => relative_path,
+        "handoff_sha256" => digest, "source_session_id" => options[:source_session_id],
+        "target_session_id" => nil, "expected_state_revision" => revision,
+        "prepared_at" => iso_now, "claimed_at" => nil
+      }
+      state["revision"] = revision + 1
+      write_state(state_path, state, raw)
+    end
+    result = { "ok" => true, "written" => options[:write], "rollover" => options[:write] ? state["rollover"] : payload.merge("handoff_sha256" => digest), "revision" => options[:write] ? revision + 1 : revision }
+  when "claim"
+    unless rollover.is_a?(Hash) && rollover["status"] == "prepared"
+      result = fail_result("rollover_not_prepared", "rollover" => rollover)
+      throw :transition_done, result
+    end
+    unless valid_session_id?(options[:target_session_id])
+      result = fail_result("invalid_target_session_id")
+      throw :transition_done, result
+    end
+    path, = DevflowControlIO.resolve_control_path(root, rollover["handoff_path"], :handoff)
+    unless File.exist?(path) && Digest::SHA256.hexdigest(File.binread(path)) == rollover["handoff_sha256"]
+      result = fail_result("handoff_integrity_failure")
+      throw :transition_done, result
+    end
+    if options[:write]
+      rollover["status"] = "claimed"; rollover["target_session_id"] = options[:target_session_id]; rollover["claimed_at"] = iso_now
+      state["rollover"] = rollover; state["revision"] = revision + 1; write_state(state_path, state, raw)
+    end
+    result = { "ok" => true, "written" => options[:write], "rollover" => rollover, "revision" => options[:write] ? revision + 1 : revision }
+  when "consume"
+    unless rollover.is_a?(Hash) && rollover["status"] == "claimed" && valid_session_id?(options[:target_session_id]) && rollover["target_session_id"] == options[:target_session_id]
+      result = fail_result("rollover_not_owned_by_target", "rollover" => rollover)
+      throw :transition_done, result
+    end
+    if options[:write]
+      rollover["status"] = "consumed"; rollover["consumed_at"] = iso_now
+      state["rollover"] = rollover; state["revision"] = revision + 1; write_state(state_path, state, raw)
+    end
+    result = { "ok" => true, "written" => options[:write], "rollover" => rollover, "revision" => options[:write] ? revision + 1 : revision }
+  else
+    result = fail_result("unknown_action")
+  end
+rescue DevflowControlIO::InvalidControlPath, Psych::Exception, SystemCallError, RuntimeError => error
+  result = fail_result("rollover_transition_failed", "message" => error.message)
+ensure
+  DevflowControlIO.release_lock(lock)
+  end
+end
+
+puts JSON.pretty_generate(result)
+exit(result["ok"] ? 0 : 1)

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

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "digest"
 require "optparse"
 require "yaml"
 require_relative "control_io"
@@ -42,6 +43,7 @@ module WorkflowStateValidator
     REQUIRED_STATE_FIELDS.each do |field|
       issues << issue("error", "missing_state_field", "STATE.md is missing required field: #{field}", field: field) unless state.key?(field)
     end
+    validate_rollover(issues, root, state)
     return result(false, state_path, nil, nil, issues) if issues.any? { |entry| entry["severity"] == "error" }
 
     ownership = PhaseOwnership.validate_state(root: root, state: state, owner_override: phase_owner_override)
@@ -122,6 +124,40 @@ module WorkflowStateValidator
     nil
   end
 
+  def validate_rollover(issues, root, state)
+    rollover = state["rollover"]
+    return if rollover.nil?
+    unless rollover.is_a?(Hash)
+      issues << issue("error", "invalid_rollover", "STATE.rollover must be an object")
+      return
+    end
+    status = rollover["status"]
+    unless %w[prepared claimed consumed failed].include?(status)
+      issues << issue("error", "invalid_rollover_status", "STATE.rollover.status is invalid", status: status)
+      return
+    end
+    %w[id handoff_path handoff_sha256 source_session_id prepared_at].each do |field|
+      issues << issue("error", "missing_rollover_field", "STATE.rollover is missing #{field}", field: field) unless rollover[field].is_a?(String) && !rollover[field].empty?
+    end
+    return if issues.any? { |entry| entry["severity"] == "error" }
+    begin
+      handoff_path, = DevflowControlIO.resolve_control_path(root, rollover["handoff_path"], :handoff)
+      if %w[prepared claimed consumed].include?(status) && !File.exist?(handoff_path)
+        issues << issue("error", "missing_rollover_handoff", "STATE.rollover references a missing immutable handoff", path: rollover["handoff_path"])
+      elsif File.exist?(handoff_path) && Digest::SHA256.hexdigest(File.binread(handoff_path)) != rollover["handoff_sha256"]
+        issues << issue("error", "rollover_handoff_hash_mismatch", "STATE.rollover handoff hash does not match immutable payload", path: rollover["handoff_path"])
+      end
+    rescue DevflowControlIO::InvalidControlPath => error
+      issues << issue("error", "invalid_rollover_handoff_path", error.message)
+    end
+    if rollover["handoff_sha256"].to_s !~ /\A[0-9a-f]{64}\z/
+      issues << issue("error", "invalid_rollover_handoff_hash", "STATE.rollover.handoff_sha256 must be SHA-256 hex")
+    end
+    if status == "claimed" && (rollover["target_session_id"].to_s.empty? || rollover["claimed_at"].to_s.empty?)
+      issues << issue("error", "incomplete_rollover_claim", "Claimed rollover requires target_session_id and claimed_at")
+    end
+  end
+
   def load_yaml(path, issues, code)
     unless File.exist?(path)
       issues << issue("error", "missing_#{code}", "YAML file does not exist", path: path)

package/plugins/devflow-design/skills/workflow-api-contract/SKILL.md

@@ -43,9 +43,10 @@ The meta file must also set `traceability_status: "passed"` only after every API
 1. **只定义接口契约，不谈实现细节** — 不写数据表结构、不写具体代码、不写业务流程内部逻辑
 2. **分叉后不变更** — 一旦确定，Track A/B 都基于此契约工作。变更走 `api-supplement` 异常路径
 3. **接口签名必须完整** — 包括 endpoint、method、请求参数（含类型约束）、响应结构（含状态码）、错误契约与行为语义（过滤、排序、权限、幂等/兼容规则）
-4. **数据模型共享** — 核心业务实体定义在这里，前后端共用一个数据模型
-5. **切片对齐** — 若 baseline 包含 `SL-*`，先读取 `skill://workflow-pipeline/references/slice-safety-guide.md`，只为当前执行切片定义 API。后置切片接口不得提前进入契约。
-6. **既有接口优先查事实索引** — 当 `.planning/code-index/` 存在时，先用 Symbol/Relation 定位候选接口、调用方和处理器，再读取源码证据；缺失或过期时再按 navigation 和 `rg` 兜底。
+4. **负载职责明确** — 事务命令、运营查询和统计查询不得在同一个接口语义中混写；统计查询必须引用已确认的 `METRIC-*`，并在响应中约定 `as_of`/新鲜度语义或明确强一致依据。
+5. **数据模型共享** — 核心业务实体定义在这里，前后端共用一个数据模型
+6. **切片对齐** — 若 baseline 包含 `SL-*`，先读取 `skill://workflow-pipeline/references/slice-safety-guide.md`，只为当前执行切片定义 API。后置切片接口不得提前进入契约。
+7. **既有接口优先查事实索引** — 当 `.planning/code-index/` 存在时，先用 Symbol/Relation 定位候选接口、调用方和处理器，再读取源码证据；缺失或过期时再按 navigation 和 `rg` 兜底。
 
 ## 可测试 API 契约（强制）
 

package/plugins/devflow-design/skills/workflow-architecture-feasibility/SKILL.md

@@ -15,6 +15,8 @@ description: "Use after API contract and before frontend/backend technical speci
    - WSH 使用 `workload_shape`，并连接 `REQ/BEH/API → WSH`，relation 为 `shapes_workload`。
    - WLC 使用 `workload_constraint`，并连接 `BEH/SL/API → WLC`，relation 为 `constrains_workload`。
    - `unknown` 只能写缺口、责任人、截止 checkpoint；不能填 target、evidence 或 assumption。
+   - 每个新增/变更的 API、BEH、Job 至少归类为 `transactional_command`、`operational_query`、`analytics_query`、`analytics_projection`、`batch_processing` 或 `external_integration`；历史节点没有 `archetype` 时按 legacy 处理，不倒逼补录。
+   - `analytics_query` 必须关联 `METRIC-*`；`analytics_projection` 还必须关联 `RM-*`。先提交指标口径（粒度、纳入/排除规则、时间字段/时区、修正规则、owner），再提交读模型（事实源、服务 API、投影/刷新方式、重建、迟到数据和对账）。
 4. 对 `lightweight` 或 `full` 且存在实质取舍的结果，提交 `decision_type: architecture_option_comparison` 的 `DECISION` candidate：
    - `subject_refs` 只引用 WSH/WLC；WSH 用 `informs_decision` 连到 DECISION，WLC 用 `constrains_decision` 连到 DECISION。
    - 每个 option 使用 `option_key`，并包含 `mechanism`、非空 `fact_refs`、非空 `tradeoffs`。
@@ -31,6 +33,8 @@ description: "Use after API contract and before frontend/backend technical speci
 - `assessment_status: incomplete`、`comparison_status: missing` 或 `awaiting_*` 必须原样交给下游技术方案，不能写成“评估通过”。
 - 已确认 WSH/WLC/架构 DECISION/RISK 不可原地更新；新建 candidate、重新连边，并让 stale 传播要求消费者复核。
 - 不替用户选择方案、接受残余风险或伪造 CP 记录。
+- 业务事实表是唯一可审计真相源；`RM-*` 是可重建的派生读模型，不能被业务命令当作事实源回写。
+- 不因“统计”自动要求拆库、消息队列或数仓。`direct_query`、物化视图、定时汇总、事件投影和数仓必须根据 WSH/WLC 给出有实质差异的比较与升级条件。
 
 ## 下游交接
 

package/plugins/devflow-design/skills/workflow-backend-tech-spec/SKILL.md

@@ -48,6 +48,8 @@ allowed-tools:
 
 读取 `.planning/requirements/{feature}/traceability.json`。每个设计章节必须列 `覆盖 REQ: REQ-*`；定时任务、批处理、导入和通知至少拆为“编排（扫描/触发/锁/重试）”与“业务算法（判定/计算/写入）”两个可独立验证的小节。不得把遍历全部活跃组织、发送通知、文件解析等编排事实藏在算法描述中。
 
+当架构简报包含 `analytics_query`、`analytics_projection`、`METRIC-*` 或 `RM-*` 时，后端方案额外必须分别写明：业务事实源；指标粒度/纳入排除/时区与修正；读模型或直接聚合路径；索引/扫描范围；新鲜度；watermark/迟到数据；重建与对账。不得把统计 SQL 混进事务命令，或以“后续补统计”跳过这些字段。
+
 根据需求基线和项目现有代码，生成聚焦于影响分析的后端技术方案。
 
 ## 核心原则

package/plugins/devflow-quality/skills/workflow-acceptance-test-design/SKILL.md

@@ -7,6 +7,14 @@ description: "Use after integration verification and before change planning to d
 
 在代码执行前，基于已确认的需求、契约和架构约束提出独立的 `TC-*` 验收测试候选。测试意图必须独立于实现：禁止读取 `SUMMARY.md`、实现源码、git diff 或 agent 交付自述来决定测试范围。
 
+## 执行合同
+
+本步骤的图谱写入受 ExecutionContract v2 约束：`devflow_requirement_graph(action="propose", kind="test_case")` 与 `devflow_api_test_matrix(action="import")` 仅在 active contract 的 step 为 `acceptance-test-design` 时放行。步骤开始且无 active contract 时：
+
+1. 先调用 `devflow_contract(action="status")` 检查当前会话是否有 active contract；
+2. 未激活时调用 `devflow_contract(action="activate", feature="<feature>", step="acceptance-test-design")` 合成并激活（planning / waiting-user / awaiting-approval 阶段均可，Core 校验 STATE 与图谱 revision 后由用户确认）；
+3. 会话中断后 contract 由 runtime 在 `session_start` 时从 `.planning/contracts/{feature}/EC-*.json` 自动恢复；恢复时校验 state/graph revision，推进后自动失效，需重新合成。
+
 ## 输入
 
 按顺序读取：
@@ -39,11 +47,15 @@ description: "Use after integration verification and before change planning to d
   "preconditions": ["身份、数据和环境前置条件"],
   "steps": ["测试操作"],
   "oracle": "可观察的预期结果",
-  "automation_mode": "automated|manual|blocked"
+  "automation_mode": "automated|manual|blocked",
+  "evidence_strategy": "replay|causal|observation"
 }
 ```
 
 - `manual` 额外写 `manual_reason` 和 `owner`；`blocked` 额外写 `blocked_by` 和 `owner`。
+- `replay`：可用稳定步骤再次触发，必须写 `replay_scope`（`component|page|api|integration`）。页面优先拆到组件、页面、接口或集成边界，不要求 AI 在真实环境盲目重试。
+- `causal`：用于已由 HAR、控制台、DOM 快照、服务日志或请求链路证明首个偏差、但暂不能稳定重放的缺陷。必须写 `causal_evidence_refs`（已有 `SRC-*` / `CODE-*`）和 `first_divergence`；后续执行绑定还必须提供实际证据文件，Core 会哈希留档。没有这些证据不能称为“已证实”。
+- `observation`：用于当前无法重放也无法证明根因的偶发问题。必须写 `observation_plan` 的 `signal`、`owner`、`window`、`alert_condition`，且 `automation_mode` 必须为 `blocked`。它会阻止版本收口，不能被“人工已看过”替代。
 - 当 TC 承接结构性专项义务时，额外带对应引用并建立同样的 `verified_by` edge：`api_refs`（API→`api`）、`workload_refs`（WSH/WLC→`performance` 或 `migration`）、`risk_refs`（架构 RISK→`resilience`）。跨数据域的 REQ 必须有 `permission` TC，BC 必须有 `boundary` TC。
 - 页面/API 的具体 selector、endpoint URL、测试数据和 runner 命令属于后续执行绑定，不得改变本步骤的步骤或 oracle。
 - 高风险边界、权限、迁移、外部依赖和工作负载事实必须产生相应 TC；`test-obligation-check` 是机器判定，不接受“无架构影响”的模型自述。环境未准备好只能标记 blocked，不得省略。

package/plugins/devflow-quality/skills/workflow-run-acceptance-tests/SKILL.md

@@ -36,6 +36,8 @@ description: "Execute the frozen TC acceptance suite after code review. Use the
    - 通用自动化用例使用 `{ "kind": "command", "argv": [ ... ] }`，不使用 shell 字符串；
    - Core 生成的 API TC 可直接使用 `{ "kind": "http", "base_url_env": "DEVFLOW_TEST_BASE_URL", "headers_env": { "Authorization": "DEVFLOW_TEST_AUTHORIZATION" } }`。请求、HTTP 状态和异常码断言来自冻结 TC 的 `execution`，绑定只能提供环境地址和鉴权，不得重写测试意图；若场景需要专用夹具，可额外配置 `{ "setup": { "argv": [ ... ] } }`，Core 会先记录并执行该受控命令，再发 HTTP 请求；
    - 人工或环境阻塞用例必须有 owner 与原因/阻塞源。
+   - `evidence_strategy=causal` 的自动用例额外写 `evidence_files`（项目根目录内的 HAR、控制台、DOM 快照、截图或日志文件相对路径）。Core 在执行前校验文件存在且未越出项目根目录，并把内容哈希写入结果；不能只填 Markdown 描述。
+   - `evidence_strategy=observation` 只能保持 `blocked`，其观测计划是风险收口输入，不是测试通过证据。
 5. 调用 `devflow_run_acceptance_tests(action="validate", feature=...)`。不通过时修正绑定，不得绕过。
 6. 调用 `devflow_run_acceptance_tests(action="run", feature=...)`。该 Core 工具记录每个 TC 的命令哈希、退出码和输出摘要。
 7. 失败、未执行或 blocked 的 TC 只能报告为 `blocked`/`failed`，不得进入版本收口。