@guanlin4924/devflow-pi 0.1.19 → 0.1.20

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

@@ -0,0 +1,86 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Core-owned freeze point for a feature's derived TC suite. A skill may propose
+# individual candidates, but it cannot turn them into evidence by confirming
+# them one by one: this command snapshots the complete, fresh suite under CP-3.
+require "json"
+require "open3"
+require "optparse"
+require_relative "control_io"
+require_relative "requirement_graph"
+
+options = { feature: nil, expected_graph_revision: nil, cp_record: nil, write: false, json: false }
+command = ARGV.shift
+OptionParser.new do |parser|
+  parser.on("--feature NAME") { |value| options[:feature] = value }
+  parser.on("--expected-graph-revision REVISION", Integer) { |value| options[:expected_graph_revision] = value }
+  parser.on("--cp-record RECORD") { |value| options[:cp_record] = value }
+  parser.on("--write") { options[:write] = true }
+  parser.on("--json") { options[:json] = true }
+end.parse!
+
+def test_nodes(graph)
+  Array(graph["nodes"]).select { |node| node.is_a?(Hash) && node["kind"] == "test_case" }
+end
+
+def api_test_matrix_check(root, feature, graph)
+  return { "ok" => true, "skipped" => "no_api_nodes" } unless Array(graph["nodes"]).any? { |node| node.is_a?(Hash) && node["kind"] == "api" }
+
+  script = File.join(__dir__, "api_test_matrix.py")
+  stdout, stderr, status = Open3.capture3("python3", script, "validate", "--feature", feature, "--json", chdir: root)
+  payload = JSON.parse(stdout)
+  return payload if status.success? && payload.is_a?(Hash)
+
+  { "ok" => false, "errors" => [stderr.strip.empty? ? "API test matrix checker returned invalid output" : stderr.strip] }
+rescue JSON::ParserError
+  { "ok" => false, "errors" => ["API test matrix checker returned invalid JSON"] }
+end
+
+root = Dir.pwd
+lock = nil
+begin
+  raise ArgumentError, "command must be inspect or freeze" unless %w[inspect freeze].include?(command)
+  raise ArgumentError, "--feature is required" unless RequirementGraph.valid_feature?(options[:feature])
+  lock = DevflowControlIO.acquire_project_lock(root) if command == "freeze"
+  graph, path, relative = RequirementGraph.load_graph(root, options[:feature])
+  cases = test_nodes(graph)
+
+  if command == "inspect"
+    view = RequirementGraph.view_payload(graph, "tests")
+    result = {
+      "ok" => true,
+      "path" => relative,
+      "graph_revision" => graph["revision"],
+      "test_case_ids" => cases.map { |node| node["id"] },
+      "frozen" => view["frozen"],
+      "frozen_graph_revision" => view["frozen_graph_revision"],
+      "stale" => Array(graph["stale"]).select { |entry| cases.any? { |node| node["id"] == entry["node_id"] } }
+    }
+  else
+    raise ArgumentError, "--write is required" unless options[:write]
+    raise ArgumentError, "--expected-graph-revision is required" if options[:expected_graph_revision].nil?
+    raise ArgumentError, "--cp-record is required" if options[:cp_record].to_s.strip.empty?
+    if graph["revision"] != options[:expected_graph_revision]
+      result = { "ok" => false, "reason" => "stale_graph_revision", "expected_revision" => options[:expected_graph_revision], "actual_revision" => graph["revision"] }
+    elsif cases.empty?
+      result = { "ok" => false, "reason" => "test_suite_empty", "message" => "cannot freeze an empty TC suite" }
+    elsif cases.any? { |node| node["status"] == "confirmed" }
+      result = { "ok" => false, "reason" => "test_suite_already_frozen", "message" => "confirmed test cases require a new candidate suite" }
+    elsif Array(graph["stale"]).any?
+      result = { "ok" => false, "reason" => "test_suite_graph_stale", "message" => "cannot freeze TC suite while the requirement graph has stale downstream nodes" }
+    else
+      matrix = api_test_matrix_check(root, options[:feature], graph)
+      result = if matrix["ok"]
+                 RequirementGraph.freeze_test_cases!(root, graph, options[:cp_record])
+               else
+                 { "ok" => false, "reason" => "api_test_matrix_incomplete", "message" => Array(matrix["errors"]).join("; "), "matrix" => matrix }
+               end
+    end
+  end
+rescue ArgumentError, JSON::ParserError => error
+  result = { "ok" => false, "reason" => "acceptance_test_suite_invalid", "message" => error.message }
+ensure
+  DevflowControlIO.release_lock(lock)
+end
+puts JSON.pretty_generate(result)

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

@@ -2,13 +2,16 @@
 # frozen_string_literal: true
 
 require "date"
+require "digest"
 require "fileutils"
 require "json"
+require "open3"
 require "optparse"
 require "yaml"
 require_relative "control_io"
 require_relative "validate_state"
 require_relative "phase_ownership"
+require_relative "requirement_graph"
 
 options = {
   state: nil,
@@ -321,7 +324,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|
@@ -342,6 +349,97 @@ def fail_result(reason, details = {})
   { "ok" => false, "reason" => reason, "details" => details }
 end
 
+# CP-3 has to validate a *candidate* task/TC binding before it freezes the
+# derived TC suite.  The normal checker then validates the Core attestation
+# against the frozen suite before execution.  Keeping both calls here, under
+# the state lock, prevents the old circular gate ("must be frozen before the
+# checkpoint that freezes it") without adding another user confirmation.
+def test_task_binding_check(root, feature, stage)
+  script = File.join(__dir__, "test_task_binding_check.py")
+  stdout, stderr, status = Open3.capture3("python3", script, "--feature", feature, "--stage", stage, "--json", chdir: root)
+  payload = JSON.parse(stdout)
+  passed = status.success? && payload.is_a?(Hash) && payload["ok"] == true
+  return payload.merge("ok" => true) if passed
+
+  { "ok" => false, "reason" => "test_task_binding_#{stage}_check_failed",
+    "errors" => payload.is_a?(Hash) && payload["errors"].is_a?(Array) ? payload["errors"] : [stderr.strip.empty? ? "checker returned invalid JSON" : stderr.strip] }
+rescue JSON::ParserError => error
+  { "ok" => false, "reason" => "test_task_binding_#{stage}_check_failed", "errors" => ["checker returned invalid JSON: #{error.message}"] }
+end
+
+def api_test_matrix_check(root, feature, graph)
+  return { "ok" => true, "skipped" => "no_api_nodes" } unless Array(graph["nodes"]).any? { |node| node.is_a?(Hash) && node["kind"] == "api" }
+
+  script = File.join(__dir__, "api_test_matrix.py")
+  stdout, stderr, status = Open3.capture3("python3", script, "validate", "--feature", feature, "--json", chdir: root)
+  payload = JSON.parse(stdout)
+  return payload if status.success? && payload.is_a?(Hash)
+
+  { "ok" => false, "errors" => [stderr.strip.empty? ? "API test matrix checker returned invalid output" : stderr.strip] }
+rescue JSON::ParserError => error
+  { "ok" => false, "errors" => ["API test matrix checker returned invalid JSON: #{error.message}"] }
+end
+
+def api_test_schema_check(root, feature, graph)
+  return { "ok" => true, "skipped" => "no_api_nodes" } unless Array(graph["nodes"]).any? { |node| node.is_a?(Hash) && node["kind"] == "api" }
+
+  script = File.join(__dir__, "api_test_matrix.py")
+  stdout, stderr, status = Open3.capture3("python3", script, "check", "--feature", feature, "--json", chdir: root)
+  payload = JSON.parse(stdout)
+  return payload if status.success? && payload.is_a?(Hash)
+
+  { "ok" => false, "errors" => [stderr.strip.empty? ? "API test schema checker returned invalid output" : stderr.strip] }
+rescue JSON::ParserError => error
+  { "ok" => false, "errors" => ["API test schema checker returned invalid JSON: #{error.message}"] }
+end
+
+def test_suite_freeze_attestation_path(root, feature)
+  DevflowControlIO.resolve_control_path(root, ".planning/features/#{feature}/test-suite-freeze.json", :artifact)
+end
+
+def frozen_test_suite_pin(freeze_result)
+  view = freeze_result["tests_view"]
+  return nil unless view.is_a?(Hash)
+
+  { "graph_revision" => view["graph_revision"], "fingerprint" => view["fingerprint"] }
+end
+
+def write_test_suite_freeze_attestation(root, feature, state_revision, candidate_check, freeze_result)
+  candidate_suite = candidate_check["candidate_test_suite"]
+  frozen_suite = frozen_test_suite_pin(freeze_result)
+  raise DevflowControlIO::InvalidControlPath, "candidate test suite pin missing from CP-3 binding check" unless candidate_suite.is_a?(Hash)
+  raise DevflowControlIO::InvalidControlPath, "frozen test suite pin missing from CP-3 freeze" unless frozen_suite.is_a?(Hash)
+  binding_hash = candidate_check["binding_sha256"]
+  raise DevflowControlIO::InvalidControlPath, "test binding hash missing from CP-3 binding check" unless binding_hash.is_a?(String) && !binding_hash.empty?
+
+  path, relative = test_suite_freeze_attestation_path(root, feature)
+  payload = {
+    "schema_version" => 1,
+    "origin" => "core_acceptance_test_suite_freeze",
+    "feature" => feature,
+    "checkpoint" => "CP-3",
+    "state_revision" => state_revision,
+    "candidate_test_suite" => candidate_suite,
+    "frozen_test_suite" => frozen_suite,
+    "test_binding_sha256" => binding_hash,
+    "frozen_case_ids" => Array(freeze_result["frozen_case_ids"]).sort
+  }
+  DevflowControlIO.atomic_create(path, JSON.pretty_generate(payload) + "\n")
+  DevflowControlIO.register_control_artifact(root, {
+    "path" => relative, "type" => "test-suite-freeze-attestation", "feature" => feature,
+    "origin" => "core_acceptance_test_suite_freeze", "sha256" => Digest::SHA256.file(path).hexdigest
+  })
+  payload
+end
+
+def cp3_freeze_provenance?(graph, state_revision)
+  expected = "CP-3: state revision #{state_revision} approved"
+  cases = Array(graph["nodes"]).select { |node| node.is_a?(Hash) && node["kind"] == "test_case" }
+  !cases.empty? && cases.all? do |node|
+    node["status"] == "confirmed" && node.dig("confirmation", "origin") == "core_acceptance_test_suite" && node.dig("confirmation", "cp_record") == expected
+  end
+end
+
 # Return from a completed failure branch using its declared return_to contract.
 # The caller must still explicitly confirm the returned checkpoint before any
 # subsequent source-flow step can proceed.
@@ -481,6 +579,98 @@ result =
         elsif Array(state["pending_steps"]).empty?
           result = fail_result("no_pending_step")
         else
+          # CP-API turns the shared candidate contract into confirmed graph
+          # fact inside the same user checkpoint. Skills cannot self-confirm
+          # API nodes and downstream generated TC imports can require a
+          # reviewed contract revision.
+          if state["checkpoint"] == "CP-API" && steps.any? { |step| step["id"] == "api-contract" }
+            feature = state.fetch("current_feature")
+            graph, = RequirementGraph.load_graph(root, feature)
+            schema_check = api_test_schema_check(root, feature, graph)
+            if !schema_check["ok"]
+              result = fail_result("api_test_schema_incomplete", "api_test_schema" => schema_check)
+            else
+              api_confirmation = RequirementGraph.confirm_api_contracts!(root, graph, "CP-API: state revision #{current_revision} approved")
+              if api_confirmation["ok"]
+                actions << "api_contract_confirmed" unless Array(api_confirmation["confirmed_api_ids"]).empty?
+              else
+                result = fail_result("api_contract_confirmation_failed", "api_contract" => api_confirmation)
+              end
+            end
+          end
+
+          # CP-3 authorizes exactly one immutable TC freeze. It is deliberately
+          # inside the checkpoint transition so the user does not have to
+          # approve an extra model-issued dialog and a Skill cannot freeze its
+          # own candidates early.
+          if result.nil? && state["checkpoint"] == "CP-3" && steps.any? { |step| step["id"] == "acceptance-test-design" }
+            feature = state.fetch("current_feature")
+            graph, = RequirementGraph.load_graph(root, feature)
+            attestation_path, = test_suite_freeze_attestation_path(root, feature)
+
+            if File.exist?(attestation_path)
+              frozen_check = test_task_binding_check(root, feature, "frozen")
+              unless frozen_check["ok"]
+                result = fail_result("acceptance_test_suite_freeze_attestation_invalid", "test_suite" => frozen_check)
+              else
+                actions << "acceptance_test_suite_freeze_attestation_verified"
+              end
+            elsif cp3_freeze_provenance?(graph, current_revision)
+              # A process can die after graph/view writes but before the
+              # attestation is published. Recover only if each TC proves that
+              # this exact CP-3 already froze it; never use this path to bless
+              # a generic confirmed suite.
+              recovery_check = test_task_binding_check(root, feature, "recovery")
+              unless recovery_check["ok"]
+                result = fail_result("acceptance_test_suite_freeze_recovery_failed", "test_suite" => recovery_check)
+              else
+                recovered = {
+                  "ok" => true,
+                  "tests_view" => graph.dig("views", "tests"),
+                  "frozen_case_ids" => Array(graph["nodes"]).select { |node| node.is_a?(Hash) && node["kind"] == "test_case" }.map { |node| node["id"] }
+                }
+                begin
+                  write_test_suite_freeze_attestation(root, feature, current_revision, recovery_check, recovered)
+                  frozen_check = test_task_binding_check(root, feature, "frozen")
+                  if frozen_check["ok"]
+                    actions << "acceptance_test_suite_freeze_attestation_recovered"
+                  else
+                    result = fail_result("acceptance_test_suite_freeze_attestation_invalid", "test_suite" => frozen_check)
+                  end
+                rescue DevflowControlIO::InvalidControlPath, SystemCallError => error
+                  result = fail_result("acceptance_test_suite_freeze_attestation_failed", "message" => error.message)
+                end
+              end
+            else
+              matrix_check = api_test_matrix_check(root, feature, graph)
+              unless matrix_check["ok"]
+                result = fail_result("api_test_matrix_incomplete", "api_test_matrix" => matrix_check)
+              else
+                candidate_check = test_task_binding_check(root, feature, "candidate")
+                unless candidate_check["ok"]
+                  result = fail_result("acceptance_test_suite_candidate_binding_failed", "test_suite" => candidate_check)
+                else
+                  frozen = RequirementGraph.freeze_test_cases!(root, graph, "CP-3: state revision #{current_revision} approved")
+                  unless frozen["ok"]
+                    result = fail_result("acceptance_test_suite_freeze_failed", "test_suite" => frozen)
+                  else
+                    begin
+                      write_test_suite_freeze_attestation(root, feature, current_revision, candidate_check, frozen)
+                      frozen_check = test_task_binding_check(root, feature, "frozen")
+                      if frozen_check["ok"]
+                        actions << "acceptance_test_suite_frozen"
+                      else
+                        result = fail_result("acceptance_test_suite_freeze_attestation_invalid", "test_suite" => frozen_check)
+                      end
+                    rescue DevflowControlIO::InvalidControlPath, SystemCallError => error
+                      result = fail_result("acceptance_test_suite_freeze_attestation_failed", "message" => error.message)
+                    end
+                  end
+                end
+              end
+            end
+          end
+          if result.nil?
           pending = Array(state["pending_steps"])
           completed = Array(state["completed_steps"])
           next_id = next_pending_step_id(state, pending, step_by_id, completed)
@@ -505,6 +695,7 @@ result =
             action_description = "Checkpoint confirmed. Advanced to next step."
             next_intent_requested = true
           end
+          end
         end
       end