@guanlin4924/devflow-pi 0.1.24 → 0.1.25

package/README.md

@@ -130,6 +130,7 @@ bash .skills/install.sh --apply --force-config
 - `TC-*` 的步骤和 oracle 在代码出现前冻结；CP-3 在同一次确认中先校验候选绑定，再冻结 TC 并固定绑定哈希。需求或契约变化会使它 stale，不能继续以旧测试集宣称通过。
 - `tdd_required` 任务必须先由 Core 记录准备快照，再记录 RED（命中预期失败）、同一目标的 GREEN 和回归；缺失或环境失败不算完成。
 - API、跨数据域、边界、迁移、工作负载与架构风险会派生相应的 `api`、`permission`、`boundary`、`migration`、`performance`、`resilience` TC 义务。
+- 每个 TC 还要声明证明策略：`replay` 用组件/页面/API/集成的稳定回放；`causal` 用已定位的首个偏差加 HAR、控制台、DOM 快照、截图或日志等受控文件证明，Core 会记录文件哈希；`observation` 用于尚不可复现、也未能证明根因的问题，只能保持阻塞并带观测计划。后两者都不能被“AI 已复现”或 Markdown 自述放行。
 - 代码完成后，`workflow-run-acceptance-tests` 只能运行绑定到冻结 TC、且已在初始化 `.planning/toolchain.md` 发现的测试运行器命令。任何失败、未执行、人工待执行或环境阻塞用例都会阻止 CP-4。
 - 验收不是代码完成后的临时手工检查。它是需求基线在编码前派生并冻结的完整测试集，覆盖主流程、异常、边界、权限、迁移、兼容、韧性和工作负载义务；代码只能补充执行适配信息，不能改变测试意图。
 - 验收失败不会创建另一套人工台账，而是进入 `acceptance-remediation`：诊断 → 修复 → code-index 刷新 → 原冻结 `TC-*` 重跑。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "type": "module",
   "description": "Devflow 专项研发 Pi，基于固定版本 OMP Runtime 组装研发状态机、代码智能、设计、实现与质量门禁。",
   "license": "UNLICENSED",

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/acceptance_test_runner.py

@@ -20,6 +20,8 @@ from test_command_policy import validate_test_command
 
 FEATURE_RE = re.compile(r"^[^/\\\x00-\x1f\x7f]+$")
 AUTOMATION_MODES = {"automated", "manual", "blocked"}
+EVIDENCE_STRATEGIES = {"replay", "causal", "observation"}
+MAX_EVIDENCE_FILE_BYTES = 25 * 1024 * 1024
 
 
 def utc_now() -> str:
@@ -142,6 +144,38 @@ def file_fingerprint(path: Path) -> str | None:
     return digest(path.read_bytes()) if path.is_file() else None
 
 
+def evidence_artifacts(root: Path, value: Any) -> tuple[list[dict[str, Any]], list[str]]:
+    """Hash causal evidence from bounded project-relative files only."""
+    if not isinstance(value, list) or not value:
+        return [], ["causal verification requires non-empty evidence_files"]
+    root_real = root.resolve()
+    artifacts: list[dict[str, Any]] = []
+    errors: list[str] = []
+    for raw in value:
+        if not isinstance(raw, str) or not raw.strip() or "\x00" in raw:
+            errors.append("evidence_files entries must be non-empty relative paths")
+            continue
+        candidate = Path(raw)
+        if candidate.is_absolute() or ".." in candidate.parts:
+            errors.append(f"evidence file escapes project root: {raw}")
+            continue
+        resolved = (root_real / candidate).resolve()
+        try:
+            relative = resolved.relative_to(root_real)
+        except ValueError:
+            errors.append(f"evidence file escapes project root: {raw}")
+            continue
+        if not resolved.is_file():
+            errors.append(f"causal evidence file is missing: {raw}")
+            continue
+        size = resolved.stat().st_size
+        if size > MAX_EVIDENCE_FILE_BYTES:
+            errors.append(f"causal evidence file exceeds {MAX_EVIDENCE_FILE_BYTES} bytes: {raw}")
+            continue
+        artifacts.append({"path": relative.as_posix(), "sha256": digest(resolved.read_bytes()), "bytes": size})
+    return artifacts, errors
+
+
 def run_http_case(source: dict[str, Any], adapter: dict[str, Any]) -> tuple[bool, int, str]:
     execution = source["execution"]
     request_spec = execution["request"]
@@ -248,6 +282,11 @@ def validate(root: Path, feature: str) -> tuple[dict[str, Any], dict[str, Any] |
         if source is None:
             errors.append(f"unknown TC reference: {tc_id}")
             continue
+        strategy = source.get("evidence_strategy")
+        if strategy is not None and strategy not in EVIDENCE_STRATEGIES:
+            errors.append(f"{label}.source evidence_strategy is invalid")
+        if strategy == "observation" and source.get("automation_mode") != "blocked":
+            errors.append(f"{label}.observation source must be blocked")
         mode = entry.get("mode")
         if mode not in AUTOMATION_MODES:
             errors.append(f"{label}.mode is invalid")
@@ -278,6 +317,9 @@ def validate(root: Path, feature: str) -> tuple[dict[str, Any], dict[str, Any] |
                             errors.append(f"{label}.adapter.setup: {setup_error}")
             else:
                 errors.append(f"{label}.adapter kind must be command or http")
+            if strategy == "causal":
+                _artifacts, artifact_errors = evidence_artifacts(root, entry.get("evidence_files"))
+                errors.extend(f"{label}.{error}" for error in artifact_errors)
         elif mode == "manual":
             if not isinstance(entry.get("owner"), str) or not entry["owner"].strip() or not isinstance(entry.get("reason"), str) or not entry["reason"].strip():
                 errors.append(f"{label}.manual requires owner and reason")
@@ -303,6 +345,7 @@ def run(root: Path, feature: str, write: bool) -> dict[str, Any]:
     for entry in bindings["cases"]:
         tc_id = entry["tc_id"]
         mode = entry["mode"]
+        strategy = cases[tc_id].get("evidence_strategy")
         if mode == "automated":
             started_at = utc_now()
             adapter = entry["adapter"]
@@ -326,6 +369,13 @@ def run(root: Path, feature: str, write: bool) -> dict[str, Any]:
                 result = {"tc_id": tc_id, "status": "passed" if passed else "failed", "mode": mode, "adapter_kind": "http",
                           "adapter_fingerprint": digest(json.dumps(adapter, ensure_ascii=False, separators=(",", ":"))), "started_at": started_at,
                           "finished_at": utc_now(), "exit_code": exit_code, "output_sha256": digest(output)}
+            if strategy == "causal":
+                artifacts, artifact_errors = evidence_artifacts(root, entry.get("evidence_files"))
+                if artifact_errors:
+                    result["status"] = "failed"
+                    result["evidence_error"] = "; ".join(artifact_errors)
+                else:
+                    result["evidence_artifacts"] = artifacts
             results.append(result)
         elif mode == "manual":
             results.append({"tc_id": tc_id, "status": "blocked", "mode": mode, "owner": entry["owner"], "reason": entry["reason"],

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/api_test_matrix.py

@@ -554,6 +554,8 @@ def tc_candidate(api: dict[str, Any], graph: dict[str, Any], key: str, obligatio
         "steps": ["发送 execution.request 中定义的 HTTP 请求"],
         "oracle": oracle,
         "automation_mode": "automated",
+        "evidence_strategy": "replay",
+        "replay_scope": "api",
         "api_refs": [api["id"]],
         "execution": execution,
     }

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

@@ -96,13 +96,29 @@ module ArchitectureBrief
       assessment["triggers"].each { |trigger| lines << "- `#{trigger["code"]}` — #{trigger["node_id"]}" }
     end
 
-    lines.concat(["", "## 工作负载形态", "", "| 节点 | 状态 | 执行 | 操作 | 扇出 | 数据影响 | 外部调用 |", "|---|---|---|---|---|---|---|"])
+    lines.concat(["", "## 工作负载形态", "", "| 节点 | 状态 | 类型 | 一致性 | 执行 | 操作 | 扇出 | 数据影响 |", "|---|---|---|---|---|---|---|---|"])
     if workload_shapes.empty?
-      lines << "| — | — | — | — | — | — | — |"
+      lines << "| — | — | — | — | — | — | — | — |"
     else
       workload_shapes.each do |node|
         facts = node.fetch("data", {}).fetch("facts", {})
-        lines << "| #{node["id"]} | #{node["status"]} | #{text(facts["execution"])} | #{text(facts["operation"])} | #{text(facts["fanout"])} | #{text(facts["data_effect"])} | #{text(Array(facts["external_calls"]).join(", "))} |"
+        lines << "| #{node["id"]} | #{node["status"]} | #{text(facts["archetype"] || "legacy")} | #{text(facts["consistency"] || "—")} | #{text(facts["execution"])} | #{text(facts["operation"])} | #{text(facts["fanout"])} | #{text(facts["data_effect"])} |"
+      end
+    end
+
+    metrics = Array(graph["nodes"]).select { |node| node["kind"] == "metric" }
+    read_models = Array(graph["nodes"]).select { |node| node["kind"] == "read_model" }
+    lines.concat(["", "## 统计指标与读模型", "", "| 节点 | 状态 | 定义/服务对象 | 时间与修正 |", "|---|---|---|---|"])
+    if metrics.empty? && read_models.empty?
+      lines << "| — | — | — | — |"
+    else
+      metrics.each do |node|
+        data = node.fetch("data", {})
+        lines << "| #{node["id"]} | #{node["status"]} | 指标：#{text(data["name"])}；粒度：#{text(data["grain"])} | #{text(data["time_basis"])} / #{text(data["timezone"])}；#{text(data["correction_policy"])} |"
+      end
+      read_models.each do |node|
+        data = node.fetch("data", {})
+        lines << "| #{node["id"]} | #{node["status"]} | 读模型：#{text(data["projection_mode"])}；服务：#{text(Array(data["serves"]).join(", "))} | 重建：#{text(data.dig("rebuild", "method"))}；迟到数据：#{text(data["late_data_policy"])} |"
       end
     end
 

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

@@ -13,6 +13,10 @@ module ArchitectureConstraints
   OPERATIONS = %w[read write batch_read batch_write].freeze
   FANOUTS = %w[none bounded unbounded unknown].freeze
   DATA_EFFECTS = %w[none update append_only migration unknown].freeze
+  ARCHETYPES = %w[transactional_command operational_query analytics_query analytics_projection batch_processing external_integration].freeze
+  DATA_ROLES = %w[source_of_truth derived_read_model external_projection].freeze
+  CONSISTENCIES = %w[strong read_your_write bounded_staleness eventual unknown].freeze
+  EVENT_TIMES = %w[required not_applicable unknown].freeze
   METRICS = %w[peak_qps data_growth p95_latency rpo rto].freeze
   SOURCE_STATUSES = %w[measured contracted approved_assumption unknown].freeze
   EVIDENCE_KINDS = %w[source_file cp_record external_measurement].freeze
@@ -52,6 +56,26 @@ module ArchitectureConstraints
     errors_for_enum(errors, facts, "data_effect", DATA_EFFECTS)
     external_calls = facts["external_calls"]
     errors << "external_calls must be an array" unless external_calls.nil? || external_calls.is_a?(Array)
+    # `archetype` is optional for pre-v5 graphs. Once supplied it is a
+    # contract, not prose: analytics shapes must say what they serve and how
+    # their time semantics behave.
+    if facts.key?("archetype")
+      errors_for_enum(errors, facts, "archetype", ARCHETYPES)
+      errors_for_enum(errors, facts, "data_role", DATA_ROLES)
+      errors_for_enum(errors, facts, "consistency", CONSISTENCIES)
+      time = facts["time_semantics"]
+      errors << "time_semantics must be an object" unless time.is_a?(Hash)
+      errors_for_enum(errors, time || {}, "event_time", EVENT_TIMES)
+      errors << "time_semantics.timezone is required" unless present?(time && time["timezone"])
+      if %w[analytics_query analytics_projection].include?(facts["archetype"])
+        refs = shape["metric_refs"]
+        errors << "analytics workloads require non-empty metric_refs" unless refs.is_a?(Array) && !refs.empty?
+      end
+      if facts["archetype"] == "analytics_projection"
+        refs = shape["read_model_refs"]
+        errors << "analytics projections require non-empty read_model_refs" unless refs.is_a?(Array) && !refs.empty?
+      end
+    end
     source_refs = shape["source_refs"]
     errors << "source_refs must be a non-empty array" unless source_refs.is_a?(Array) && !source_refs.empty?
     Array(source_refs).each { |ref| errors << "source_refs must reference REQ/BEH/API" unless reference?(ref, %w[REQ BEH API]) }

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/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-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

@@ -39,11 +39,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`，不得进入版本收口。

package/src/constants.ts

@@ -1,5 +1,5 @@
 export const PRODUCT_NAME = "Devflow Pi";
-export const PRODUCT_VERSION = "0.1.24";
+export const PRODUCT_VERSION = "0.1.25";
 export const PROJECT_SCHEMA_VERSION = 1;
 export const OMP_RUNTIME_VERSION = "17.2.7";