@guanlin4924/devflow-pi 0.1.0

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

@@ -0,0 +1,219 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "date"
+require "fileutils"
+require "json"
+require "optparse"
+require "yaml"
+
+options = {
+  state: nil,
+  select: false,
+  write_template: false,
+  title: nil,
+  source: nil,
+  next_step: nil,
+  write: false,
+  json: false
+}
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: manage_lessons.rb [--select] [--write-template --title TITLE] [options]"
+  opts.on("--state PATH", "Read an alternate STATE.md file") { |path| options[:state] = path }
+  opts.on("--select", "Select relevant lessons from configured indexes") { options[:select] = true }
+  opts.on("--next-step STEP", "Target step ID for lesson matching") { |step| options[:next_step] = step }
+  opts.on("--write-template", "Create a new lesson template") { options[:write_template] = true }
+  opts.on("--title TITLE", "Lesson title for template creation") { |title| options[:title] = title }
+  opts.on("--source PATH", "Evidence/source artifact path") { |path| options[:source] = path }
+  opts.on("--write", "Persist template/index changes. Without this flag, preview only.") { options[:write] = true }
+  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 load_state(path)
+  doc = File.read(path)
+  yaml = front_matter(doc)
+  raise "missing state front matter: #{path}" if yaml.nil?
+
+  YAML.safe_load(yaml, permitted_classes: [], aliases: false)
+end
+
+def workflow_path_for(state)
+  state["workflow_config"] || File.join(".planning", "workflows", "#{state.fetch("current_flow")}.yaml")
+end
+
+def configured_policy(workflow)
+  workflow["lessons_policy"] || {
+    "sources" => [
+      { "path" => ".context/lessons/README.md", "required" => false },
+      { "path" => ".planning/lessons/README.md", "required" => false }
+    ],
+    "selection" => { "max_candidates" => 5, "min_score" => 1 },
+    "write" => {
+      "default_dir" => ".context/lessons",
+      "index_path" => ".context/lessons/README.md"
+    }
+  }
+end
+
+def words(text)
+  text.to_s.downcase.scan(/[[:alnum:]_\-\p{Han}]{2,}/)
+end
+
+def parse_lesson_index(root, source)
+  path = source.fetch("path")
+  abs = File.join(root, path)
+  return { "path" => path, "exists" => false, "lessons" => [] } unless File.exist?(abs)
+
+  lessons = []
+  File.readlines(abs, chomp: true).each do |line|
+    line.scan(/\[([^\]]+)\]\(([^)]+)\)/).each do |title, href|
+      lessons << {
+        "title" => title,
+        "path" => href.start_with?(".") ? href : File.join(File.dirname(path), href),
+        "source_index" => path
+      }
+    end
+    if line.start_with?("#")
+      title = line.sub(/\A#+\s*/, "").strip
+      lessons << { "title" => title, "path" => path, "source_index" => path } unless title.empty?
+    end
+  end
+
+  { "path" => path, "exists" => true, "lessons" => lessons.uniq }
+end
+
+def selection_terms(state, workflow, source_path, next_step)
+  steps = Array(workflow["steps"])
+  step = steps.find { |item| item["id"] == (next_step || state["current_step"]) } || {}
+  terms = []
+  terms.concat(words(state["current_flow"]))
+  terms.concat(words(next_step || state["current_step"]))
+  terms.concat(words(state["status"]))
+  terms.concat(words(state["checkpoint"]))
+  terms.concat(words(state["checkpoint_decision"]))
+  terms.concat(words(step["label"]))
+  terms.concat(words(step["skill"]))
+  terms.concat(words(step["action"]))
+  terms.concat(words(source_path))
+  terms.uniq
+end
+
+def select_lessons(root, policy, state, workflow, source_path, next_step)
+  terms = selection_terms(state, workflow, source_path, next_step)
+  indexes = Array(policy["sources"]).map { |source| parse_lesson_index(root, source) }
+  min_score = policy.dig("selection", "min_score") || 1
+  max_candidates = policy.dig("selection", "max_candidates") || 5
+
+  candidates = indexes.flat_map { |index| index["lessons"] }.map do |lesson|
+    text = "#{lesson["title"]} #{lesson["path"]}".downcase
+    matched = terms.select { |term| text.include?(term) }
+    lesson.merge("score" => matched.length, "matched_terms" => matched)
+  end
+  candidates = candidates.select { |candidate| candidate["score"] >= min_score }
+                         .sort_by { |candidate| [-candidate["score"], candidate["title"]] }
+                         .first(max_candidates)
+
+  {
+    "terms" => terms,
+    "indexes" => indexes.map { |index| index.reject { |key, _| key == "lessons" } },
+    "candidates" => candidates
+  }
+end
+
+def slug_for(title)
+  slug = title.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-|-+\z/, "")
+  slug.empty? ? "lesson" : slug
+end
+
+def build_template(title, state, source)
+  <<~MD
+    # #{title}
+
+    - Date: #{Date.today}
+    - Workflow: #{state["current_flow"]}
+    - Step: #{state["current_step"]}
+    - Source: #{source || "TODO"}
+
+    ## Symptom
+
+    TODO
+
+    ## Root Cause
+
+    TODO
+
+    ## Fix
+
+    TODO
+
+    ## Prevention
+
+    TODO
+  MD
+end
+
+def write_template(root, policy, state, title, source, write)
+  write_config = policy["write"] || {}
+  dir = write_config["default_dir"] || ".context/lessons"
+  index_path = write_config["index_path"] || File.join(dir, "README.md")
+  file_name = "#{Date.today}-#{slug_for(title)}.md"
+  rel_path = File.join(dir, file_name)
+  abs_path = File.join(root, rel_path)
+  abs_index = File.join(root, index_path)
+  template = build_template(title, state, source)
+  index_entry = "- [#{title}](#{file_name})"
+
+  if write
+    FileUtils.mkdir_p(File.dirname(abs_path))
+    File.write(abs_path, template)
+    unless File.exist?(abs_index)
+      FileUtils.mkdir_p(File.dirname(abs_index))
+      File.write(abs_index, "# Lessons\n\n")
+    end
+    index = File.read(abs_index)
+    File.write(abs_index, "#{index.chomp}\n#{index_entry}\n") unless index.include?(index_entry)
+  end
+
+  {
+    "path" => rel_path,
+    "index_path" => index_path,
+    "written" => write,
+    "template" => template
+  }
+end
+
+state = load_state(state_path)
+workflow_path = workflow_path_for(state)
+workflow = load_yaml_file(File.join(root, workflow_path))
+policy = configured_policy(workflow)
+
+result = {
+  "state_path" => state_path,
+  "workflow_config" => workflow_path,
+  "policy" => policy
+}
+
+if options[:select]
+  result["selection"] = select_lessons(root, policy, state, workflow, options[:source], options[:next_step])
+end
+
+if options[:write_template]
+  raise "--title is required with --write-template" if options[:title].to_s.strip.empty?
+
+  result["write_template"] = write_template(root, policy, state, options[:title], options[:source], options[:write])
+end
+
+puts JSON.pretty_generate(result)

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

@@ -0,0 +1,168 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "date"
+require "fileutils"
+require "json"
+require "optparse"
+require "yaml"
+require_relative "control_io"
+
+options = {
+  state: ".planning/STATE.md",
+  workflow: nil,
+  output: nil,
+  write: false,
+  preserve: true,
+  json: false
+}
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: sync_artifacts.rb [--write] [--state PATH] [--workflow PATH]"
+  opts.on("--state PATH", "STATE.md path") { |value| options[:state] = value }
+  opts.on("--workflow PATH", "Workflow YAML path") { |value| options[:workflow] = value }
+  opts.on("--output PATH", "Artifact registry path") { |value| options[:output] = value }
+  opts.on("--write", "Create/update artifact registry") { options[:write] = true }
+  opts.on("--no-preserve", "Do not preserve existing statuses") { options[:preserve] = false }
+  opts.on("--json", "Print JSON output") { options[:json] = true }
+end.parse!
+
+root = Dir.pwd
+
+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 load_state(path)
+  doc = File.read(path)
+  yaml = front_matter(doc)
+  raise "missing state front matter: #{path}" if yaml.nil?
+
+  YAML.safe_load(yaml, 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 collect_outputs(workflow)
+  Array(workflow["steps"]).flat_map do |step|
+    Array(step["outputs"]).map do |output|
+      [step, output]
+    end
+  end
+end
+
+project_lock = DevflowControlIO.acquire_project_lock(root) if options[:write]
+
+begin
+state = load_state(File.join(root, options[:state]))
+workflow_path = options[:workflow] || state["workflow_config"] || ".planning/workflows/#{state.fetch("current_flow")}.yaml"
+workflow = load_yaml_file(File.join(root, workflow_path))
+registry_path = options[:output] || workflow.dig("artifact_registry", "source") || ".planning/artifacts/index.yaml"
+existing_registry_path = File.join(root, registry_path)
+existing_by_path = {}
+if options[:preserve] && File.exist?(existing_registry_path)
+  existing = load_yaml_file(existing_registry_path)
+  existing_by_path = Array(existing["artifacts"]).to_h { |artifact| [artifact.fetch("path"), artifact] }
+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]
+
+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)
+    unless head.include?(required_header)
+      issues << "missing_required_header(#{required_header.inspect})"
+    end
+  end
+
+  { "valid" => issues.empty?, "issues" => issues }
+end
+
+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 options[:preserve] && 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"]
+  },
+  "status_values" => %w[planned generated approved completed passed pending_rerun stale failed],
+  "artifacts" => artifacts
+}
+
+if options[:write]
+  DevflowControlIO.atomic_write(existing_registry_path, registry.to_yaml.sub(/\A---\n/, ""))
+end
+
+result = {
+  "ok" => true,
+  "written" => options[:write],
+  "path" => registry_path,
+  "artifact_count" => artifacts.length,
+  "missing_count" => artifacts.count { |artifact| !artifact["exists"] },
+  "registry" => registry
+}
+ensure
+  DevflowControlIO.release_lock(project_lock)
+end
+
+puts JSON.pretty_generate(result)

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

@@ -0,0 +1,110 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "optparse"
+require "yaml"
+
+ROUTE_NEXT_SKILL = {
+  "ready_for_wayfinder" => "workflow-wayfinder",
+  "ready_for_baseline" => "workflow-requirement-baseline",
+  "needs_demand_clarify" => "workflow-demand-clarify",
+  "needs_wayfinder" => "workflow-wayfinder",
+  "needs_info" => "none",
+  "ready_for_human" => "none",
+  "already_done" => "none",
+  "wontfix" => "none"
+}.freeze
+
+ROUTE_STATUS = {
+  "ready_for_wayfinder" => "routed",
+  "ready_for_baseline" => "routed",
+  "needs_demand_clarify" => "routed",
+  "needs_wayfinder" => "routed",
+  "needs_info" => "blocked",
+  "ready_for_human" => "blocked",
+  "already_done" => "blocked",
+  "wontfix" => "blocked"
+}.freeze
+
+options = {
+  feature: nil,
+  route: nil,
+  reason: nil,
+  blocking_question: nil,
+  state: ".planning/STATE.md",
+  write: false,
+  json: false
+}
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: update_triage_route.rb --route ROUTE [--feature NAME] [--reason TEXT] [--write] [--json]"
+  opts.on("--feature NAME", "Feature name. Defaults to STATE.md current_feature") { |value| options[:feature] = value }
+  opts.on("--route ROUTE", "Triage route") { |value| options[:route] = value }
+  opts.on("--reason TEXT", "Route reason") { |value| options[:reason] = value }
+  opts.on("--blocking-question TEXT", "Blocking question when route requires user input") { |value| options[:blocking_question] = value }
+  opts.on("--state PATH", "STATE.md path") { |value| options[:state] = value }
+  opts.on("--write", "Persist meta update") { options[:write] = true }
+  opts.on("--json", "Print JSON output") { options[:json] = true }
+end.parse!
+
+root = Dir.pwd
+
+def front_matter(markdown)
+  match = markdown.match(/\A---\n(.*?)\n---\n/m)
+  match && match[1]
+end
+
+def load_state(root, path)
+  abs = File.expand_path(path, root)
+  return {} unless File.exist?(abs)
+
+  yaml = front_matter(File.read(abs))
+  yaml ? YAML.safe_load(yaml, permitted_classes: [], aliases: false) : {}
+end
+
+def fail_result(reason, details = {})
+  { "ok" => false, "reason" => reason, "details" => details }
+end
+
+result = if !ROUTE_NEXT_SKILL.key?(options[:route].to_s)
+           fail_result("invalid_route", "route" => options[:route], "allowed_routes" => ROUTE_NEXT_SKILL.keys)
+         else
+           state = load_state(root, options[:state])
+           feature = options[:feature] || state["current_feature"]
+           if feature.to_s.empty?
+             fail_result("missing_feature", "message" => "Pass --feature or provide current_feature in STATE.md")
+           else
+             meta_path = File.join(root, ".planning", "requirements", feature, "入口分诊.meta.json")
+             meta = File.exist?(meta_path) ? JSON.parse(File.read(meta_path)) : { "feature_name" => feature }
+             route = options[:route]
+
+             meta["feature_name"] ||= feature
+             meta["status"] = ROUTE_STATUS.fetch(route)
+             meta["route"] = route
+             meta["route_reason"] = options[:reason] || meta["route_reason"] || ""
+             meta["blocking_question"] = options[:blocking_question] || meta["blocking_question"] || ""
+             meta["next_skill"] = ROUTE_NEXT_SKILL.fetch(route)
+             meta["request_type"] ||= "unknown"
+             meta["duplicate_count"] ||= 0
+             meta["prior_rejection_count"] ||= 0
+             meta["searched_sources"] ||= []
+             meta["related_code_paths"] ||= []
+             meta["related_history_paths"] ||= []
+
+             if options[:write]
+               FileUtils.mkdir_p(File.dirname(meta_path))
+               File.write(meta_path, JSON.pretty_generate(meta))
+             end
+
+             {
+               "ok" => true,
+               "written" => options[:write],
+               "path" => ".planning/requirements/#{feature}/入口分诊.meta.json",
+               "meta" => meta
+             }
+           end
+         end
+
+puts JSON.pretty_generate(result)