@guanlin4924/devflow-pi 0.1.0

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

@@ -0,0 +1,520 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "date"
+require "fileutils"
+require "json"
+require "optparse"
+require "yaml"
+require_relative "control_io"
+require_relative "validate_state"
+
+options = {
+  state: nil,
+  write: false,
+  complete_step: nil,
+  confirm_checkpoint: false,
+  checkpoint_decision: nil,
+  enter_failure_branch: false,
+  expected_revision: nil,
+  json: false
+}
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: advance_state.rb [options]"
+  opts.on("--state PATH", "Read/write an alternate STATE.md file") { |path| options[:state] = path }
+  opts.on("--write", "Persist changes. Without this flag, the script only previews.") { options[:write] = true }
+  opts.on("--complete-step STEP", "Mark STEP complete and advance state") { |step| options[:complete_step] = step }
+  opts.on("--confirm-checkpoint", "Advance from waiting checkpoint to the next pending step") { options[:confirm_checkpoint] = true }
+  opts.on("--checkpoint-decision VALUE", "Set checkpoint decision, e.g. approved, rejected, needs_fix") { |value| options[:checkpoint_decision] = value }
+  opts.on("--enter-failure-branch", "Transition into the configured failure branch for the current step") { options[:enter_failure_branch] = true }
+  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 }
+end.parse!
+
+root = Dir.pwd
+state_path = options[:state] ? File.expand_path(options[:state], root) : File.join(root, ".planning", "STATE.md")
+
+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 workflow_path_for(root, state)
+  state["workflow_config"] || File.join(".planning", "workflows", "#{state.fetch("current_flow")}.yaml")
+end
+
+def load_workflow(root, state)
+  path = workflow_path_for(root, state)
+  [path, load_yaml_file(File.join(root, path))]
+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_path = workflow.dig("artifact_registry", "source")
+  return {} unless registry_path
+
+  abs = File.join(root, registry_path)
+  return {} unless File.exist?(abs)
+
+  registry = load_yaml_file(abs)
+  Array(registry["artifacts"]).to_h { |a| [a.fetch("path"), a] }
+end
+
+def collect_outputs(workflow)
+  Array(workflow["steps"]).flat_map do |step|
+    Array(step["outputs"]).map { |output| [step, output] }
+  end
+end
+
+def content_validity(root, path, checks)
+  abs = File.join(root, path)
+  return { "valid" => false, "issues" => ["file_missing"] } unless File.exist?(abs)
+
+  issues = []
+  min_bytes = checks["min_bytes"]
+  required_header = checks["required_header"]
+
+  if min_bytes && File.size(abs) < min_bytes
+    issues << "below_min_bytes(#{File.size(abs)} < #{min_bytes})"
+  end
+
+  if required_header
+    head = File.read(abs, [required_header.length + 50, 200].min)
+    issues << "missing_required_header(#{required_header.inspect})" unless head.include?(required_header)
+  end
+
+  { "valid" => issues.empty?, "issues" => issues }
+end
+
+def sync_artifact_registry(root, workflow, state)
+  registry_path = workflow.dig("artifact_registry", "source")
+  return nil unless registry_path
+
+  abs = File.join(root, registry_path)
+  existing_by_path = if File.exist?(abs)
+                       Array(load_yaml_file(abs)["artifacts"]).to_h { |artifact| [artifact.fetch("path"), artifact] }
+                     else
+                       {}
+                     end
+
+  completed = Array(state["completed_steps"])
+  current_step = state["current_step"]
+  content_checks = workflow.dig("artifact_registry", "content_checks") || {}
+  preservable_statuses = %w[approved completed passed pending_rerun stale failed]
+
+  artifacts = collect_outputs(workflow).map do |step, output|
+    path = interpolate_path(output.fetch("path"), state)
+    existing = existing_by_path[path] || {}
+    generated_status =
+      if completed.include?(step.fetch("id"))
+        step["checkpoint"] ? "approved" : "completed"
+      elsif step.fetch("id") == current_step && state["status"] == "waiting_checkpoint"
+        "generated"
+      else
+        "planned"
+      end
+
+    validity = content_validity(root, path, content_checks)
+    file_exists = File.exist?(File.join(root, path))
+    status = if preservable_statuses.include?(existing["status"])
+               existing["status"]
+             else
+               generated_status
+             end
+
+    {
+      "path" => path,
+      "type" => output["type"],
+      "workflow_step" => step.fetch("id"),
+      "produced_by" => step["skill"] || step["action"],
+      "status" => status,
+      "checkpoint" => existing["checkpoint"] || step["checkpoint"],
+      "covers" => Array(existing["covers"]),
+      "downstream_steps" => Array(existing["downstream_steps"]),
+      "exists" => file_exists,
+      "content_valid" => validity["valid"],
+      "content_issues" => validity["issues"].empty? ? nil : validity["issues"]
+    }.reject { |_, value| value.nil? || value == [] }
+  end
+
+  registry = {
+    "schema_version" => 1,
+    "state_revision" => state.fetch("revision", 0),
+    "updated_at" => Date.today.to_s,
+    "registry_scope" => {
+      "flow" => state["current_flow"],
+      "feature" => state["current_feature"],
+      "phase" => state["current_phase"]
+    },
+    "artifacts" => artifacts
+  }
+
+  DevflowControlIO.atomic_write(abs, registry.to_yaml)
+  registry_path
+end
+
+def artifact_status_icon(status, exists, content_valid)
+  return "❌" unless exists
+  return "⚠️" if content_valid == false
+  case status
+  when "approved", "completed", "passed" then "✅"
+  when "generated" then "📝"
+  when "failed" then "❌"
+  else "⬜"
+  end
+end
+
+def generate_body(root, state, workflow, artifact_by_path, action_description)
+  feature = state["current_feature"] || "—"
+  phase = state["current_phase"] || "—"
+  status = state["status"] || "unknown"
+  current_step_id = state["current_step"]
+  checkpoint_id = state["checkpoint"]
+
+  steps = Array(workflow["steps"])
+  step_by_id = steps.to_h { |s| [s.fetch("id"), s] }
+
+  completed_ids = Array(state["completed_steps"])
+  pending_ids = Array(state["pending_steps"])
+
+  status_labels = { "completed" => "All steps complete", "blocked" => "Blocked", "failed" => "Failed" }
+  current_step = step_by_id[current_step_id]
+  current_label = if current_step
+                    "#{current_step["label"]} (#{current_step_id})"
+                  elsif status_labels.key?(current_step_id.to_s)
+                    status_labels[current_step_id.to_s]
+                  else
+                    current_step_id.to_s
+                  end
+
+  checkpoint = checkpoint_id && workflow.dig("checkpoints", checkpoint_id)
+  cp_label = checkpoint ? "#{checkpoint_id}: #{checkpoint["name"]}" : checkpoint_id
+
+  lines = []
+  lines << "<!-- ⚠ GENERATED by advance_state.rb on #{Time.now.strftime("%Y-%m-%d %H:%M")} — DO NOT EDIT -->"
+  lines << ""
+  lines << "## Current State"
+  lines << ""
+  lines << "| Field | Value |"
+  lines << "|-------|-------|"
+  lines << "| Flow | `#{state["current_flow"]}` |"
+  lines << "| Feature | #{feature} |"
+  lines << "| Phase | #{phase} |"
+  lines << "| Step | #{current_label} |"
+  lines << "| Status | **#{status}** |"
+  lines << "| Checkpoint | #{cp_label || "—"} |"
+  if state["checkpoint_decision"]
+    lines << "| CP Decision | #{state["checkpoint_decision"]} |"
+  end
+
+  unless completed_ids.empty?
+    lines << ""
+    lines << "## Completed Steps"
+    lines << ""
+    completed_ids.each do |sid|
+      s = step_by_id[sid]
+      label = s ? s["label"] : sid
+      outputs = Array(s && s["outputs"]).map { |o| interpolate_path(o.fetch("path"), state) }
+      parts = outputs.map do |p|
+        art = artifact_by_path[p]
+        icon = artifact_status_icon(art&.dig("status"), art&.dig("exists") || File.exist?(File.join(root, p)), art&.dig("content_valid"))
+        "#{icon} #{p}"
+      end
+      lines << "- **#{label}** (`#{sid}`) #{parts.join(" ")}".strip
+    end
+  end
+
+  unless pending_ids.empty?
+    lines << ""
+    lines << "## Pending Steps"
+    lines << ""
+    pending_ids.each do |sid|
+      s = step_by_id[sid]
+      label = s ? s["label"] : sid
+      cp = s && s["checkpoint"]
+      note = cp ? " — gates at #{cp}" : ""
+      lines << "- **#{label}** (`#{sid}`)#{note}"
+    end
+  end
+
+  if status == "waiting_checkpoint" && checkpoint
+    lines << ""
+    lines << "## Checkpoint: #{cp_label}"
+    lines << ""
+    lines << "Waiting for user confirmation before advancing."
+  end
+
+  if action_description
+    lines << ""
+    lines << "## Last Action"
+    lines << ""
+    lines << "- #{action_description} — #{Time.now.strftime("%Y-%m-%d %H:%M")}"
+  end
+
+  lines << ""
+  lines.join("\n")
+end
+
+def write_state_file(root, path, state, workflow, artifact_by_path, action_description)
+  front = state.to_yaml.sub(/\A---\n/, "")
+  body = generate_body(root, state, workflow, artifact_by_path, action_description)
+  DevflowControlIO.atomic_write(path, "---\n#{front}---\n\n#{body}")
+end
+
+def checkpoint_label(workflow, checkpoint_id)
+  checkpoint_id && workflow.fetch("checkpoints", {}).dig(checkpoint_id, "name")
+end
+
+def next_intent_path(root, workflow)
+  workflow.dig("resume_rules", "continue_keyword", "next_intent_path") || ".planning/.next-intent"
+end
+
+def write_next_intent(root, workflow)
+  path = File.join(root, next_intent_path(root, workflow))
+  DevflowControlIO.atomic_write(path, '{"action":"continue"}')
+  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)
+  track = active_track(state)
+  return false unless track
+
+  (pending_ids & track_allowed_steps(track)).empty? && pending_ids.any?
+end
+
+def fail_result(reason, details = {})
+  { "ok" => false, "reason" => reason, "details" => details }
+end
+
+project_lock = DevflowControlIO.acquire_project_lock(root) if options[:write]
+
+begin
+result =
+  if !File.exist?(state_path)
+    fail_result("missing_state_file", "path" => state_path)
+  else
+    original_doc = File.read(state_path)
+    yaml = front_matter(original_doc)
+    if yaml.nil?
+      fail_result("missing_state_front_matter", "path" => state_path)
+    else
+      state = YAML.safe_load(yaml, permitted_classes: [], aliases: false)
+      workflow_path, workflow = load_workflow(root, state)
+      artifact_by_path = load_artifact_registry(root, workflow)
+      steps = workflow.fetch("steps", [])
+      step_by_id = steps.to_h { |step| [step.fetch("id"), step] }
+      changed = false
+      next_intent_written = nil
+      actions = []
+      action_description = nil
+      next_intent_requested = false
+      current_revision = Integer(state.fetch("revision", 0))
+
+      if !options[:expected_revision].nil? && current_revision != options[:expected_revision]
+        result = fail_result(
+          "stale_revision",
+          "expected_revision" => options[:expected_revision],
+          "actual_revision" => current_revision
+        )
+      end
+
+      if result.nil? && options[:checkpoint_decision]
+        state["checkpoint_decision"] = options[:checkpoint_decision]
+        changed = true
+        actions << "checkpoint_decision_set"
+        action_description = "Checkpoint decision set to: #{options[:checkpoint_decision]}"
+      end
+
+      if result.nil? && options[:complete_step]
+        step_id = options[:complete_step]
+        step = step_by_id[step_id]
+        if step.nil?
+          result = fail_result("unknown_step", "step" => step_id)
+        else
+          completed = Array(state["completed_steps"])
+          pending = Array(state["pending_steps"])
+          completed << step_id unless completed.include?(step_id)
+          pending = pending.reject { |id| id == step_id }
+
+          state["completed_steps"] = completed
+          state["pending_steps"] = pending
+          state["last_completed_step"] = step_id
+          state.delete("checkpoint_decision")
+
+          if step["checkpoint"]
+            state["current_step"] = step_id
+            state["status"] = "waiting_checkpoint"
+            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 track_boundary?(state, pending)
+            state["current_step"] = step_id
+            state["status"] = "blocked"
+            state["block_reason"] = "track_scope_complete"
+            state.delete("checkpoint")
+            state.delete("checkpoint_label")
+            action_description = "Step completed: #{step["label"]} (#{step_id}). Active track output scope is complete."
+          elsif (next_id = next_pending_step_id(state, pending, step_by_id, completed))
+            state["current_step"] = next_id
+            state["status"] = "in_progress"
+            state.delete("checkpoint")
+            state.delete("checkpoint_label")
+            next_step = step_by_id[next_id]
+            action_description = "Step completed: #{step["label"]} (#{step_id}). Advanced to #{next_step ? next_step["label"] : next_id}."
+          else
+            state["current_step"] = step_id
+            state["status"] = "completed"
+            state.delete("checkpoint")
+            state.delete("checkpoint_label")
+            action_description = "Step completed: #{step["label"]} (#{step_id}). All steps complete."
+          end
+
+          changed = true
+          actions << "step_completed"
+        end
+      end
+
+      if result.nil? && options[:confirm_checkpoint]
+        if state["status"] != "waiting_checkpoint"
+          result = fail_result("not_waiting_checkpoint", "status" => state["status"])
+        elsif Array(state["pending_steps"]).empty?
+          result = fail_result("no_pending_step")
+        else
+          pending = Array(state["pending_steps"])
+          completed = Array(state["completed_steps"])
+          next_id = next_pending_step_id(state, pending, step_by_id, completed)
+          if next_id.nil? && track_boundary?(state, pending)
+            state["checkpoint_decision"] = "approved"
+            state["status"] = "blocked"
+            state["block_reason"] = "track_scope_complete"
+            state.delete("checkpoint")
+            state.delete("checkpoint_label")
+            changed = true
+            actions << "checkpoint_confirmed_track_complete"
+            action_description = "Checkpoint confirmed. Active track output scope is complete."
+            next_intent_requested = true
+          else
+            state["checkpoint_decision"] = "approved"
+            state["current_step"] = next_id || pending.first
+            state["status"] = "in_progress"
+            state.delete("checkpoint")
+            state.delete("checkpoint_label")
+            changed = true
+            actions << "checkpoint_confirmed"
+            action_description = "Checkpoint confirmed. Advanced to next step."
+            next_intent_requested = true
+          end
+        end
+      end
+
+      if result.nil? && options[:enter_failure_branch]
+        current_step = step_by_id[state["current_step"]]
+        branch = current_step && workflow.fetch("failure_branches", {})[current_step["id"]]
+        if branch.nil?
+          result = fail_result("missing_failure_branch", "current_step" => state["current_step"])
+        else
+          branch_path = branch.fetch("workflow_config")
+          branch_workflow = load_yaml_file(File.join(root, branch_path))
+          transition = branch_workflow.dig("state_contract", "suggested_transition") || {}
+          state["source_flow"] = state["current_flow"]
+          state["source_workflow_config"] = workflow_path
+          state["current_flow"] = transition["current_flow"] || branch.fetch("workflow")
+          state["workflow_config"] = branch_path
+          state["current_step"] = transition["current_step"] || branch_workflow.dig("entry", "initial_step")
+          state["status"] = transition["status"] || "in_progress"
+          state["completed_steps"] = Array(transition["completed_steps"])
+          state["pending_steps"] = Array(transition["pending_steps"])
+          state.delete("checkpoint")
+          state.delete("checkpoint_label")
+          changed = true
+          actions << "failure_branch_entered"
+          action_description = "Entered failure branch: #{branch["label"] || branch.fetch("workflow")}."
+        end
+      end
+
+      if result.nil?
+        if changed
+          state["state_updated_at"] = Date.today.to_s
+          state["revision"] = current_revision + 1
+        end
+        validation = WorkflowStateValidator.validate(
+          root: root,
+          state_path: state_path,
+          state_override: state,
+          strict_artifact_status: false,
+          strict_registry_revision: false
+        )
+
+        if changed && !validation["ok"]
+          result = fail_result("state_validation_failed", "validation" => validation)
+        elsif changed && options[:write]
+          sync_artifact_registry(root, workflow, state)
+          artifact_by_path = load_artifact_registry(root, workflow)
+          write_state_file(root, state_path, state, workflow, artifact_by_path, action_description)
+          next_intent_written = write_next_intent(root, workflow) if next_intent_requested
+        end
+
+        result ||= {
+          "ok" => true,
+          "written" => changed && options[:write],
+          "actions" => actions,
+          "state_path" => state_path,
+          "next_intent_written" => next_intent_written,
+          "state_validation" => validation,
+          "state" => state
+        }
+      end
+      result
+    end
+  end
+ensure
+  DevflowControlIO.release_lock(project_lock)
+end
+
+if options[:json]
+  puts JSON.pretty_generate(result)
+else
+  puts JSON.pretty_generate(result)
+end

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

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+require "securerandom"
+
+# Shared durability primitives for every writer in the Devflow control plane.
+# The project lock serializes state, workflow, registry, and next-intent updates;
+# atomic rename prevents readers from observing partially written documents.
+module DevflowControlIO
+  module_function
+
+  def acquire_project_lock(root)
+    planning_dir = File.join(root, ".planning")
+    FileUtils.mkdir_p(planning_dir)
+    handle = File.open(File.join(planning_dir, ".devflow.lock"), File::RDWR | File::CREAT, 0o644)
+    handle.flock(File::LOCK_EX)
+    handle
+  end
+
+  def release_lock(handle)
+    return unless handle
+
+    handle.flock(File::LOCK_UN)
+    handle.close
+  end
+
+  def atomic_write(path, content)
+    directory = File.dirname(path)
+    FileUtils.mkdir_p(directory)
+    temporary = File.join(directory, ".#{File.basename(path)}.#{Process.pid}.#{SecureRandom.hex(6)}.tmp")
+
+    File.open(temporary, File::WRONLY | File::CREAT | File::EXCL, 0o644) do |file|
+      file.write(content)
+      file.flush
+      file.fsync
+    end
+    File.rename(temporary, path)
+  ensure
+    File.delete(temporary) if temporary && File.exist?(temporary)
+  end
+end