@guanlin4924/devflow-pi 0.1.39 → 0.1.47

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

@@ -26,7 +26,13 @@ options = {
   cancel_reason: nil,
   expected_revision: nil,
   json: false,
-  runtime_confirmed: false
+  runtime_confirmed: false,
+  confirm_test_prerequisites: false,
+  parallel_action: nil,
+  parallel_branch_id: nil,
+  parallel_attempt: nil,
+  parallel_branch_revision: nil,
+  parallel_evidence: {}
 }
 
 OptionParser.new do |opts|
@@ -43,6 +49,13 @@ OptionParser.new do |opts|
   opts.on("--expected-revision REVISION", Integer, "Reject a stale write unless STATE.md has this revision") { |value| options[:expected_revision] = value }
   opts.on("--json", "Print JSON output") { options[:json] = true }
   opts.on("--runtime-confirmed", "Internal runtime authorization for checkpoint confirmation") { options[:runtime_confirmed] = true }
+  opts.on("--confirm-test-prerequisites", "Confirm displayed CP-3 prerequisite candidates in the same atomic freeze") { options[:confirm_test_prerequisites] = true }
+  opts.on("--parallel-action ACTION", %w[start complete fail retry join]) { |value| options[:parallel_action] = value }
+  opts.on("--parallel-branch-id ID", "Branch id for a parallel transition") { |value| options[:parallel_branch_id] = value }
+  opts.on("--parallel-task-id ID", "OMP task id to bind to a branch") { |value| options[:parallel_task_id] = value }
+  opts.on("--parallel-attempt N", Integer) { |value| options[:parallel_attempt] = value }
+  opts.on("--parallel-branch-revision N", Integer) { |value| options[:parallel_branch_revision] = value }
+  opts.on("--parallel-evidence JSON") { |value| options[:parallel_evidence] = JSON.parse(value) }
 end.parse!
 
 root = Dir.pwd
@@ -83,6 +96,8 @@ def transition_gate_contract(workflow, step)
     window["branches"].keys.map { |name| name.to_s.sub(/\Atrack_/, "").upcase }
   end
   allowed_tracks = track_names.empty? ? ["main"] : ["main", *track_names]
+  step_order = step["order"].to_i
+  immediate_prior = Array(workflow["steps"]).select { |candidate| candidate.is_a?(Hash) && candidate["order"].to_i < step_order }.max_by { |candidate| candidate["order"].to_i }
   reentries = (workflow["failure_branches"] || {}).each_with_object([]) do |(source_step, branch), entries|
     next unless branch.is_a?(Hash) && branch["resume_after_success"].is_a?(Hash)
     entries << { "source" => { "flow" => branch["workflow"], "step" => source_step }, "target" => branch["resume_after_success"], "requires_checkpoint_reconfirm" => true }
@@ -93,6 +108,7 @@ def transition_gate_contract(workflow, step)
     "topology" => {
       "allowed_tracks" => allowed_tracks,
       "allowed_predecessors" => Array(step["depends_on"]),
+      "allowed_intervening_predecessors" => immediate_prior ? [immediate_prior["id"]] : [],
       "allowed_reentry" => reentries,
       "checkpoint" => checkpoint && checkpoint.merge("id" => checkpoint_id)
     },
@@ -409,6 +425,104 @@ def track_boundary?(state, pending_ids)
   (pending_ids & track_allowed_steps(track)).empty? && pending_ids.any?
 end
 
+def parallel_window_for(workflow, completed_step_id)
+  Array(workflow["parallel_windows"]).find do |window|
+    window.is_a?(Hash) && window["after_step"].to_s == completed_step_id.to_s
+  end
+end
+
+def parallel_branch_for(root, state, branch_id)
+  record = ParallelRun.load(root, state.fetch("current_feature"))
+  branch = Array(record && record["branches"]).find { |item| item["branch_id"].to_s == branch_id.to_s }
+  [record, branch]
+end
+
+def advance_parallel_branch(root, state, options, lock = nil)
+  branch_id = options[:parallel_branch_id]
+  raise ArgumentError, "parallel branch id is required" if branch_id.to_s.empty?
+  record, branch = parallel_branch_for(root, state, branch_id)
+  raise ArgumentError, "parallel run not found" unless record
+  raise ArgumentError, "parallel branch not found: #{branch_id}" unless branch
+  expected = Integer(record.fetch("run_revision", 0))
+  case options[:parallel_action]
+  when "start"
+    ParallelRun.update_branch(root: root, feature: state.fetch("current_feature"), branch_id: branch_id, expected_revision: expected, status: "running", task_id: options[:parallel_task_id], lock: lock)
+  when "complete"
+    ParallelRun.update_branch(root: root, feature: state.fetch("current_feature"), branch_id: branch_id, expected_revision: expected, status: "succeeded", evidence_path: options[:parallel_evidence]["evidence_path"], output_fingerprint: options[:parallel_evidence]["output_fingerprint"], lock: lock)
+  when "fail"
+    # The error is diagnostic metadata only; it is never used as evidence or
+    # as an authorization for branch completion.
+    ParallelRun.update_branch(root: root, feature: state.fetch("current_feature"), branch_id: branch_id, expected_revision: expected, status: "failed", error: options[:parallel_evidence]["error"], lock: lock)
+  when "retry"
+    ParallelRun.retry_branch(root: root, feature: state.fetch("current_feature"), branch_id: branch_id, expected_revision: expected, lock: lock)
+  else
+    raise ArgumentError, "unsupported parallel branch action"
+  end
+end
+
+def join_parallel_window(root, state, workflow, current_revision)
+  record = ParallelRun.load(root, state.fetch("current_feature"))
+  raise ArgumentError, "parallel run not found" unless record
+  branches = Array(record["branches"])
+  incomplete = branches.reject { |branch| branch["status"].to_s == "succeeded" }
+  raise ArgumentError, "parallel join requires every branch to succeed" unless branches.any? && incomplete.empty?
+
+  branch_steps = branches.map { |branch| branch.fetch("workflow_step").to_s }
+  state["completed_steps"] = (Array(state["completed_steps"]) + branch_steps).uniq
+  state["pending_steps"] = Array(state["pending_steps"]) - branch_steps
+  window = workflow.fetch("parallel_windows").find { |candidate| candidate["id"].to_s == record["workflow_window"].to_s }
+  raise ArgumentError, "parallel workflow window not found" unless window
+  join_step_id = window.fetch("join_step")
+  join_step = Array(workflow["steps"]).find { |step| step["id"].to_s == join_step_id.to_s }
+  join_predecessors = Array(join_step && join_step["depends_on"]).map(&:to_s)
+  # The join step is only becoming current here; it has not completed yet.
+  # Keep last_completed_step on an actual branch predecessor so the next
+  # GateContract evaluation does not reject the join step as its own previous
+  # step. Prefer the final declared dependency for deterministic behavior.
+  last_predecessor = join_predecessors.reverse.find { |step_id| branch_steps.include?(step_id) }
+  state["last_completed_step"] = last_predecessor || branch_steps.last || state["last_completed_step"]
+  state.delete("parallel_run_ref")
+  record["status"] = "completed"
+  record["run_revision"] = Integer(record.fetch("run_revision", 0)) + 1
+  record["updated_at"] = Time.now.utc.iso8601
+  state["current_step"] = join_step_id
+  state["status"] = "in_progress"
+  state["state_updated_at"] = Date.today.to_s
+  state["revision"] = current_revision + 1
+  [state, record, "Parallel window joined; branch steps merged and parallel_run_ref cleared."]
+end
+
+# Releases states written by the pre-fix join implementation. That version set
+# last_completed_step to the join step while leaving the join step pending,
+# making GateContract reject the very next complete-step call. The signature
+# below is deliberately narrow so unrelated historical state is never changed.
+def repair_legacy_parallel_join_predecessor!(state, workflow)
+  return nil if state["parallel_run_ref"]
+
+  current_step = state["current_step"].to_s
+  completed = Array(state["completed_steps"]).map(&:to_s)
+  return nil if current_step.empty? || completed.include?(current_step)
+  return nil unless state["last_completed_step"].to_s == current_step
+
+  window = Array(workflow["parallel_windows"]).find { |candidate| candidate["join_step"].to_s == current_step }
+  return nil unless window
+
+  branch_steps = if window["branches"].is_a?(Hash)
+                   window["branches"].values.flatten.map(&:to_s)
+                 else
+                   Array(window["branch_steps"]).map(&:to_s)
+                 end
+  return nil if branch_steps.empty? || branch_steps.any? { |step_id| !completed.include?(step_id) }
+
+  join_step = Array(workflow["steps"]).find { |step| step["id"].to_s == current_step }
+  predecessor = Array(join_step && join_step["depends_on"]).map(&:to_s).reverse.find { |step_id| completed.include?(step_id) }
+  predecessor ||= branch_steps.reverse.find { |step_id| completed.include?(step_id) }
+  return nil unless predecessor
+
+  state["last_completed_step"] = predecessor
+  predecessor
+end
+
 def fail_result(reason, details = {})
   { "ok" => false, "reason" => reason, "details" => details }
 end
@@ -457,6 +571,66 @@ rescue JSON::ParserError => error
   { "ok" => false, "errors" => ["API test schema checker returned invalid JSON: #{error.message}"] }
 end
 
+def cross_track_checker_enabled?(workflow, step_id)
+  Array(workflow.dig("governance", "step_checkers", step_id)).map(&:to_s).include?("cross-track-consistency-check")
+end
+
+def cross_track_consistency_check(root, feature)
+  script = File.join(__dir__, "cross_track_consistency_check.rb")
+  stdout, stderr, status = Open3.capture3("ruby", script, "--feature", feature, "--json", chdir: root)
+  payload = JSON.parse(stdout)
+  return payload if status.success? && payload.is_a?(Hash)
+
+  { "ok" => false, "errors" => [stderr.strip.empty? ? "cross-track checker returned invalid output" : stderr.strip] }
+rescue JSON::ParserError => error
+  { "ok" => false, "errors" => ["cross-track checker returned invalid JSON: #{error.message}"] }
+end
+
+def business_cross_model_checker_enabled?(workflow, step_id)
+  Array(workflow.dig("governance", "step_checkers", step_id)).map(&:to_s).include?("business-cross-model-check")
+end
+
+def business_cross_model_check(root, feature)
+  script = File.join(__dir__, "business_cross_model_check.py")
+  business = ".planning/business-model/#{feature}/canonical.json"
+  wireframe = ".planning/features/#{feature}/canonical.json"
+  unless File.file?(File.join(root, business))
+    return { "valid" => false, "errors" => [{ "code" => "BUSINESS_CANONICAL_MISSING", "path" => business }] }
+  end
+  command = ["python3", script, "--business-canonical", business]
+  command += ["--wireframe", wireframe] if File.file?(File.join(root, wireframe))
+  claims = ".planning/features/#{feature}/business-claims.yaml"
+  command += ["--claims", claims] if File.file?(File.join(root, claims))
+  traceability = ".planning/requirements/#{feature}/traceability.json"
+  command += ["--traceability", traceability] if File.file?(File.join(root, traceability))
+  stdout, stderr, status = Open3.capture3(*command, "--json", chdir: root)
+  payload = JSON.parse(stdout)
+  return payload if status.success? && payload.is_a?(Hash)
+
+  payload.is_a?(Hash) ? payload : { "valid" => false, "errors" => [{ "code" => "BUSINESS_CROSS_MODEL_CHECK_FAILED", "message" => stderr.strip }] }
+rescue JSON::ParserError => error
+  { "valid" => false, "errors" => [{ "code" => "BUSINESS_CROSS_MODEL_CHECK_INVALID", "message" => error.message }] }
+end
+
+def branch_machine_evidence(root, state, branch)
+  script = File.join(__dir__, "machine_evidence.rb")
+  step = branch.fetch("workflow_step").to_s
+  attempt = Integer(branch.fetch("attempt", 0))
+  revision = Integer(branch.fetch("branch_revision", 0))
+  stdout, stderr, status = Open3.capture3(
+    "ruby", script, "--feature", state.fetch("current_feature"), "--step", step,
+    "--parallel-branch-id", branch.fetch("branch_id").to_s,
+    "--parallel-attempt", attempt.to_s, "--parallel-branch-revision", revision.to_s,
+    "--lock-held", "--write", "--json", chdir: root
+  )
+  payload = JSON.parse(stdout)
+  return payload if status.success? && payload.is_a?(Hash) && payload["ok"] == true
+
+  { "ok" => false, "errors" => [stderr.strip.empty? ? "machine evidence returned invalid output" : stderr.strip] }
+rescue JSON::ParserError => error
+  { "ok" => false, "errors" => ["machine evidence 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
@@ -565,9 +739,17 @@ result =
       next_intent_written = nil
       actions = []
       action_description = nil
+      parallel_run_to_write = nil
+      test_suite_freeze_to_write = nil
       next_intent_requested = false
       current_revision = Integer(state.fetch("revision", 0))
 
+      if (repaired_predecessor = repair_legacy_parallel_join_predecessor!(state, workflow))
+        changed = true
+        actions << "legacy_parallel_join_predecessor_repaired"
+        action_description = "Repaired legacy parallel join predecessor: #{repaired_predecessor}."
+      end
+
       if result.nil? && !options[:expected_revision].nil? && current_revision != options[:expected_revision]
         result = fail_result(
           "stale_revision",
@@ -576,13 +758,40 @@ result =
         )
       end
 
+      # Branch completion evidence is always generated by Core from the
+      # persisted branch record and current artifacts. Ignore any caller-built
+      # binding so an agent cannot self-attest a different attempt/revision.
+      if result.nil? && options[:parallel_action] == "complete" && options[:write]
+        _run, branch = parallel_branch_for(root, state, options[:parallel_branch_id])
+        if branch.nil?
+          result = fail_result("parallel_branch_not_found")
+        else
+          generated = branch_machine_evidence(root, state, branch)
+          if generated["ok"] == true
+            binding = generated.fetch("parallel_binding")
+            options[:parallel_evidence] = {
+              "evidence_path" => generated.fetch("path"),
+              "branch_id" => binding.fetch("branch_id"),
+              "attempt" => binding.fetch("attempt"),
+              "branch_revision" => binding.fetch("branch_revision"),
+              "state_revision" => binding.fetch("state_revision")
+            }
+          else
+            result = fail_result("parallel_machine_evidence_failed", "evidence" => generated)
+          end
+        end
+      end
+
       # GateRuntime is a read-only boundary check.  It runs while the project
       # lock is held and before any candidate state mutation; the existing
       # validator and advance_state CAS remain the final write guard.
       if result.nil? && gate_contract_enabled?(workflow) &&
          !%w[prepared claimed].include?(state.dig("rollover", "status")) &&
-         (options[:complete_step] || options[:confirm_checkpoint] || options[:enter_failure_branch] || options[:exit_failure_branch])
-        target_step_id = if options[:complete_step]
+         (options[:complete_step] || options[:confirm_checkpoint] || options[:enter_failure_branch] || options[:exit_failure_branch] || options[:parallel_action])
+        target_step_id = if options[:parallel_action] && options[:parallel_action] != "join"
+                           _record, branch = parallel_branch_for(root, state, options[:parallel_branch_id])
+                           branch && branch["workflow_step"]
+                         elsif options[:complete_step]
                            options[:complete_step]
                          elsif options[:confirm_checkpoint]
                            state["current_step"]
@@ -595,20 +804,78 @@ result =
         elsif options[:complete_step] && state["current_step"].to_s != target_step_id.to_s
           result = fail_result("gate_current_step_mismatch", "current_step" => state["current_step"], "requested_step" => target_step_id)
         else
-          transition_kind = if options[:confirm_checkpoint]
+          transition_kind = if options[:parallel_action]
+                              { "start" => "parallel_branch_start", "complete" => "parallel_branch_complete", "fail" => "parallel_branch_fail", "retry" => "parallel_branch_retry", "join" => "parallel_join" }.fetch(options[:parallel_action])
+                            elsif options[:confirm_checkpoint]
                               "confirm_checkpoint"
                             elsif options[:enter_failure_branch]
                               "enter_failure_branch"
                             elsif options[:exit_failure_branch]
                               "exit_failure_branch"
                             end
-          gate_result = transition_gate_preflight(workflow, state, target_step, current_revision, options[:runtime_confirmed], transition_kind)
+          gate_result = GateRuntime.evaluate(
+            contract: transition_gate_contract(workflow, target_step),
+            workflow_state: state,
+            current_revision: current_revision,
+            expected_revision: current_revision,
+            track: if options[:parallel_action] && options[:parallel_action] != "join"
+                     _record, branch = parallel_branch_for(root, state, options[:parallel_branch_id])
+                     branch ? branch["track"].to_s.sub(/\Atrack_/, "").upcase : (active_track(state) || "main")
+                   else
+                     active_track(state) || "main"
+                   end,
+            branch_id: options[:parallel_branch_id],
+            attempt: options[:parallel_attempt],
+            branch_revision: options[:parallel_branch_revision],
+            evidence: options[:parallel_evidence],
+            source: "advance_state",
+            root: root,
+            check_outputs: target_step["id"].to_s == state["current_step"].to_s,
+            transition_kind: transition_kind,
+            checkpoint_authorized: options[:runtime_confirmed]
+          )
           if gate_result && gate_result["verdict"] != "allow"
             result = fail_result("gate_boundary_rejected", "gate" => gate_result)
           end
         end
       end
 
+      if result.nil? && options[:parallel_action]
+        if !options[:write]
+          result = fail_result("parallel_transition_requires_write")
+        elsif options[:parallel_action] == "join"
+          begin
+            if cross_track_checker_enabled?(workflow, "integration-verify")
+              checker = cross_track_consistency_check(root, state.fetch("current_feature"))
+              unless checker["ok"] == true
+                result = fail_result("cross_track_consistency_failed", "checker" => checker)
+              end
+            end
+            if result.nil? && business_cross_model_checker_enabled?(workflow, "integration-verify")
+              checker = business_cross_model_check(root, state.fetch("current_feature"))
+              unless checker["valid"] == true
+                result = fail_result("business_cross_model_check_failed", "checker" => checker)
+              end
+            end
+            if result.nil?
+              state, parallel_run_to_write, action_description = join_parallel_window(root, state, workflow, current_revision)
+              changed = true
+              actions << "parallel_window_joined"
+            end
+          rescue ArgumentError, KeyError, TypeError => error
+            result = fail_result("parallel_join_failed", "message" => error.message)
+          end
+        else
+          begin
+            advance_parallel_branch(root, state, options, project_lock)
+            actions << "parallel_branch_#{options[:parallel_action]}"
+            action_description = "Parallel branch #{options[:parallel_action]}: #{options[:parallel_branch_id]}"
+          rescue ArgumentError, KeyError, TypeError => error
+            result = fail_result("parallel_branch_transition_failed", "message" => error.message)
+          end
+        end
+      end
+
       if result.nil? && options[:checkpoint_decision]
         state["checkpoint_decision"] = options[:checkpoint_decision]
         changed = true
@@ -675,6 +942,12 @@ result =
             state["checkpoint"] = step["checkpoint"]
             state["checkpoint_label"] = checkpoint_label(workflow, step["checkpoint"])
             action_description = "Step completed: #{step["label"]} (#{step_id}). Now waiting at #{step["checkpoint"]}."
+          elsif (parallel_window = parallel_window_for(workflow, step_id))
+            state["current_step"] = parallel_window.fetch("join_step")
+            state["status"] = "in_progress"
+            state.delete("checkpoint")
+            state.delete("checkpoint_label")
+            action_description = "Step completed: #{step["label"]} (#{step_id}). Entered parallel window #{parallel_window["id"]}; awaiting Core prepare."
           elsif track_boundary?(state, pending)
             state["current_step"] = step_id
             state["status"] = "blocked"
@@ -784,21 +1057,25 @@ result =
                 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")
+                  frozen = RequirementGraph.freeze_test_cases!(
+                    root,
+                    graph,
+                    "CP-3: state revision #{current_revision} approved",
+                    confirm_prerequisites: options[:confirm_test_prerequisites] && options[:runtime_confirmed],
+                    persist: false
+                  )
                   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
+                    actions << "acceptance_test_prerequisites_confirmed" unless Array(frozen["confirmed_prerequisite_ids"]).empty?
+                    test_suite_freeze_to_write = {
+                      "feature" => feature,
+                      "state_revision" => current_revision,
+                      "graph" => graph,
+                      "candidate_check" => candidate_check,
+                      "frozen" => frozen
+                    }
+                    actions << "acceptance_test_suite_frozen"
                   end
                 end
               end
@@ -914,22 +1191,49 @@ result =
           if !ownership["ok"]
             result = fail_result("phase_ownership_claim_failed", "ownership" => ownership)
           else
-            sync_artifact_registry(root, workflow, state, registry: candidate_registry)
-            artifact_by_path = load_artifact_registry(root, workflow)
-            write_state_file(root, state_path, state, workflow, artifact_by_path, action_description)
-            # STATE.md is project-global. Once its top-level workflow is
-            # terminal, retain the historical owner but release its active
-            # reservation so the next feature can claim a distinct phase.
-            if %w[completed failed cancelled].include?(state["status"]) && Array(state["pending_steps"]).empty? && state["source_flow"].nil?
-              completed_owner = PhaseOwnership.complete(
-                root: root, feature: state["current_feature"], phase: state["current_phase"],
-                flow: state["current_flow"], write: true
+            if test_suite_freeze_to_write
+              pending_freeze = test_suite_freeze_to_write
+              RequirementGraph.persist_test_suite_freeze!(
+                root,
+                pending_freeze.fetch("graph"),
+                pending_freeze.fetch("frozen").fetch("audit_event")
+              )
+              pending_freeze.fetch("frozen")["tests_view"] = pending_freeze.fetch("graph").dig("views", "tests")
+              write_test_suite_freeze_attestation(
+                root,
+                pending_freeze.fetch("feature"),
+                pending_freeze.fetch("state_revision"),
+                pending_freeze.fetch("candidate_check"),
+                pending_freeze.fetch("frozen")
+              )
+              frozen_check = test_task_binding_check(root, pending_freeze.fetch("feature"), "frozen")
+              unless frozen_check["ok"]
+                result = fail_result("acceptance_test_suite_freeze_attestation_invalid", "test_suite" => frozen_check)
+              end
+            end
+            unless result
+              sync_artifact_registry(root, workflow, state, registry: candidate_registry)
+              artifact_by_path = load_artifact_registry(root, workflow)
+              write_state_file(root, state_path, state, workflow, artifact_by_path, action_description)
+              ParallelRun.write(root, state.fetch("current_feature"), parallel_run_to_write) if parallel_run_to_write
+              ParallelRun.rebase_state_revision(
+                root: root, feature: state.fetch("current_feature"),
+                state_revision: state.fetch("revision"), lock: project_lock
               )
-              unless completed_owner["ok"]
-                result = fail_result("phase_ownership_completion_failed", "ownership" => completed_owner)
+              # STATE.md is project-global. Once its top-level workflow is
+              # terminal, retain the historical owner but release its active
+              # reservation so the next feature can claim a distinct phase.
+              if %w[completed failed cancelled].include?(state["status"]) && Array(state["pending_steps"]).empty? && state["source_flow"].nil?
+                completed_owner = PhaseOwnership.complete(
+                  root: root, feature: state["current_feature"], phase: state["current_phase"],
+                  flow: state["current_flow"], write: true
+                )
+                unless completed_owner["ok"]
+                  result = fail_result("phase_ownership_completion_failed", "ownership" => completed_owner)
+                end
               end
+              next_intent_written = write_next_intent(root, workflow) if next_intent_requested
             end
-            next_intent_written = write_next_intent(root, workflow) if next_intent_requested
           end
         end
 

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

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Validate business/technical claims against frozen business facts."""
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+from pathlib import Path
+from typing import Any
+
+
+def load_yaml(path: Path) -> Any:
+    try:
+        import yaml  # type: ignore
+        return yaml.safe_load(path.read_text(encoding="utf-8"))
+    except ImportError:
+        result = subprocess.run(["ruby", "-ryaml", "-rjson", "-e", "puts JSON.generate(YAML.safe_load(File.read(ARGV.fetch(0))))", str(path)], text=True, capture_output=True, check=False)
+        if result.returncode != 0:
+            raise ValueError(result.stderr.strip() or "YAML parse failed")
+        return json.loads(result.stdout)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--claims", type=Path, required=True)
+    parser.add_argument("--business-canonical", type=Path, required=True)
+    parser.add_argument("--traceability", type=Path)
+    args = parser.parse_args()
+    try:
+        claims = load_yaml(args.claims)
+        business = json.loads(args.business_canonical.read_text(encoding="utf-8"))
+        traceability = json.loads(args.traceability.read_text(encoding="utf-8")) if args.traceability else {}
+    except Exception as error:
+        print(json.dumps({"valid": False, "verdict": "block_unsafe", "errors": [{"code": "BUSINESS_CLAIM_SCHEMA_INVALID", "message": str(error)}]}, ensure_ascii=False))
+        return 1
+    errors = []
+    warnings = []
+    actions = {item.get("id") for item in business.get("actions", []) if isinstance(item, dict)}
+    requirements = {item.get("id") for item in traceability.get("requirements", []) if isinstance(item, dict) and item.get("status") in {"confirmed", "approved"}} if isinstance(traceability, dict) else set()
+    values = claims.get("claims") if isinstance(claims, dict) else claims
+    if not isinstance(values, list):
+        errors.append({"code": "BUSINESS_CLAIM_SCHEMA_INVALID", "path": "claims", "message": "claims must be an array"})
+        values = []
+    for index, claim in enumerate(values):
+        path = f"claims[{index}]"
+        if not isinstance(claim, dict):
+            errors.append({"code": "BUSINESS_CLAIM_SCHEMA_INVALID", "path": path, "message": "claim must be an object"})
+            continue
+        allowed = {"id", "text", "kind", "business_action_ref", "requirement_ref"}
+        for key in claim:
+            if key not in allowed:
+                errors.append({"code": "BUSINESS_CLAIM_UNKNOWN_FIELD", "path": f"{path}.{key}", "message": "unknown claim field"})
+        if not isinstance(claim.get("id"), str) or not claim["id"].strip() or not isinstance(claim.get("text"), str) or not claim["text"].strip():
+            errors.append({"code": "BUSINESS_CLAIM_SCHEMA_INVALID", "path": path, "message": "id and text are required"})
+        if isinstance(claim.get("id"), str) and sum(1 for item in values[:index] if isinstance(item, dict) and item.get("id") == claim.get("id")):
+            errors.append({"code": "BUSINESS_CLAIM_DUPLICATE_ID", "path": f"{path}.id", "message": f"duplicate claim id {claim['id']}"})
+        kind = claim.get("kind")
+        if kind not in {"business", "technical"}:
+            errors.append({"code": "BUSINESS_CLAIM_SCHEMA_INVALID", "path": f"{path}.kind", "message": "kind must be business or technical"})
+        ref = claim.get("business_action_ref")
+        req = claim.get("requirement_ref")
+        if ref and ref not in actions:
+            errors.append({"code": "BUSINESS_CLAIM_REF_UNRESOLVED", "path": f"{path}.business_action_ref", "message": f"unknown business action {ref}"})
+        if req and (not args.traceability or req not in requirements):
+            errors.append({"code": "BUSINESS_CLAIM_REF_UNRESOLVED", "path": f"{path}.requirement_ref", "message": f"requirement is not confirmed or traceability input is missing: {req}"})
+        if kind == "business" and not ref and not req:
+            errors.append({"code": "BUSINESS_CLAIM_REF_MISSING", "path": path, "message": "business claim requires action or requirement reference"})
+        if kind == "technical" and not ref and not req:
+            warnings.append({"code": "TECHNICAL_CLAIM_UNGROUNDED", "path": path, "message": "technical claim has no business grounding reference"})
+    verdict = "block_unsafe" if errors else ("await_user" if warnings else "allow")
+    payload = {"valid": not errors, "verdict": verdict, "errors": errors, "warnings": warnings}
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0 if verdict in {"allow", "await_user"} else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())