@guanlin4924/devflow-pi 0.1.19 → 0.1.21

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

@@ -12,12 +12,14 @@ 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 change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[api] },
+  "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] },
   "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] },
-  "change-plan" => { "checkers" => %w[requirement-graph-check slice-independence-check contract-coverage-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[acceptance] },
-  "execute" => { "checkers" => %w[change-impact-check], "agents" => ["implementation-worker"], "budget" => 1, "allowed_graph_delta" => %w[requirement rule boundary behavior] },
-  "verify" => { "checkers" => %w[acceptance-coverage-check change-impact-check], "agents" => ["verification-runner"], "budget" => 1, "allowed_graph_delta" => %w[acceptance] }
+  "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] },
+  "execute" => { "checkers" => %w[tdd-evidence-check change-impact-check], "agents" => ["implementation-worker"], "budget" => 1, "allowed_graph_delta" => %w[requirement rule boundary behavior] },
+  "run-acceptance-tests" => { "checkers" => %w[api-test-matrix-check test-coverage-check acceptance-test-results-check change-impact-check], "agents" => ["verification-runner"], "budget" => 1, "allowed_graph_delta" => [] },
+  "verify" => { "checkers" => %w[acceptance-coverage-check acceptance-test-results-check change-impact-check], "agents" => ["verification-runner"], "budget" => 1, "allowed_graph_delta" => %w[acceptance] }
 }.freeze
 
 options = { feature: nil, step: nil, expected_state_revision: nil, expected_graph_revision: nil, write: false, json: false }
@@ -67,7 +69,7 @@ begin
     "state_revision" => state["revision"], "graph_revision" => graph["revision"], "workflow_path" => workflow_relative,
     "workflow_fingerprint" => Digest::SHA256.hexdigest(workflow_raw), "manifest_id" => "devflow-core-execution-policy-v2",
     "allowed_paths" => paths, "allowed_agents" => policy["agents"], "checker_ids" => policy["checkers"],
-    "allowed_tools" => %w[read grep find glob lsp search write edit apply_patch bash shell exec_command task],
+    "allowed_tools" => %w[read grep find glob lsp search write edit apply_patch bash shell exec_command task devflow_api_test_matrix devflow_tdd_evidence devflow_run_acceptance_tests],
     "tool_budget" => policy["budget"], "acceptance" => Array(graph["nodes"]).select { |node| node["kind"] == "acceptance" }.map { |node| node["id"] },
     "allowed_graph_delta" => Array(policy["allowed_graph_delta"]),
     "on_unknown" => "block_and_escalate"

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

@@ -87,7 +87,17 @@ fallback_pending_steps = [
 ]
 pending_steps = if File.exist?(workflow_path)
                   workflow = YAML.safe_load(File.read(workflow_path), permitted_classes: [], aliases: false)
-                  Array(workflow["steps"]).map { |step| step.fetch("id") }
+                  # The template is authored in readable sections, so physical
+                  # YAML position is not a scheduling contract. A step with an
+                  # explicit order must initialize ahead of later ordered
+                  # steps even when it was inserted lower in the document.
+                  Array(workflow["steps"])
+                    .each_with_index
+                    .sort_by do |(step, index)|
+                      order = step["order"]
+                      [order.is_a?(Integer) ? 0 : 1, order.is_a?(Integer) ? order : index, index]
+                    end
+                    .map { |(step, _index)| step.fetch("id") }
                 else
                   fallback_pending_steps
                 end

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

@@ -148,7 +148,11 @@ end
 
 def next_pending_step_id(state, pending_ids, step_by_id, completed_ids)
   track = active_track(state)
-  return pending_ids.first unless track
+  unless track
+    return pending_ids.find do |step_id|
+      step_by_id[step_id] && dependencies_satisfied?(step_by_id[step_id], completed_ids)
+    end
+  end
 
   allowed = track_allowed_steps(track)
   pending_ids.find do |step_id|

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

@@ -5,6 +5,7 @@
 # and canonical graph. Agent text is never used to decide completion.
 require "digest"
 require "json"
+require "open3"
 require "optparse"
 require "yaml"
 require_relative "control_io"
@@ -37,14 +38,46 @@ def configured_checkers(workflow, step_id)
   return Array(explicit) if explicit
   case step_id
   when "requirement-baseline" then %w[requirement-graph-check slice-independence-check acceptance-coverage-check change-impact-check]
-  when "api-contract" then %w[requirement-graph-check contract-coverage-check change-impact-check]
+  when "api-contract" then %w[requirement-graph-check contract-coverage-check api-test-schema-check change-impact-check]
   when "architecture-feasibility" then %w[requirement-graph-check change-impact-check]
-  when "integration-verify", "change-plan" then %w[requirement-graph-check slice-independence-check contract-coverage-check change-impact-check]
-  when "verify" then %w[acceptance-coverage-check change-impact-check]
+  when "integration-verify" then %w[requirement-graph-check slice-independence-check contract-coverage-check change-impact-check]
+  when "change-plan" then %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]
+  when "acceptance-test-design" then %w[requirement-graph-check contract-coverage-check acceptance-coverage-check api-test-matrix-check test-coverage-check test-obligation-check change-impact-check]
+  when "run-acceptance-tests" then %w[api-test-matrix-check test-coverage-check acceptance-test-results-check change-impact-check]
+  when "verify" then %w[acceptance-coverage-check acceptance-test-results-check change-impact-check]
+  when "execute" then %w[tdd-evidence-check change-impact-check]
   else []
   end
 end
 
+def supplemental_checker(root, feature, id, step_id)
+  command = case id
+            when "test-task-binding-check"
+              stage = step_id == "change-plan" ? "candidate" : "frozen"
+              [File.join(__dir__, "test_task_binding_check.py"), "--feature", feature, "--stage", stage, "--json"]
+            when "tdd-evidence-check"
+              [File.join(__dir__, "tdd_evidence.py"), "validate", "--feature", feature, "--json"]
+            when "acceptance-test-results-check"
+              [File.join(__dir__, "acceptance_test_runner.py"), "validate-results", "--feature", feature, "--json"]
+            when "api-test-matrix-check"
+              [File.join(__dir__, "api_test_matrix.py"), "validate", "--feature", feature, "--json"]
+            when "api-test-schema-check"
+              [File.join(__dir__, "api_test_matrix.py"), "check", "--feature", feature, "--json"]
+            end
+  return nil unless command
+
+  stdout, stderr, status = Open3.capture3("python3", *command, chdir: root)
+  payload = JSON.parse(stdout)
+  issues = payload.is_a?(Hash) && payload["errors"].is_a?(Array) ? payload["errors"].map(&:to_s) : ["test-task-binding checker returned invalid JSON"]
+  passed = status.success? && payload.is_a?(Hash) && payload["ok"] == true
+  { "id" => id, "origin" => "core_fixed_checker", "exit_code" => passed ? 0 : 1, "passed" => passed,
+    "issues" => passed ? [] : (issues.empty? ? [stderr.strip.empty? ? "#{id} failed" : stderr.strip] : issues),
+    "counters" => { "issue_count" => passed ? 0 : issues.length } }
+rescue JSON::ParserError => error
+  { "id" => id, "origin" => "core_fixed_checker", "exit_code" => 1, "passed" => false,
+    "issues" => ["#{id} returned invalid JSON: #{error.message}"], "counters" => { "issue_count" => 1 } }
+end
+
 root = Dir.pwd
 lock = DevflowControlIO.acquire_project_lock(root)
 begin
@@ -78,6 +111,9 @@ begin
   gate = workflow.dig("governance", "requirement_graph_gate").to_s
   enforced = gate == "enforced"
   checker_results = selected.map do |id|
+    supplemental = supplemental_checker(root, options[:feature], id, options[:step])
+    next supplemental if supplemental
+
     issues = checkers.fetch(id, ["unknown fixed checker: #{id}"])
     { "id" => id, "origin" => "core_fixed_checker", "exit_code" => issues.empty? ? 0 : 1, "passed" => issues.empty?, "issues" => issues,
       "counters" => { "issue_count" => issues.length } }

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

@@ -13,19 +13,24 @@ require_relative "control_io"
 require_relative "architecture_constraints"
 
 module RequirementGraph
-  # v3 adds the two narrowly-scoped architecture inputs. Existing v1/v2
+  # v4 adds derived TC verification nodes. Existing v1-v3
   # graphs are migrated in memory and re-written only by this Core writer.
-  SCHEMA_VERSION = 3
-  SUPPORTED_SCHEMA_VERSIONS = [1, 2, SCHEMA_VERSION].freeze
+  SCHEMA_VERSION = 4
+  SUPPORTED_SCHEMA_VERSIONS = [1, 2, 3, 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"
+    "api" => "API", "workload_shape" => "WSH", "workload_constraint" => "WLC", "test_case" => "TC"
   }.freeze
-  VIEW_NAMES = %w[evidence definitions behavior-graph requirement-graph slices acceptance traceability].freeze
+  VIEW_NAMES = %w[evidence definitions behavior-graph requirement-graph slices acceptance tests traceability].freeze
   FEATURE_INVALID = /[\\\/\x00-\x1F\x7F]/
+  # Delta data never writes a node's top-level id/status/revision: Core builds
+  # that wrapper itself. Reserving these words recursively made ordinary API
+  # bodies such as {"id": ...} or {"status": ...} impossible to describe;
+  # reject only root data keys, while nested contract/request payloads remain
+  # factual business data.
   RESERVED_KEYS = %w[id status revision passed confirmed graph_revision stale_fingerprint severity risk_level priority p0 high_risk].freeze
 
   module_function
@@ -85,12 +90,7 @@ module RequirementGraph
   end
 
   def contains_reserved_key?(value)
-    case value
-    when Hash
-      value.any? { |key, child| RESERVED_KEYS.include?(key.to_s) || contains_reserved_key?(child) }
-    when Array then value.any? { |child| contains_reserved_key?(child) }
-    else false
-    end
+    value.is_a?(Hash) && value.keys.any? { |key| RESERVED_KEYS.include?(key.to_s) }
   end
 
   def normalize_data(value)
@@ -111,6 +111,24 @@ module RequirementGraph
     graph["nodes"].map { |node| node["id"] if node.is_a?(Hash) && node["id"].is_a?(String) }.compact.to_set
   end
 
+  # The API test compiler deliberately fingerprints only the API contracts.
+  # Importing its derived TC nodes advances the graph revision, but must not
+  # make the compiler believe the source contract itself changed.
+  def api_contract_fingerprint(graph)
+    source = Array(graph["nodes"]).select { |node| node.is_a?(Hash) && node["kind"] == "api" }.map do |node|
+      { "id" => node["id"], "data" => node["data"] }
+    end
+    Digest::SHA256.hexdigest(JSON.generate(deep_sort(source)))
+  end
+
+  def deep_sort(value)
+    case value
+    when Hash then value.keys.sort.to_h { |key| [key, deep_sort(value[key])] }
+    when Array then value.map { |item| deep_sort(item) }
+    else value
+    end
+  end
+
   def set_node_fingerprint!(node)
     node["fingerprint"] = fingerprint(node.reject { |key, _| key == "fingerprint" })
   end
@@ -158,7 +176,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)
+      candidate_errors = workload_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
@@ -175,12 +193,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].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"
+      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"
       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)
+      candidate_errors = workload_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)
@@ -199,6 +217,7 @@ module RequirementGraph
     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"
+    raise ArgumentError, "test cases must be frozen through acceptance_test_suite.rb" if node["kind"] == "test_case"
     unless evidence.is_a?(Hash) && (evidence["cp_record"] || evidence["evidence_ref"])
       raise ArgumentError, "confirm requires cp_record or evidence_ref"
     end
@@ -252,6 +271,215 @@ module RequirementGraph
     end
   end
 
+  TEST_CASE_TYPES = %w[api page permission boundary resilience migration performance].freeze
+  TEST_AUTOMATION_MODES = %w[automated manual blocked].freeze
+
+  # TC nodes are derived verification intent. They deliberately store only
+  # externally observable setup, operation and oracle; implementation paths,
+  # selectors and agent summaries belong to later execution bindings.
+  def test_case_errors(graph, node, require_edges: false, require_confirmed_inputs: false)
+    return [] unless node["kind"] == "test_case"
+
+    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|
+      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?
+    errors << "#{node["id"]}: requirement_refs must be a non-empty array" unless data["requirement_refs"].is_a?(Array) && !data["requirement_refs"].empty?
+    errors << "#{node["id"]}: preconditions must be a non-empty array" unless data["preconditions"].is_a?(Array) && !data["preconditions"].empty?
+    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"])
+    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
+    if data.key?("generated_case_key")
+      errors << "#{node["id"]}: generated_case_key is invalid" unless data["generated_case_key"].is_a?(String) && data["generated_case_key"].match?(/\AATC-[A-Z0-9-]+\z/)
+      errors << "#{node["id"]}: generated API TC requires test_obligation_refs" unless data["test_obligation_refs"].is_a?(Array) && !data["test_obligation_refs"].empty?
+      errors << "#{node["id"]}: generated API TC requires a non-empty api_refs" unless data["api_refs"].is_a?(Array) && !data["api_refs"].empty?
+      execution = data["execution"]
+      unless execution.is_a?(Hash) && execution["protocol"] == "http" && execution["request"].is_a?(Hash) && execution["expect"].is_a?(Hash) && execution.dig("request", "method").is_a?(String) && execution.dig("request", "path").is_a?(String) && execution.dig("expect", "http_status").is_a?(Integer)
+        errors << "#{node["id"]}: generated API TC requires an HTTP execution definition"
+      end
+    end
+    if data["automation_mode"] == "manual"
+      %w[manual_reason owner].each { |field| errors << "#{node["id"]}: manual tests require #{field}" unless present?(data[field]) }
+    elsif data["automation_mode"] == "blocked"
+      %w[blocked_by owner].each { |field| errors << "#{node["id"]}: blocked tests require #{field}" unless present?(data[field]) }
+    end
+
+    Array(data["acceptance_refs"]).each do |ref|
+      errors << "#{node["id"]}: acceptance_ref #{ref} must reference AC" unless refs_known?(graph, [ref], %w[AC])
+      errors << "#{node["id"]}: acceptance_ref #{ref} must link with verified_by" if require_edges && !incoming_edge?(graph, ref, node["id"], "verified_by")
+      errors << "#{node["id"]}: acceptance_ref #{ref} must be confirmed" if require_confirmed_inputs && !confirmed?(graph, ref)
+    end
+    Array(data["requirement_refs"]).each do |ref|
+      errors << "#{node["id"]}: requirement_ref #{ref} must reference REQ/BR/BC" unless refs_known?(graph, [ref], %w[REQ BR BC])
+      errors << "#{node["id"]}: requirement_ref #{ref} must link with verified_by" if require_edges && !incoming_edge?(graph, ref, node["id"], "verified_by")
+      errors << "#{node["id"]}: requirement_ref #{ref} must be confirmed" if require_confirmed_inputs && !confirmed?(graph, ref)
+    end
+    {
+      "api_refs" => %w[API],
+      "workload_refs" => %w[WSH WLC],
+      "risk_refs" => %w[RISK]
+    }.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|
+        label = field.sub(/s\z/, "")
+        errors << "#{node["id"]}: #{label} #{ref} references an invalid graph node" unless refs_known?(graph, [ref], prefixes)
+        errors << "#{node["id"]}: #{label} #{ref} must link with verified_by" if require_edges && !incoming_edge?(graph, ref, node["id"], "verified_by")
+        errors << "#{node["id"]}: #{label} #{ref} must be confirmed" if require_confirmed_inputs && !confirmed?(graph, ref)
+      end
+    end
+    errors.uniq
+  end
+
+  def frozen_test_case?(graph, node)
+    node["kind"] == "test_case" && node["status"] == "confirmed" && !Array(graph["stale"]).any? { |entry| entry.is_a?(Hash) && entry["node_id"] == node["id"] }
+  end
+
+  # CP-3 is the single freeze point. Keep it here instead of in a Skill so the
+  # graph revision, TC statuses, views and audit entry commit atomically under
+  # the caller's control-plane lock.
+  def freeze_test_cases!(root, graph, cp_record)
+    cases = Array(graph["nodes"]).select { |node| node.is_a?(Hash) && node["kind"] == "test_case" }
+    return { "ok" => false, "reason" => "test_suite_empty", "message" => "cannot freeze an empty TC suite" } if cases.empty?
+    return { "ok" => false, "reason" => "test_suite_already_frozen", "message" => "confirmed test cases require a new candidate suite" } if cases.any? { |node| node["status"] == "confirmed" }
+    return { "ok" => false, "reason" => "test_suite_graph_stale", "message" => "cannot freeze TC suite while the requirement graph has stale downstream nodes" } if Array(graph["stale"]).any?
+
+    checkers = checker_results(graph)
+    errors = checkers.fetch("test-coverage-check", []).dup
+    errors.concat(checkers.fetch("test-obligation-check", []))
+    cases.each { |node| errors.concat(test_case_errors(graph, node, require_edges: true, require_confirmed_inputs: true)) }
+    return { "ok" => false, "reason" => "test_suite_incomplete", "message" => errors.uniq.join("; "), "errors" => errors.uniq } if errors.any?
+
+    cases.each do |node|
+      node["status"] = "confirmed"
+      node["confirmation"] = { "origin" => "core_acceptance_test_suite", "cp_record" => cp_record }
+      set_node_fingerprint!(node)
+      clear_stale_for!(graph, node["id"])
+    end
+    graph["revision"] += 1
+    write_views!(root, graph, stale: false)
+    path, = graph_path(root, graph["feature"])
+    append_audit!(root, graph, { "event" => "test_suite_freeze", "node_ids" => cases.map { |node| node["id"] }, "cp_record" => cp_record })
+    DevflowControlIO.atomic_write(path, JSON.pretty_generate(graph) + "\n")
+    { "ok" => true, "path" => path.sub("#{File.realpath(root)}/", ""), "graph_revision" => graph["revision"],
+      "frozen_case_ids" => cases.map { |node| node["id"] }, "tests_view" => graph.dig("views", "tests") }
+  end
+
+  # The matrix compiler is Core-owned and deterministic; this importer is the
+  # only path which may turn its complete generated case list into graph TC
+  # candidates.  Keeping the batch write here prevents a Skill from omitting
+  # the 37th boundary case while still preserving the normal graph audit and
+  # ID allocation rules.
+  def import_api_test_matrix!(root, graph)
+    matrix_path = File.join(feature_dir(root, graph["feature"]), "api-test-matrix.json")
+    raise ArgumentError, "API test matrix is missing; compile it before import" unless File.file?(matrix_path)
+    matrix = JSON.parse(File.read(matrix_path))
+    raise ArgumentError, "API test matrix identity is invalid" unless matrix["schema_version"] == 1 && matrix["origin"] == "core_api_test_matrix" && matrix["feature"] == graph["feature"]
+    expected_source = { "api_contract_fingerprint" => api_contract_fingerprint(graph), "api_ids" => Array(graph["nodes"]).select { |node| node.is_a?(Hash) && node["kind"] == "api" }.map { |node| node["id"] } }
+    unless matrix["source"] == expected_source
+      raise ArgumentError, "API test matrix is stale for the current API contract (expected #{expected_source["api_contract_fingerprint"]}, got #{matrix.dig("source", "api_contract_fingerprint")})"
+    end
+    raise ArgumentError, "API test matrix contains unresolved contract gaps" unless Array(matrix["errors"]).empty?
+
+    generated_cases = matrix["cases"]
+    raise ArgumentError, "API test matrix cases must be an array" unless generated_cases.is_a?(Array)
+    existing = Array(graph["nodes"]).select { |node| node.is_a?(Hash) && node["kind"] == "test_case" && node.dig("data", "generated_case_key").is_a?(String) }.to_h { |node| [node.dig("data", "generated_case_key"), node] }
+    keys = generated_cases.map { |item| item.is_a?(Hash) ? item["key"] : nil }
+    raise ArgumentError, "API test matrix case keys must be unique non-empty strings" unless keys.all? { |key| key.is_a?(String) && key.match?(/\AATC-[A-Z0-9-]+\z/) } && keys.uniq.length == keys.length
+
+    imported = []
+    generated_cases.each do |item|
+      candidate_data = item["test_case"]
+      raise ArgumentError, "#{item["key"]}: test_case must be an object" unless candidate_data.is_a?(Hash)
+      raise ArgumentError, "#{item["key"]}: test_case generated_case_key mismatch" unless candidate_data["generated_case_key"] == item["key"]
+      raise ArgumentError, "#{item["key"]}: test_case obligation refs mismatch" unless candidate_data["test_obligation_refs"] == item["obligation_refs"]
+      node = existing[item["key"]]
+      if node
+        comparable = node.dig("data", "execution") == candidate_data["execution"] && node.dig("data", "test_obligation_refs") == candidate_data["test_obligation_refs"]
+        raise ArgumentError, "#{item["key"]}: existing generated TC does not match matrix" unless comparable
+      else
+        applied = proposal(graph, { "op" => "add", "kind" => "test_case", "data" => candidate_data }, ["test_case"])
+        node = applied.fetch("node")
+        refs = Array(candidate_data["acceptance_refs"]) + Array(candidate_data["requirement_refs"]) + Array(candidate_data["api_refs"])
+        refs.each do |ref|
+          edge = { "from" => ref, "to" => node["id"], "relation" => "verified_by" }
+          graph["edges"] << edge unless graph["edges"].include?(edge)
+        end
+        errors = test_case_errors(graph, node, require_edges: true, require_confirmed_inputs: true)
+        raise ArgumentError, errors.join("; ") if errors.any?
+        existing[item["key"]] = node
+        imported << node["id"]
+      end
+      item["tc_id"] = node["id"]
+    end
+
+    if imported.any?
+      graph["revision"] += 1
+      stale = Array(graph["stale"]).any?
+      write_views!(root, graph, stale: stale)
+      append_audit!(root, graph, { "event" => "api_test_matrix_import", "node_ids" => imported, "case_set_fingerprint" => matrix["case_set_fingerprint"] })
+      path, = graph_path(root, graph["feature"])
+      DevflowControlIO.atomic_write(path, JSON.pretty_generate(graph) + "\n")
+    end
+    matrix["imported_graph_revision"] = graph["revision"]
+    DevflowControlIO.atomic_write(matrix_path, JSON.pretty_generate(matrix) + "\n")
+    template_path = File.join(root, ".planning", "features", graph["feature"], "api-acceptance-bindings.template.json")
+    template = {
+      "schema_version" => 1, "origin" => "core_api_test_matrix_template", "feature" => graph["feature"],
+      "case_set_fingerprint" => matrix["case_set_fingerprint"],
+      "cases" => generated_cases.map do |item|
+        { "tc_id" => item["tc_id"], "mode" => "automated", "adapter" => { "kind" => "http", "base_url_env" => "DEVFLOW_TEST_BASE_URL", "headers_env" => { "Authorization" => "DEVFLOW_TEST_AUTHORIZATION" } } }
+      end
+    }
+    DevflowControlIO.atomic_write(template_path, JSON.pretty_generate(template) + "\n")
+    { "ok" => true, "imported_case_ids" => imported, "test_case_ids" => generated_cases.map { |item| item["tc_id"] }, "graph_revision" => graph["revision"], "case_set_fingerprint" => matrix["case_set_fingerprint"] }
+  end
+
+  # CP-API, not the API-contract Skill, turns a complete candidate contract
+  # into confirmed graph fact.  Downstream TC imports therefore never need to
+  # trust an agent-written `cp_record` as proof that the shared contract was
+  # reviewed by the user.
+  def confirm_api_contracts!(root, graph, cp_record)
+    apis = Array(graph["nodes"]).select { |node| node.is_a?(Hash) && node["kind"] == "api" }
+    return { "ok" => true, "confirmed_api_ids" => [], "graph_revision" => graph["revision"], "skipped" => "no_api_nodes" } if apis.empty?
+
+    errors = checker_results(graph).fetch("contract-coverage-check", []).dup
+    apis.each do |node|
+      Array(node.dig("data", "requirement_refs")).each do |ref|
+        errors << "#{node["id"]}: requirement_ref #{ref} must be confirmed before CP-API" unless confirmed?(graph, ref)
+      end
+      behavior_ref = node.dig("data", "behavior_ref")
+      errors << "#{node["id"]}: behavior_ref #{behavior_ref} must be confirmed before CP-API" unless confirmed?(graph, behavior_ref)
+    end
+    return { "ok" => false, "reason" => "api_contract_incomplete", "errors" => errors.uniq } if errors.any?
+
+    confirmed = []
+    apis.each do |node|
+      next if node["status"] == "confirmed"
+
+      node["status"] = "confirmed"
+      node["confirmation"] = { "origin" => "core_api_contract_checkpoint", "cp_record" => cp_record }
+      set_node_fingerprint!(node)
+      clear_stale_for!(graph, node["id"])
+      confirmed << node["id"]
+    end
+    if confirmed.any?
+      graph["revision"] += 1
+      stale = Array(graph["stale"]).any?
+      write_views!(root, graph, stale: stale)
+      path, = graph_path(root, graph["feature"])
+      append_audit!(root, graph, { "event" => "api_contract_confirm", "node_ids" => confirmed, "cp_record" => cp_record })
+      DevflowControlIO.atomic_write(path, JSON.pretty_generate(graph) + "\n")
+    end
+    { "ok" => true, "confirmed_api_ids" => confirmed, "graph_revision" => graph["revision"] }
+  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.
@@ -400,7 +628,7 @@ module RequirementGraph
   def checker_results(graph)
     results = {
       "requirement-graph-check" => [], "slice-independence-check" => [], "contract-coverage-check" => [],
-      "change-impact-check" => [], "acceptance-coverage-check" => [], "risk-derivation-check" => []
+      "change-impact-check" => [], "acceptance-coverage-check" => [], "test-coverage-check" => [], "test-obligation-check" => [], "risk-derivation-check" => []
     }
     Array(graph["nodes"]).each do |node|
       next unless node.is_a?(Hash)
@@ -446,6 +674,45 @@ module RequirementGraph
           missing = %w[business contract resilience] - types
           results["acceptance-coverage-check"] << "#{node["id"]}: high-risk acceptance missing #{missing.join(", ")}" if missing.any?
         end
+      when "test_case"
+        results["test-coverage-check"].concat(
+          test_case_errors(graph, node, require_edges: true, require_confirmed_inputs: node["status"] == "confirmed")
+        )
+      end
+    end
+    Array(graph["nodes"]).select { |node| node.is_a?(Hash) && node["kind"] == "acceptance" }.each do |acceptance|
+      covered = Array(graph["nodes"]).any? do |candidate|
+        candidate.is_a?(Hash) && candidate["kind"] == "test_case" && Array(candidate.dig("data", "acceptance_refs")).include?(acceptance["id"])
+      end
+      results["test-coverage-check"] << "#{acceptance["id"]}: missing TC coverage" unless covered
+    end
+    test_cases = Array(graph["nodes"]).select { |node| node.is_a?(Hash) && node["kind"] == "test_case" }
+    covered_by = lambda do |test_type, field, ref|
+      test_cases.any? do |test_case|
+        test_case.dig("data", "test_type") == test_type && Array(test_case.dig("data", field)).include?(ref)
+      end
+    end
+    Array(graph["nodes"]).each do |node|
+      next unless node.is_a?(Hash)
+
+      case node["kind"]
+      when "api"
+        results["test-obligation-check"] << "#{node["id"]}: API change requires an api TC with api_refs" unless covered_by.call("api", "api_refs", node["id"])
+      when "boundary"
+        results["test-obligation-check"] << "#{node["id"]}: boundary requires a boundary TC with requirement_refs" unless covered_by.call("boundary", "requirement_refs", node["id"])
+      when "workload_shape", "workload_constraint"
+        results["test-obligation-check"] << "#{node["id"]}: workload constraint requires a performance TC with workload_refs" unless covered_by.call("performance", "workload_refs", node["id"])
+        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
+      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"])
+        end
+      when "requirement"
+        if high_risk_by_structure?(node)
+          results["test-obligation-check"] << "#{node["id"]}: cross-domain requirement requires a permission TC with requirement_refs" unless covered_by.call("permission", "requirement_refs", node["id"])
+        end
       end
     end
     stale = Array(graph["stale"])
@@ -477,7 +744,10 @@ module RequirementGraph
     Array(graph["edges"]).each do |edge|
       errors << "invalid edge" unless edge.is_a?(Hash) && known.include?(edge["from"]) && known.include?(edge["to"]) && edge["relation"].is_a?(String)
     end
-    checker_results(graph).each_value { |issues| errors.concat(issues) }
+    # Test coverage becomes enforced only at acceptance-test-design and later
+    # workflow steps. Baseline construction itself must remain valid before
+    # any derived TC candidates exist.
+    checker_results(graph).reject { |id, _| %w[test-coverage-check test-obligation-check].include?(id) }.each_value { |issues| errors.concat(issues) }
     Array(graph["nodes"]).each do |node|
       next unless node.is_a?(Hash) && high_risk_by_structure?(node)
       errors << "#{node["id"]}: derived high-risk node must be confirmed and provable" unless node["status"] == "confirmed"
@@ -490,14 +760,21 @@ 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]
+            when "requirement-graph", "traceability" then %w[requirement rule boundary api workload_shape workload_constraint test_case]
             when "slices" then %w[slice]
             when "acceptance" then %w[acceptance risk decision]
+            when "tests" then %w[test_case]
             else []
             end
     nodes = Array(graph["nodes"]).select { |node| kinds.include?(node["kind"]) }
-    { "schema_version" => SCHEMA_VERSION, "origin" => "core_requirement_graph", "feature" => graph["feature"], "graph_revision" => graph["revision"],
-      "view" => name, "nodes" => nodes, "edges" => Array(graph["edges"]).select { |edge| nodes.any? { |node| node["id"] == edge["from"] || node["id"] == edge["to"] } } }
+    payload = { "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"] } } }
+    if name == "tests"
+      test_cases = nodes.select { |node| node["kind"] == "test_case" }
+      payload["frozen"] = !test_cases.empty? && test_cases.all? { |node| frozen_test_case?(graph, node) }
+      payload["frozen_graph_revision"] = graph["revision"] if payload["frozen"]
+    end
+    payload
   end
 
   def write_views!(root, graph, stale: false)
@@ -559,7 +836,7 @@ if __FILE__ == $PROGRAM_NAME
   options = { feature: nil, expected_revision: nil, delta_json: nil, slice_id: nil, node_id: nil, evidence_json: nil, allowed_kinds: nil, confirmed_interactively: false, write: false, read: false, json: false }
   command = ARGV.shift
   OptionParser.new do |opts|
-    opts.banner = "Usage: requirement_graph.rb propose|inspect|validate|context --feature NAME [options]"
+  opts.banner = "Usage: requirement_graph.rb propose|import-test-cases|inspect|validate|context --feature NAME [options]"
     opts.on("--feature NAME") { |value| options[:feature] = value }
     opts.on("--expected-revision N", Integer) { |value| options[:expected_revision] = value }
     opts.on("--delta-json JSON") { |value| options[:delta_json] = value }
@@ -573,7 +850,7 @@ if __FILE__ == $PROGRAM_NAME
     opts.on("--json") { options[:json] = true }
   end.parse!
   root = Dir.pwd
-  lock = %w[propose context confirm].include?(command) && options[:write] ? DevflowControlIO.acquire_project_lock(root) : nil
+  lock = %w[propose import-test-cases context confirm].include?(command) && options[:write] ? DevflowControlIO.acquire_project_lock(root) : nil
   begin
     graph, path, relative = RequirementGraph.load_graph(root, options[:feature])
     result = case command
@@ -617,6 +894,15 @@ if __FILE__ == $PROGRAM_NAME
                  DevflowControlIO.atomic_write(path, JSON.pretty_generate(graph) + "\n")
                  { "ok" => true, "path" => relative, "revision" => graph["revision"], "applied" => applied, "validation_errors" => RequirementGraph.validate(graph), "checkers" => RequirementGraph.checker_results(graph), "views" => graph["views"] }
                end
+             when "import-test-cases"
+               raise ArgumentError, "--write is required" unless options[:write]
+               raise ArgumentError, "--expected-revision is required" if options[:expected_revision].nil?
+               if graph["revision"] != options[:expected_revision]
+                 { "ok" => false, "reason" => "stale_graph_revision", "expected_revision" => options[:expected_revision], "actual_revision" => graph["revision"] }
+               else
+                 imported = RequirementGraph.import_api_test_matrix!(root, graph)
+                 { "ok" => true, "path" => relative, "revision" => graph["revision"], "imported" => imported, "validation_errors" => RequirementGraph.validate(graph), "checkers" => RequirementGraph.checker_results(graph), "views" => graph["views"] }
+               end
              when "confirm"
                raise ArgumentError, "--write is required" unless options[:write]
                raise ArgumentError, "--node-id is required" unless options[:node_id]
@@ -635,7 +921,7 @@ if __FILE__ == $PROGRAM_NAME
                  { "ok" => true, "path" => relative, "revision" => graph["revision"], "applied" => applied, "validation_errors" => RequirementGraph.validate(graph), "checkers" => RequirementGraph.checker_results(graph), "views" => graph["views"] }
                end
              else
-               { "ok" => false, "reason" => "invalid_command", "message" => "command must be propose, inspect, validate, context, or confirm" }
+               { "ok" => false, "reason" => "invalid_command", "message" => "command must be propose, import-test-cases, inspect, validate, context, or confirm" }
              end
   rescue ArgumentError, JSON::ParserError => error
     result = { "ok" => false, "reason" => "invalid_requirement_graph_input", "message" => error.message }