@guanlin4924/devflow-pi 0.1.0

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

@@ -0,0 +1,553 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "yaml"
+require_relative "validate_state"
+
+options = { json: false, state: nil }
+OptionParser.new do |opts|
+  opts.banner = "Usage: inspect_state.rb [--json] [--state PATH]"
+  opts.on("--json", "Print JSON output") { options[:json] = true }
+  opts.on("--state PATH", "Read an alternate STATE.md file") { |path| options[:state] = path }
+end.parse!
+
+root = Dir.pwd
+state_path = options[:state] ? File.expand_path(options[:state], root) : File.join(root, ".planning", "STATE.md")
+
+def fail_result(reason, details = {})
+  {
+    action: "blocked",
+    reason: reason,
+    details: details
+  }
+end
+
+def front_matter(markdown)
+  match = markdown.match(/\A---\n(.*?)\n---\n/m)
+  match && match[1]
+end
+
+def load_yaml_file(path)
+  YAML.safe_load(File.read(path), permitted_classes: [], aliases: false)
+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 load_artifact_registry(root, workflow)
+  registry_config = workflow["artifact_registry"]
+  registry_path = registry_config && registry_config["source"]
+  return [{}, nil, nil] if registry_path.nil?
+
+  abs_registry_path = File.join(root, registry_path)
+  return [{}, registry_path, "missing_artifact_registry"] unless File.exist?(abs_registry_path)
+
+  registry = load_yaml_file(abs_registry_path)
+  artifacts = Array(registry["artifacts"])
+  by_path = artifacts.to_h { |artifact| [artifact.fetch("path"), artifact] }
+  [by_path, registry_path, nil]
+end
+
+def project_context_missing?(root)
+  required_paths = [
+    File.join(root, ".planning", "PROJECT.md"),
+    File.join(root, ".planning", "navigation", "INDEX.md"),
+    File.join(root, ".context", "spec", "index.md")
+  ]
+
+  required_paths.any? { |path| !File.exist?(path) }
+end
+
+def project_context_result(reason, details = {})
+  {
+    action: "run_project_context",
+    reason: reason,
+    skill: "workflow-project-context",
+    resume_after: "inspect_state"
+  }.merge(details)
+end
+
+def attach_artifact(output, artifact_by_path)
+  artifact = artifact_by_path[output["resolved_path"]]
+  output.merge(
+    "artifact_status" => artifact && artifact["status"],
+    "artifact_type" => artifact && artifact["type"],
+    "artifact_workflow_step" => artifact && artifact["workflow_step"],
+    "artifact_checkpoint" => artifact && artifact["checkpoint"],
+    "artifact_registered" => !artifact.nil?
+  )
+end
+
+def artifact_registry_summary(root, artifact_by_path)
+  artifacts = artifact_by_path.values
+  status_counts = artifacts.each_with_object(Hash.new(0)) do |artifact, counts|
+    counts[artifact["status"] || "unknown"] += 1
+  end
+  missing_paths = artifacts
+                  .map { |artifact| artifact["path"] }
+                  .compact
+                  .reject { |path| File.exist?(File.join(root, path)) }
+
+  {
+    "registered_count" => artifacts.length,
+    "status_counts" => status_counts.sort.to_h,
+    "missing_paths" => missing_paths
+  }
+end
+
+def output_payload(output, state, root, artifact_by_path)
+  resolved = interpolate_path(output.fetch("path"), state)
+  artifact = artifact_by_path[resolved]
+  {
+    "path" => resolved,
+    "type" => output["type"],
+    "required" => output["required"],
+    "exists" => File.exist?(File.join(root, resolved)),
+    "artifact_status" => artifact && artifact["status"],
+    "artifact_registered" => !artifact.nil?
+  }
+end
+
+def step_payload(step, state, root, artifact_by_path)
+  return nil if step.nil?
+
+  {
+    "id" => step["id"],
+    "label" => step["label"],
+    "skill" => step["skill"],
+    "action" => step["action"],
+    "inputs" => Array(step["inputs"]).map { |path| interpolate_path(path, state) },
+    "outputs" => Array(step["outputs"]).map { |output| output_payload(output, state, root, artifact_by_path) }
+  }
+end
+
+def dependencies_satisfied?(step, completed_ids)
+  Array(step["depends_on"]).all? { |dependency| completed_ids.include?(dependency) }
+end
+
+def active_track(state)
+  track = state["active_track"].to_s
+  %w[A B].include?(track) ? track : nil
+end
+
+def track_allowed_steps(track)
+  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]
+  else
+    []
+  end
+end
+
+def next_pending_step_id(state, pending_ids, step_by_id, completed_ids)
+  track = active_track(state)
+  return pending_ids.first unless track
+
+  allowed = track_allowed_steps(track)
+  pending_ids.find do |step_id|
+    allowed.include?(step_id) &&
+      step_by_id[step_id] &&
+      dependencies_satisfied?(step_by_id[step_id], completed_ids)
+  end
+end
+
+def track_boundary(state, pending_ids, completed_ids)
+  track = active_track(state)
+  return nil unless track
+
+  allowed = track_allowed_steps(track)
+  remaining_allowed = pending_ids & allowed
+  return nil if remaining_allowed.any?
+
+  return nil if pending_ids.empty?
+
+  {
+    "reason" => "track_scope_complete",
+    "message" => "Track #{track} output scope is complete. Single-track mode cannot enter integration-verify, change-plan, execute, or archive."
+  }
+end
+
+def active_parallel_window(workflow, state, root, step_by_id, completed_ids, pending_ids, artifact_by_path)
+  Array(workflow["parallel_windows"]).each do |window|
+    after_step = window["after_step"]
+    branch_map = window["branches"].is_a?(Hash) ? window["branches"] : {}
+    branch_ids = branch_map.any? ? branch_map.values.flatten : Array(window["branch_steps"])
+    track = active_track(state)
+    branch_ids &= track_allowed_steps(track) if track
+    next unless completed_ids.include?(after_step)
+
+    runnable_ids = branch_ids.select do |step_id|
+      step = step_by_id[step_id]
+      pending_ids.include?(step_id) && step && dependencies_satisfied?(step, completed_ids)
+    end
+    next unless runnable_ids.length > 1
+
+    policy = window["execution_policy"] || {}
+    return {
+      "id" => window["id"],
+      "label" => window["label"],
+      "after_step" => after_step,
+      "join_step" => window["join_step"],
+      "checkpoint" => window["checkpoint"],
+      "mode" => policy["mode"],
+      "serial_fallback_order" => Array(policy["serial_fallback_order"]),
+      "branches" => branch_map.transform_values do |step_ids|
+        Array(step_ids).map { |step_id| step_payload(step_by_id[step_id], state, root, artifact_by_path) }.compact
+      end,
+      "join_requires" => Array(policy["join_requires"]).map { |path| interpolate_path(path, state) },
+      "branch_steps" => runnable_ids.map { |step_id| step_payload(step_by_id[step_id], state, root, artifact_by_path) }
+    }
+  end
+
+  nil
+end
+
+def active_failure_branch(workflow, state, current_step, current_outputs, root)
+  branch = workflow.fetch("failure_branches", {})[current_step["id"]]
+  return nil if branch.nil?
+
+  conditions = branch["trigger_conditions"] || {}
+  reasons = []
+
+  if Array(conditions["state_statuses"]).include?(state["status"])
+    reasons << { "source" => "state.status", "value" => state["status"] }
+  end
+
+  checkpoint_decision = state["checkpoint_decision"]
+  if checkpoint_decision && Array(conditions["checkpoint_decisions"]).include?(checkpoint_decision)
+    reasons << { "source" => "state.checkpoint_decision", "value" => checkpoint_decision }
+  end
+
+  failed_outputs = current_outputs.select do |output|
+    Array(conditions["artifact_statuses"]).include?(output["artifact_status"])
+  end
+  failed_outputs.each do |output|
+    reasons << {
+      "source" => "artifact.status",
+      "path" => output["resolved_path"],
+      "value" => output["artifact_status"]
+    }
+  end
+
+  return nil if reasons.empty?
+
+  workflow_config = branch["workflow_config"]
+  abs_workflow_config = workflow_config && File.join(root, workflow_config)
+  branch_workflow = abs_workflow_config && File.exist?(abs_workflow_config) ? load_yaml_file(abs_workflow_config) : nil
+  branch_steps = Array(branch_workflow && branch_workflow["steps"])
+  entry_step_id = branch_workflow&.dig("entry", "initial_step") || branch_steps.first&.fetch("id", nil)
+
+  {
+    "id" => branch["id"],
+    "label" => branch["label"],
+    "workflow" => branch["workflow"],
+    "workflow_config" => workflow_config,
+    "workflow_config_exists" => abs_workflow_config ? File.exist?(abs_workflow_config) : false,
+    "entry_step" => entry_step_id,
+    "reason_signals" => reasons,
+    "resume_after_success" => branch["resume_after_success"],
+    "steps" => branch_steps.map do |step|
+      {
+        "id" => step["id"],
+        "label" => step["label"],
+        "skill" => step["skill"],
+        "action" => step["action"],
+        "depends_on" => Array(step["depends_on"])
+      }
+    end
+  }
+end
+
+result =
+  if !File.exist?(state_path)
+    if project_context_missing?(root)
+      project_context_result(
+        "missing_project_context",
+        path: state_path,
+        missing: [
+          ".planning/STATE.md",
+          ".planning/PROJECT.md",
+          ".planning/navigation/INDEX.md",
+          ".context/spec/index.md"
+        ]
+      )
+    else
+      fail_result(
+        "missing_state_file",
+        path: state_path,
+        recovery: "Call devflow_bootstrap with feature and phase."
+      )
+    end
+  else
+    state_doc = File.read(state_path)
+    yaml = front_matter(state_doc)
+
+    if yaml.nil?
+      fail_result(
+        "missing_state_front_matter",
+        path: state_path,
+        recovery: "Call devflow_bootstrap with feature, phase, and force=true after reviewing the invalid state."
+      )
+    else
+      state = YAML.safe_load(yaml, permitted_classes: [], aliases: false)
+      required = %w[
+        current_flow
+        current_feature
+        current_phase
+        current_step
+        status
+        completed_steps
+        pending_steps
+      ]
+      missing = required.reject { |key| state.key?(key) }
+
+      if missing.any?
+        fail_result("missing_state_fields", fields: missing)
+      elsif project_context_missing?(root)
+        project_context_result(
+          "incomplete_project_context",
+          missing: [
+            ".planning/PROJECT.md",
+            ".planning/navigation/INDEX.md",
+            ".context/spec/index.md"
+          ]
+        )
+      else
+        pending_template_blockers = Array(state["blockers"]).select do |blocker|
+          blocker.is_a?(Hash) && blocker["type"] == "PENDING_TEMPLATE"
+        end
+
+        if pending_template_blockers.any?
+          fail_result(
+            "pending_depth_spec_templates",
+            blockers: pending_template_blockers,
+            recovery: "add the missing template or mark the topic NOT_APPLICABLE, then rerun workflow-project-context"
+          )
+        else
+          workflow_path = state["workflow_config"] ||
+                          File.join(".planning", "workflows", "#{state["current_flow"]}.yaml")
+          abs_workflow_path = File.join(root, workflow_path)
+
+        if !File.exist?(abs_workflow_path)
+          fail_result(
+            "missing_workflow_config",
+            path: workflow_path,
+            recovery: "Call devflow_bootstrap with feature and phase."
+          )
+        else
+          workflow = load_yaml_file(abs_workflow_path)
+          artifact_by_path, artifact_registry_path, artifact_registry_error = load_artifact_registry(root, workflow)
+          steps = workflow.fetch("steps", [])
+          step_by_id = steps.to_h { |step| [step.fetch("id"), step] }
+          current_step = step_by_id[state["current_step"]]
+          pending_ids = Array(state["pending_steps"])
+          completed_ids = Array(state["completed_steps"])
+          validation = WorkflowStateValidator.validate(
+            root: root,
+            state_path: state_path,
+            state_override: state,
+            workflow_override: workflow,
+            strict_artifact_status: true
+          )
+
+          if !validation["ok"]
+            {
+              current_flow: state["current_flow"],
+              current_feature: state["current_feature"],
+              current_phase: state["current_phase"],
+              status: state["status"],
+              completed_steps: completed_ids,
+              pending_steps: pending_ids,
+              current_step: current_step && {
+                id: current_step["id"],
+                label: current_step["label"],
+                skill: current_step["skill"],
+                action: current_step["action"]
+              },
+              next_step: nil,
+              workflow_config: workflow_path,
+              artifact_registry: artifact_registry_summary(root, artifact_by_path).merge(
+                "path" => artifact_registry_path,
+                "error" => artifact_registry_error,
+                "recovery" => artifact_registry_error ? "Call devflow_artifact with action=sync." : nil,
+                "current_outputs_registered" => 0
+              ),
+              action: "blocked",
+              reason: "state_validation_failed",
+              state_validation: validation,
+              recovery: "Fix missing/invalid artifacts or call devflow_artifact with action=sync and preserve=false, then call devflow_state with action=inspect."
+            }
+          elsif current_step.nil?
+            fallback_next_id = next_pending_step_id(state, pending_ids, step_by_id, completed_ids)
+            fallback_next_step = fallback_next_id && step_by_id[fallback_next_id]
+
+            if fallback_next_step
+              {
+                current_flow: state["current_flow"],
+                current_feature: state["current_feature"],
+                current_phase: state["current_phase"],
+                status: state["status"],
+                completed_steps: completed_ids,
+                pending_steps: pending_ids,
+                current_step: nil,
+                next_step: step_payload(fallback_next_step, state, root, artifact_by_path),
+                workflow_config: workflow_path,
+                artifact_registry: artifact_registry_summary(root, artifact_by_path).merge(
+                  "path" => artifact_registry_path,
+                  "error" => artifact_registry_error,
+                  "recovery" => artifact_registry_error ? "Call devflow_artifact with action=sync." : nil,
+                  "current_outputs_registered" => 0
+                ),
+                action: "run_next_step",
+                reason: "current_step_not_in_workflow_using_pending_step"
+              }
+            elsif pending_ids.empty? && state["status"] == "completed"
+              {
+                current_flow: state["current_flow"],
+                current_feature: state["current_feature"],
+                current_phase: state["current_phase"],
+                status: state["status"],
+                completed_steps: completed_ids,
+                pending_steps: pending_ids,
+                current_step: nil,
+                next_step: nil,
+                workflow_config: workflow_path,
+                artifact_registry: artifact_registry_summary(root, artifact_by_path).merge(
+                  "path" => artifact_registry_path,
+                  "error" => artifact_registry_error,
+                  "recovery" => artifact_registry_error ? "Call devflow_artifact with action=sync." : nil,
+                  "current_outputs_registered" => 0
+                ),
+                action: "workflow_complete",
+                reason: "completed_status_with_no_pending_steps"
+              }
+            else
+              fail_result("unknown_current_step", current_step: state["current_step"])
+            end
+          else
+            current_outputs = Array(current_step["outputs"]).map do |output|
+              resolved = interpolate_path(output.fetch("path"), state)
+              attach_artifact(
+                output.merge("resolved_path" => resolved, "exists" => File.exist?(File.join(root, resolved))),
+                artifact_by_path
+              )
+            end
+
+            next_id = next_pending_step_id(state, pending_ids, step_by_id, completed_ids)
+            next_step = next_id && step_by_id[next_id]
+            checkpoint_id = state["checkpoint"] || current_step["checkpoint"]
+            checkpoint = checkpoint_id && workflow.fetch("checkpoints", {})[checkpoint_id]
+            parallel_window = active_parallel_window(workflow, state, root, step_by_id, completed_ids, pending_ids, artifact_by_path)
+            failure_branch = active_failure_branch(workflow, state, current_step, current_outputs, root)
+
+            base = {
+              current_flow: state["current_flow"],
+              current_feature: state["current_feature"],
+              current_phase: state["current_phase"],
+              status: state["status"],
+              checkpoint: checkpoint_id,
+              checkpoint_label: checkpoint && checkpoint["name"],
+              completed_steps: completed_ids,
+              pending_steps: pending_ids,
+              current_step: {
+                id: current_step["id"],
+                label: current_step["label"],
+                skill: current_step["skill"],
+                action: current_step["action"],
+                outputs: current_outputs
+              },
+              next_step: next_step && {
+                id: next_step["id"],
+                label: next_step["label"],
+                skill: next_step["skill"],
+                action: next_step["action"],
+                inputs: Array(next_step["inputs"]).map { |path| interpolate_path(path, state) },
+                outputs: Array(next_step["outputs"]).map do |output|
+                  resolved = interpolate_path(output.fetch("path"), state)
+                  artifact = artifact_by_path[resolved]
+                  {
+                    path: resolved,
+                    type: output["type"],
+                    required: output["required"],
+                    exists: File.exist?(File.join(root, resolved)),
+                    artifact_status: artifact && artifact["status"],
+                    artifact_registered: !artifact.nil?
+                  }
+                end
+              },
+              parallel_window: parallel_window,
+              workflow_config: workflow_path,
+              artifact_registry: artifact_registry_summary(root, artifact_by_path).merge(
+                "path" => artifact_registry_path,
+                "error" => artifact_registry_error,
+                "recovery" => artifact_registry_error ? "Call devflow_artifact with action=sync." : nil,
+                "current_outputs_registered" => current_outputs.count { |output| output["artifact_registered"] }
+              )
+            }
+
+            boundary = track_boundary(state, pending_ids, completed_ids)
+
+            if artifact_registry_error
+              base.merge(
+                action: "blocked",
+                reason: artifact_registry_error,
+                recovery: "Call devflow_artifact with action=sync."
+              )
+            elsif boundary
+              base.merge(
+                action: "blocked",
+                reason: boundary["reason"],
+                message: boundary["message"],
+                active_track: active_track(state)
+              )
+            elsif failure_branch
+              base.merge(
+                action: "route_failure_branch",
+                reason: "failure_branch_triggered",
+                failure_branch: failure_branch
+              )
+            elsif state["status"] == "waiting_checkpoint"
+              missing_outputs = current_outputs
+                                .select { |output| output["required"] && !output["exists"] }
+                                .map { |output| output["resolved_path"] }
+
+              base.merge(
+                action: missing_outputs.empty? ? "await_user_confirmation" : "blocked",
+                reason: missing_outputs.empty? ? nil : "missing_checkpoint_outputs",
+                missing_outputs: missing_outputs,
+                resume_behavior: checkpoint && checkpoint["resume_behavior"],
+                next_intent: ".planning/.next-intent"
+              )
+            elsif parallel_window
+              base.merge(action: "run_parallel_window")
+            elsif next_step
+              base.merge(action: "run_next_step")
+            elsif pending_ids.empty?
+              base.merge(action: "workflow_complete")
+            else
+              base.merge(action: "blocked", reason: "unknown_next_step", next_step_id: next_id)
+            end
+          end
+          end
+        end
+      end
+    end
+  end
+
+if defined?(state) && state.is_a?(Hash) && result.is_a?(Hash)
+  result = result.merge(revision: Integer(state.fetch("revision", 0)))
+end
+
+if options[:json]
+  puts JSON.pretty_generate(result)
+else
+  puts "action: #{result[:action] || result["action"]}"
+  puts JSON.pretty_generate(result)
+end