@guanlin4924/devflow-pi 0.1.0

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

@@ -0,0 +1,565 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "yaml"
+
+module WorkflowStateValidator
+  REQUIRED_STATE_FIELDS = %w[
+    current_flow
+    current_feature
+    current_phase
+    current_step
+    status
+    completed_steps
+    pending_steps
+  ].freeze
+
+  TERMINAL_ARTIFACT_STATUSES = %w[approved completed passed].freeze
+  NON_TERMINAL_ARTIFACT_STATUSES = %w[planned generated pending_rerun stale failed].freeze
+
+  module_function
+
+  def validate(root:, state_path:, state_override: nil, workflow_override: nil, strict_artifact_status: true, strict_registry_revision: true)
+    root = File.expand_path(root)
+    state_path = File.expand_path(state_path, root)
+    issues = []
+
+    state = state_override || load_state(state_path, issues)
+    return result(false, state_path, nil, nil, issues) unless state
+
+    REQUIRED_STATE_FIELDS.each do |field|
+      issues << issue("error", "missing_state_field", "STATE.md is missing required field: #{field}", field: field) unless state.key?(field)
+    end
+    return result(false, state_path, nil, nil, issues) if issues.any? { |entry| entry["severity"] == "error" }
+
+    workflow_path = state["workflow_config"] || File.join(".planning", "workflows", "#{state.fetch("current_flow")}.yaml")
+    abs_workflow_path = File.expand_path(workflow_path, root)
+    workflow = workflow_override || load_yaml(abs_workflow_path, issues, "workflow_config")
+    return result(false, state_path, workflow_path, nil, issues) unless workflow
+
+    registry_path = workflow.dig("artifact_registry", "source")
+    artifact_by_path = load_artifacts(
+      root,
+      registry_path,
+      issues,
+      state_revision: state.fetch("revision", 0),
+      strict_registry_revision: strict_registry_revision
+    )
+
+    steps = Array(workflow["steps"])
+    step_by_id = steps.to_h { |step| [step.fetch("id"), step] }
+    step_ids = steps.map { |step| step.fetch("id") }
+    completed_ids = Array(state["completed_steps"])
+    pending_ids = Array(state["pending_steps"])
+    tracked_ids = completed_ids + pending_ids
+
+    validate_step_tracking(issues, state, step_ids, completed_ids, pending_ids, tracked_ids)
+    validate_track_scope(issues, state, completed_ids)
+    validate_dependencies(issues, step_by_id, completed_ids)
+    validate_completed_outputs(issues, root, state, step_by_id, completed_ids, artifact_by_path, strict_artifact_status)
+    validate_waiting_checkpoint(issues, root, state, step_by_id, artifact_by_path, strict_artifact_status)
+
+    ok = issues.none? { |entry| entry["severity"] == "error" }
+    result(ok, state_path, workflow_path, registry_path, issues)
+  end
+
+  def load_state(path, issues)
+    unless File.exist?(path)
+      issues << issue("error", "missing_state_file", "STATE.md does not exist", path: path)
+      return nil
+    end
+
+    doc = File.read(path)
+    yaml = doc.match(/\A---\n(.*?)\n---\n/m)&.[](1)
+    unless yaml
+      issues << issue("error", "missing_state_front_matter", "STATE.md is missing YAML front matter", path: path)
+      return nil
+    end
+
+    YAML.safe_load(yaml, permitted_classes: [], aliases: false)
+  rescue Psych::SyntaxError => e
+    issues << issue("error", "invalid_state_yaml", e.message, path: path)
+    nil
+  end
+
+  def load_yaml(path, issues, code)
+    unless File.exist?(path)
+      issues << issue("error", "missing_#{code}", "YAML file does not exist", path: path)
+      return nil
+    end
+
+    YAML.safe_load(File.read(path), permitted_classes: [], aliases: false)
+  rescue Psych::SyntaxError => e
+    issues << issue("error", "invalid_#{code}", e.message, path: path)
+    nil
+  end
+
+  def load_artifacts(root, registry_path, issues, state_revision:, strict_registry_revision:)
+    return {} unless registry_path
+
+    abs_registry_path = File.expand_path(registry_path, root)
+    unless File.exist?(abs_registry_path)
+      issues << issue("error", "missing_artifact_registry", "Artifact registry does not exist", path: registry_path)
+      return {}
+    end
+
+    registry = YAML.safe_load(File.read(abs_registry_path), permitted_classes: [], aliases: false)
+    if strict_registry_revision && registry.key?("state_revision") && Integer(registry["state_revision"]) != Integer(state_revision)
+      issues << issue(
+        "error",
+        "artifact_registry_revision_mismatch",
+        "Artifact registry was derived from a different state revision",
+        state_revision: state_revision,
+        registry_revision: registry["state_revision"]
+      )
+    end
+    Array(registry["artifacts"]).to_h { |artifact| [artifact.fetch("path"), artifact] }
+  rescue ArgumentError, TypeError, Psych::SyntaxError => e
+    issues << issue("error", "invalid_artifact_registry", e.message, path: registry_path)
+    {}
+  end
+
+  def validate_step_tracking(issues, state, step_ids, completed_ids, pending_ids, tracked_ids)
+    duplicate_completed = duplicates(completed_ids)
+    duplicate_pending = duplicates(pending_ids)
+    overlap = completed_ids & pending_ids
+    unknown = tracked_ids.uniq - step_ids
+    missing = step_ids - tracked_ids.uniq
+
+    duplicate_completed.each do |step_id|
+      issues << issue("error", "duplicate_completed_step", "Step is duplicated in completed_steps", step: step_id)
+    end
+    duplicate_pending.each do |step_id|
+      issues << issue("error", "duplicate_pending_step", "Step is duplicated in pending_steps", step: step_id)
+    end
+    overlap.each do |step_id|
+      issues << issue("error", "step_in_completed_and_pending", "Step appears in both completed_steps and pending_steps", step: step_id)
+    end
+    unknown.each do |step_id|
+      issues << issue("error", "unknown_tracked_step", "Tracked step is not defined in the active workflow", step: step_id)
+    end
+    missing.each do |step_id|
+      issues << issue("error", "missing_tracked_step", "Workflow step is missing from both completed_steps and pending_steps", step: step_id)
+    end
+
+    current_step = state["current_step"]
+    if current_step && !step_ids.include?(current_step)
+      issues << issue("error", "unknown_current_step", "current_step is not defined in the active workflow", step: current_step)
+    end
+
+    if state["status"] == "completed"
+      if pending_ids.any?
+        issues << issue("error", "completed_with_pending_steps", "Workflow status is completed but pending_steps is not empty")
+      end
+      missing_completed = step_ids - completed_ids
+      missing_completed.each do |step_id|
+        issues << issue("error", "completed_status_missing_step", "Workflow status is completed but a workflow step is not completed", step: step_id)
+      end
+    elsif pending_ids.empty?
+      issues << issue("error", "non_completed_without_pending_steps", "Workflow has no pending steps but status is not completed")
+    end
+  end
+
+  def validate_dependencies(issues, step_by_id, completed_ids)
+    completed_ids.each do |step_id|
+      step = step_by_id[step_id]
+      next unless step
+
+      Array(step["depends_on"]).each do |dependency|
+        next if completed_ids.include?(dependency)
+
+        issues << issue(
+          "error",
+          "completed_step_missing_dependency",
+          "Completed step depends on an incomplete step",
+          step: step_id,
+          dependency: dependency
+        )
+      end
+    end
+  end
+
+  def validate_completed_outputs(issues, root, state, step_by_id, completed_ids, artifact_by_path, strict_artifact_status)
+    completed_ids.each do |step_id|
+      step = step_by_id[step_id]
+      next unless step
+
+      validate_step_outputs(issues, root, state, step, artifact_by_path, strict_artifact_status, waiting_checkpoint_step?(state, step_id))
+      validate_meta_output(issues, root, state, step)
+    end
+  end
+
+  def validate_waiting_checkpoint(issues, root, state, step_by_id, artifact_by_path, strict_artifact_status)
+    return unless state["status"] == "waiting_checkpoint"
+
+    step = step_by_id[state["current_step"]]
+    unless step
+      issues << issue("error", "waiting_checkpoint_unknown_step", "Waiting checkpoint current_step is unknown", step: state["current_step"])
+      return
+    end
+
+    unless step["checkpoint"]
+      issues << issue("error", "waiting_checkpoint_without_step_checkpoint", "State is waiting_checkpoint but current step has no checkpoint", step: step["id"])
+    end
+
+    validate_step_outputs(issues, root, state, step, artifact_by_path, strict_artifact_status, true)
+  end
+
+  def validate_step_outputs(issues, root, state, step, artifact_by_path, strict_artifact_status, waiting_checkpoint)
+    Array(step["outputs"]).each do |output|
+      next unless output["required"]
+
+      path = interpolate_path(output.fetch("path"), state)
+      abs = File.expand_path(path, root)
+      unless File.exist?(abs)
+        issues << issue("error", "missing_required_output", "Completed step required output is missing", step: step["id"], path: path)
+        next
+      end
+
+      artifact = artifact_by_path[path]
+      if artifact.nil?
+        issues << issue("error", "output_not_registered", "Completed step output is not registered in artifact registry", step: step["id"], path: path)
+        next
+      end
+
+      if artifact["content_valid"] == false
+        issues << issue("error", "invalid_registered_output", "Artifact registry marks output content as invalid", step: step["id"], path: path, content_issues: artifact["content_issues"])
+      end
+
+      next unless strict_artifact_status
+
+      status = artifact["status"]
+      allowed = waiting_checkpoint ? (TERMINAL_ARTIFACT_STATUSES + ["generated"]) : TERMINAL_ARTIFACT_STATUSES
+      next if allowed.include?(status)
+
+      code = NON_TERMINAL_ARTIFACT_STATUSES.include?(status) ? "non_terminal_artifact_status" : "unknown_artifact_status"
+      issues << issue("error", code, "Completed step output has a non-terminal artifact status", step: step["id"], path: path, status: status)
+    end
+  end
+
+  def validate_meta_output(issues, root, state, step)
+    meta = step["meta_output"]
+    return unless meta
+
+    path = interpolate_path(meta.fetch("path"), state)
+    abs = File.expand_path(path, root)
+    unless File.exist?(abs)
+      issues << issue("error", "missing_meta_output", "Completed step meta_output is missing", step: step["id"], path: path)
+      return
+    end
+
+    data = JSON.parse(File.read(abs))
+    Array(meta["fields"]).each do |field, config|
+      next unless config.is_a?(Hash) && config["required"]
+      next if data.key?(field) && !data[field].nil?
+
+      issues << issue("error", "missing_meta_field", "Completed step meta_output is missing a required field", step: step["id"], path: path, field: field)
+    end
+
+    validate_requirement_triage_gate(issues, step, data)
+    validate_requirement_wayfinder_gate(issues, step, data)
+    validate_domain_modeling_gate(issues, step, data)
+    validate_requirement_feasibility_review_gate(issues, step, data)
+    validate_requirement_baseline_gate(issues, step, data)
+    validate_api_contract_gate(issues, step, data)
+    validate_api_call_guide_gate(issues, step, data)
+    validate_frontend_tech_spec_gate(issues, step, data)
+    validate_api_supplement_gate(issues, step, data)
+    validate_integration_merge_gate(issues, step, data)
+    validate_verification_gate(issues, step, data)
+  rescue JSON::ParserError => e
+    issues << issue("error", "invalid_meta_json", e.message, step: step["id"], path: path)
+  end
+
+  def validate_requirement_triage_gate(issues, step, data)
+    return unless step["id"] == "requirement-triage"
+
+    allowed_statuses = %w[checked routed blocked superseded]
+    unless allowed_statuses.include?(data["status"].to_s)
+      issues << issue("error", "triage_invalid_status", "Requirement triage meta status is invalid", step: step["id"], status: data["status"])
+    end
+
+    allowed_routes = %w[
+      ready_for_wayfinder
+      ready_for_baseline
+      needs_demand_clarify
+      needs_wayfinder
+      needs_info
+      ready_for_human
+      already_done
+      wontfix
+    ]
+    unless allowed_routes.include?(data["route"].to_s)
+      issues << issue("error", "triage_invalid_route", "Requirement triage meta route is invalid", step: step["id"], route: data["route"])
+    end
+
+    return if data["status"] == "routed" && data["route"] == "ready_for_wayfinder"
+
+    issues << issue(
+      "error",
+      "triage_not_ready_for_wayfinder",
+      "Requirement triage can only complete when status=routed and route=ready_for_wayfinder",
+      step: step["id"],
+      status: data["status"],
+      route: data["route"]
+    )
+  end
+
+  def validate_requirement_wayfinder_gate(issues, step, data)
+    return unless step["id"] == "requirement-wayfinder"
+
+    return if data["status"] == "ready_for_baseline" && data["ready_for_baseline"] == true
+
+    issues << issue(
+      "error",
+      "wayfinder_not_ready",
+      "Requirement wayfinder can only complete when active-slice fog is resolved",
+      step: step["id"],
+      status: data["status"],
+      ready_for_baseline: data["ready_for_baseline"]
+    )
+  end
+
+  def validate_domain_modeling_gate(issues, step, data)
+    return unless step["id"] == "domain-modeling"
+
+    return unless data["feature_name"].to_s.empty?
+
+    issues << issue(
+      "error",
+      "domain_model_missing_feature",
+      "Domain modeling meta must identify the feature it modeled",
+      step: step["id"]
+    )
+  end
+
+  def validate_requirement_feasibility_review_gate(issues, step, data)
+    return unless step["id"] == "requirement-feasibility-review"
+
+    pass = data["status"] == "ready_for_baseline" && data["baseline_gate"] == "pass"
+    pass &&= data["gap_count"].to_i.zero?
+    pass &&= Array(data["critical_finding_ids"]).empty?
+    return if pass
+
+    issues << issue(
+      "error",
+      "feasibility_review_not_passed",
+      "Requirement feasibility review must pass before baseline",
+      step: step["id"],
+      status: data["status"],
+      baseline_gate: data["baseline_gate"],
+      gap_count: data["gap_count"],
+      critical_finding_ids: data["critical_finding_ids"]
+    )
+  end
+
+  def validate_requirement_baseline_gate(issues, step, data)
+    return unless step["id"] == "requirement-baseline"
+
+    if data["review_status"] != "passed"
+      issues << issue("error", "baseline_review_not_passed", "Requirement baseline meta review_status is not passed", step: step["id"], status: data["review_status"])
+    end
+
+    %w[blocking_pending_count critical_image_missing_count challenge_pending_count code_reality_missing_count].each do |field|
+      next if data[field].to_i.zero?
+
+      issues << issue("error", "baseline_blocking_counter_nonzero", "Requirement baseline has a non-zero blocking counter", step: step["id"], field: field, count: data[field])
+    end
+  end
+
+  def validate_api_contract_gate(issues, step, data)
+    return unless step["id"] == "api-contract"
+
+    if data["review_status"] != "passed"
+      issues << issue("error", "api_contract_review_not_passed", "API contract meta review_status is not passed", step: step["id"], status: data["review_status"])
+    end
+
+    if data["pending_contract_count"].to_i.positive?
+      issues << issue("error", "api_contract_pending_items", "API contract has unresolved pending contract items", step: step["id"], count: data["pending_contract_count"])
+    end
+
+    api_required = data["api_required"]
+    endpoint_count = data["endpoint_count"].to_i
+    if api_required == false && endpoint_count.positive?
+      issues << issue("error", "api_contract_noop_with_endpoints", "API contract is marked api_required=false but endpoint_count is greater than zero", step: step["id"], endpoint_count: endpoint_count)
+    elsif api_required != false && endpoint_count.zero?
+      issues << issue("error", "api_contract_required_without_endpoints", "API contract is marked as required but endpoint_count is zero", step: step["id"])
+    end
+  end
+
+  def validate_api_call_guide_gate(issues, step, data)
+    return unless step["id"] == "api-call-guide"
+
+    api_required = data["api_required"]
+    if api_required == false
+      pending_items = data["pending_items"]
+      if pending_items.is_a?(Array) && pending_items.any?
+        issues << issue("error", "api_call_guide_noop_pending_items", "No-op API call guide has pending items", step: step["id"], count: pending_items.length)
+      end
+      return
+    end
+
+    unless data["frontend_consumable"] == true
+      issues << issue("error", "api_call_guide_not_frontend_consumable", "API call guide is not marked frontend_consumable", step: step["id"])
+    end
+
+    unless data["mock_ready"] == true
+      issues << issue("error", "api_call_guide_mock_not_ready", "API call guide mock_ready is not true", step: step["id"])
+    end
+
+    pending_items = data["pending_items"]
+    if pending_items.is_a?(Array) && pending_items.any?
+      issues << issue("error", "api_call_guide_pending_items", "API call guide has unresolved pending items", step: step["id"], count: pending_items.length)
+    end
+  end
+
+  def validate_frontend_tech_spec_gate(issues, step, data)
+    return unless step["id"] == "frontend-tech-spec"
+
+    if data["api_gaps_count"].to_i.negative?
+      issues << issue("error", "frontend_api_gaps_negative", "frontend-tech-spec api_gaps_count cannot be negative", step: step["id"], count: data["api_gaps_count"])
+    end
+  end
+
+  def validate_api_supplement_gate(issues, step, data)
+    return unless step["id"] == "api-supplement"
+
+    supplement_count = data["api_supplement_count"].to_i
+    unresolved_count = data["unresolved_supplement_count"].to_i
+    contract_updated = data["contract_updated"]
+    no_supplement_required = data["no_supplement_required"]
+
+    if no_supplement_required == true
+      if supplement_count.positive? || unresolved_count.positive?
+        issues << issue("error", "api_supplement_noop_has_items", "No-op API supplement reports supplement items", step: step["id"], api_supplement_count: supplement_count, unresolved_supplement_count: unresolved_count)
+      end
+      return
+    end
+
+    if unresolved_count.positive?
+      issues << issue("error", "api_supplement_unresolved_items", "API supplement has unresolved items", step: step["id"], count: unresolved_count)
+    end
+
+    if supplement_count.positive? && contract_updated != true
+      issues << issue("error", "api_supplement_contract_not_updated", "API supplement items exist but contract_updated is not true", step: step["id"])
+    end
+  end
+
+  def validate_integration_merge_gate(issues, step, data)
+    return unless step["id"] == "integration-verify"
+
+    api_required = data["api_required"]
+    if api_required == false
+      unless %w[passed skipped].include?(data["merge_gate_status"])
+        issues << issue("error", "merge_gate_noop_invalid_status", "No-op integration merge gate status must be passed or skipped", step: step["id"], status: data["merge_gate_status"])
+      end
+    elsif data["merge_gate_status"] != "passed"
+      issues << issue("error", "merge_gate_not_passed", "Integration merge gate status is not passed", step: step["id"], status: data["merge_gate_status"])
+    end
+
+    %w[
+      contract_backend_mismatch_count
+      contract_frontend_mismatch_count
+      unhandled_api_supplement_count
+      blocking_issue_count
+    ].each do |field|
+      next if data[field].to_i.zero?
+
+      issues << issue("error", "merge_gate_counter_nonzero", "Integration merge gate has a non-zero blocking counter", step: step["id"], field: field, count: data[field])
+    end
+  end
+
+  def validate_verification_gate(issues, step, data)
+    return unless step["id"] == "verify"
+
+    if data["uat_failed"].to_i.positive?
+      issues << issue("error", "verification_uat_failed", "Verification meta reports failed UAT items", step: step["id"], count: data["uat_failed"])
+    end
+
+    gate_passed = data["gate_passed"].to_i
+    gate_total = data["gate_total"].to_i
+    if gate_total.zero?
+      issues << issue("error", "verification_gate_total_zero", "Verification meta gate_total must be greater than zero", step: step["id"])
+    elsif gate_passed != gate_total
+      issues << issue("error", "verification_gates_not_all_passed", "Verification meta reports incomplete gates", step: step["id"], gate_passed: gate_passed, gate_total: gate_total)
+    end
+  end
+
+  def validate_track_scope(issues, state, completed_ids)
+    track = state["active_track"].to_s
+    return unless %w[A B].include?(track)
+
+    allowed = case track
+              when "A"
+                %w[requirement-triage requirement-wayfinder domain-modeling requirement-feasibility-review requirement-baseline api-contract backend-tech-spec api-call-guide]
+              when "B"
+                %w[requirement-triage requirement-wayfinder domain-modeling requirement-feasibility-review requirement-baseline api-contract ui-spec feature-breakdown frontend-tech-spec api-supplement]
+              end
+
+    illegal = completed_ids - allowed
+    illegal.each do |step_id|
+      issues << issue(
+        "error",
+        "active_track_completed_out_of_scope_step",
+        "Single-track mode cannot complete steps outside its output scope",
+        active_track: track,
+        step: step_id
+      )
+    end
+  end
+
+  def waiting_checkpoint_step?(state, step_id)
+    state["status"] == "waiting_checkpoint" && state["current_step"] == step_id
+  end
+
+  def interpolate_path(path, state)
+    path
+      .gsub("{feature}", state.fetch("current_feature", "").to_s)
+      .gsub("{phase}", state.fetch("current_phase", "").to_s)
+  end
+
+  def duplicates(values)
+    values.each_with_object(Hash.new(0)) { |value, counts| counts[value] += 1 }
+          .select { |_, count| count > 1 }
+          .keys
+  end
+
+  def issue(severity, code, message, details = {})
+    { "severity" => severity, "code" => code, "message" => message }.merge(details.transform_keys(&:to_s))
+  end
+
+  def result(ok, state_path, workflow_path, registry_path, issues)
+    {
+      "ok" => ok,
+      "state_path" => state_path,
+      "workflow_path" => workflow_path,
+      "artifact_registry_path" => registry_path,
+      "errors" => issues.select { |entry| entry["severity"] == "error" },
+      "warnings" => issues.select { |entry| entry["severity"] == "warning" },
+      "issues" => issues
+    }
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  options = { state: ".planning/STATE.md", strict_artifact_status: true, json: false }
+  OptionParser.new do |opts|
+    opts.banner = "Usage: validate_state.rb [--state PATH] [--no-strict-artifact-status] [--json]"
+    opts.on("--state PATH", "STATE.md path") { |path| options[:state] = path }
+    opts.on("--no-strict-artifact-status", "Do not require terminal artifact statuses") { options[:strict_artifact_status] = false }
+    opts.on("--json", "Print JSON output") { options[:json] = true }
+  end.parse!
+
+  root = Dir.pwd
+  state_path = File.expand_path(options[:state], root)
+  validation = WorkflowStateValidator.validate(
+    root: root,
+    state_path: state_path,
+    strict_artifact_status: options[:strict_artifact_status]
+  )
+
+  puts JSON.pretty_generate(validation)
+  exit(validation["ok"] ? 0 : 1)
+end