@guanlin4924/devflow-pi 0.1.85 → 0.1.88

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

@@ -11,6 +11,15 @@ module CheckerRegistry
     business-cross-model-check business-invalidation-check
   ].freeze
   EMBEDDED = %w[requirement-coverage-check source-authority-check traceability-check].freeze
+  GRAPH_BACKED = %w[
+    requirement-graph-check slice-independence-check contract-coverage-check
+    change-impact-check acceptance-coverage-check test-coverage-check test-obligation-check
+  ].freeze
+  ADAPTERS = %w[
+    api-test-schema-check api-test-matrix-check acceptance-test-results-check
+    test-task-binding-check tdd-evidence-check cross-track-consistency-check
+    business-cross-model-check business-claim-reference-check
+  ].freeze
 
   module_function
 
@@ -24,6 +33,16 @@ module CheckerRegistry
     nil
   end
 
+  def executable?(id)
+    GRAPH_BACKED.include?(id.to_s) || ADAPTERS.include?(id.to_s)
+  end
+
+  def validate_executable!(ids)
+    unsupported = Array(ids).map(&:to_s).reject { |id| executable?(id) }
+    raise ArgumentError, "checker has no Core execution adapter: #{unsupported.join(', ')}" unless unsupported.empty?
+    true
+  end
+
   def validate!(ids)
     unknown = Array(ids).map(&:to_s).reject { |id| known?(id) }
     raise ArgumentError, "unknown checker id(s): #{unknown.join(", ")}" unless unknown.empty?

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

@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+
+module CheckpointMeta
+  module_function
+
+  def validate(root:, state:, checkpoint:)
+    return [] unless checkpoint.is_a?(Hash)
+
+    raw_path = checkpoint["required_meta_output"]
+    # Legacy/custom checkpoints may not declare checkpoint metadata. Only
+    # enforce the contract when a metadata path is explicitly declared.
+    return [] if raw_path.to_s.empty?
+
+    relative = raw_path.to_s
+                   .gsub("{feature}", state.fetch("current_feature", "").to_s)
+                   .gsub("{phase}", state.fetch("current_phase", "").to_s)
+    absolute = File.expand_path(relative, root)
+    unless File.file?(absolute)
+      return [{ "code" => "missing_checkpoint_meta_output", "message" => "checkpoint meta output is missing", "path" => relative }]
+    end
+
+    data = JSON.parse(File.read(absolute))
+    errors = []
+    unless data.is_a?(Hash)
+      errors << { "code" => "invalid_checkpoint_meta_shape", "message" => "checkpoint meta output must be a JSON object", "path" => relative }
+      return errors
+    end
+
+    Array(checkpoint["required_meta_fields"]).each do |field|
+      next if data.key?(field.to_s) && !data[field.to_s].nil?
+
+      errors << {
+        "code" => "missing_checkpoint_meta_field",
+        "message" => "checkpoint meta output is missing a required field",
+        "path" => relative,
+        "field" => field
+      }
+    end
+    errors
+  rescue JSON::ParserError => error
+    [{ "code" => "invalid_checkpoint_meta_json", "message" => error.message, "path" => relative }]
+  end
+end

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

@@ -9,6 +9,7 @@ require "optparse"
 require "yaml"
 require_relative "control_io"
 require_relative "requirement_graph"
+require_relative "checker_registry"
 
 POLICY = {
   "domain-modeling" => { "checkers" => %w[requirement-graph-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[term object behavior rule boundary] },
@@ -26,6 +27,7 @@ POLICY = {
   "change-plan" => { "checkers" => %w[requirement-graph-check slice-independence-check contract-coverage-check api-test-matrix-check test-coverage-check test-obligation-check test-task-binding-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[acceptance] },
   "execute" => { "checkers" => %w[tdd-evidence-check change-impact-check], "agents" => ["implementation-worker"], "budget" => 1, "allowed_graph_delta" => %w[requirement rule boundary behavior] },
   "run-acceptance-tests" => { "checkers" => %w[api-test-matrix-check test-coverage-check acceptance-test-results-check change-impact-check], "agents" => ["verification-runner"], "budget" => 1, "allowed_graph_delta" => [] },
+  "code-review" => { "checkers" => %w[], "agents" => ["devflow-code-reviewer"], "budget" => 3, "allowed_graph_delta" => [] },
   "verify" => { "checkers" => %w[acceptance-coverage-check acceptance-test-results-check change-impact-check], "agents" => ["verification-runner"], "budget" => 1, "allowed_graph_delta" => %w[acceptance] }
 }.freeze
 
@@ -91,12 +93,19 @@ begin
     raise ArgumentError, "stale graph revision: expected #{options[:expected_graph_revision]}, actual #{graph["revision"]}" if options[:expected_graph_revision] && graph["revision"] != options[:expected_graph_revision]
   end
   policy = POLICY.fetch(options[:step], { "checkers" => [], "agents" => [], "budget" => 0 })
+  # The active workflow is the source of truth for gate checkers.  POLICY
+  # retains execution permissions and budgets, but must not maintain a second
+  # checker list that can drift from workflow governance.
+  workflow_checkers = workflow.dig("governance", "step_checkers", options[:step])
+  checker_ids = workflow_checkers.nil? ? Array(policy["checkers"]) : Array(workflow_checkers).map(&:to_s)
+  CheckerRegistry.validate!(checker_ids)
+  CheckerRegistry.validate_executable!(checker_ids)
   paths = (Array(step["outputs"]).map { |output| output["path"] } + [step.dig("meta_output", "path")]).compact.map { |value| interpolate(value, state) }.uniq
   contract = {
     "schema_version" => 2, "origin" => "core_execution_contract", "feature" => options[:feature], "step" => options[:step],
     "state_revision" => state["revision"], "graph_revision" => graph["revision"], "workflow_path" => workflow_relative,
     "workflow_fingerprint" => Digest::SHA256.hexdigest(workflow_raw), "manifest_id" => "devflow-core-execution-policy-v2",
-    "allowed_paths" => paths, "allowed_agents" => policy["agents"], "checker_ids" => policy["checkers"],
+    "allowed_paths" => paths, "allowed_agents" => policy["agents"], "checker_ids" => checker_ids,
     # Core read/write tools required by the architecture feasibility skill are
     # part of the frozen contract.  The tool layer still applies per-tool
     # mutation ownership and the step's allowed paths.

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

@@ -2,12 +2,14 @@
 # frozen_string_literal: true
 
 require "json"
+require "open3"
 require_relative "gate_result"
 require_relative "gate_contract"
 require_relative "checker_registry"
 require_relative "parallel_run"
 require_relative "business_model_gate"
 require_relative "requirement_graph"
+require_relative "checkpoint_meta"
 
 module GateRuntime
   KNOWN_VALIDATIONS = %w[static-runtime-context requirement-graph].freeze
@@ -69,8 +71,32 @@ module GateRuntime
           missing_outputs = required_paths(contract.dig("outputs", "required"), root, workflow_state)
           missing_outputs.concat(required_paths(contract.dig("outputs", "required_inputs"), root, workflow_state, purpose: :completion))
           return GateResult.block(**base, code: "REQUIRED_OUTPUT_MISSING", message: "required step output is missing", details: { "missing" => missing_outputs }) unless missing_outputs.empty?
+          checkpoint = contract.dig("topology", "checkpoint")
+          if checkpoint.is_a?(Hash) && checkpoint["producing_step"].to_s == step_id.to_s
+            meta_errors = CheckpointMeta.validate(root: root, state: workflow_state, checkpoint: checkpoint)
+            unless meta_errors.empty?
+              return GateResult.block(**base, code: "CHECKPOINT_META_INVALID", message: "checkpoint meta output is missing or invalid", details: { "checkpoint" => checkpoint["id"], "errors" => meta_errors })
+            end
+          end
           invalid_outputs = validate_declared_inputs(contract.dig("outputs", "required_inputs"), root, workflow_state, purpose: :completion)
           return GateResult.block(**base, code: "REQUIRED_OUTPUT_INVALID", message: "required step input/output fact is invalid", details: { "invalid" => invalid_outputs }) unless invalid_outputs.empty?
+          if step_id == "code-review"
+            contract_view = File.join(root, ".planning/execution-contract.md")
+            contract_id = if File.file?(contract_view) && !File.symlink?(contract_view)
+                            File.read(contract_view).match(/^- Contract ID: `(EC-[0-9a-f]{16})`$/)&.[](1)
+                          end
+            unless contract_id
+              return GateResult.block(**base, code: "REVIEW_GATE_NOT_PASSED", message: "current Core review contract identity is unavailable")
+            end
+            script = File.join(__dir__, "review_run.py")
+            stdout, stderr, process = Open3.capture3("python3", script, File.realpath(root), "--gate", workflow_state.fetch("current_feature").to_s, contract_id)
+            review = JSON.parse(stdout) rescue nil
+            unless process.success? && review.is_a?(Hash) && review["status"] == "pass"
+              return GateResult.block(**base, code: "REVIEW_GATE_NOT_PASSED", message: "independent Core review has not passed", details: {
+                "review" => review, "error" => stderr.to_s.empty? ? nil : stderr.to_s[0, 1000]
+              })
+            end
+          end
         end
       end
     end
@@ -84,6 +110,12 @@ module GateRuntime
       unless workflow_state["completed_steps"].to_a.include?(checkpoint["producing_step"].to_s)
         return GateResult.block(**base, code: "CHECKPOINT_PRODUCER_INCOMPLETE", message: "checkpoint producing step is not completed", details: { "checkpoint" => checkpoint_id })
       end
+      if root
+        meta_errors = CheckpointMeta.validate(root: root, state: workflow_state, checkpoint: checkpoint)
+        unless meta_errors.empty?
+          return GateResult.block(**base, code: "CHECKPOINT_META_INVALID", message: "checkpoint meta output is missing or invalid", details: { "checkpoint" => checkpoint_id, "errors" => meta_errors })
+        end
+      end
     end
     GateResult.allow(**base)
   rescue KeyError, ArgumentError => e

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

@@ -60,47 +60,50 @@ unless PhaseOwnership.valid_slug?(phase)
 end
 workflow_config = ".planning/workflows/#{options[:flow]}.yaml"
 workflow_path = File.expand_path(workflow_config, root)
-fallback_pending_steps = [
-  "requirement-triage",
-  "requirement-wayfinder",
-  "domain-modeling",
-  "requirement-feasibility-review",
-  "requirement-baseline",
-  "api-contract",
-  "backend-tech-spec",
-  "api-call-guide",
-  "ui-spec",
-  "feature-breakdown",
-  "frontend-tech-spec",
-  "api-supplement",
-  "integration-verify",
-  "change-plan",
-  "phase-structure",
-  "execute",
-  "code-index-refresh",
-  "code-review",
-  "generate-mainflow-cases",
-  "verify",
-  "audit",
-  "update-navigation",
-  "archive"
-]
-pending_steps = if File.exist?(workflow_path)
-                  workflow = YAML.safe_load(File.read(workflow_path), permitted_classes: [], aliases: false)
-                  # The template is authored in readable sections, so physical
-                  # YAML position is not a scheduling contract. A step with an
-                  # explicit order must initialize ahead of later ordered
-                  # steps even when it was inserted lower in the document.
-                  Array(workflow["steps"])
-                    .each_with_index
-                    .sort_by do |(step, index)|
-                      order = step["order"]
-                      [order.is_a?(Integer) ? 0 : 1, order.is_a?(Integer) ? order : index, index]
-                    end
-                    .map { |(step, _index)| step.fetch("id") }
-                else
-                  fallback_pending_steps
-                end
+unless options[:flow].is_a?(String) && options[:flow].match?(/\A[A-Za-z0-9][A-Za-z0-9_-]*\z/)
+  puts JSON.pretty_generate({
+    "ok" => false,
+    "reason" => "invalid_flow",
+    "message" => "flow must be a safe workflow id"
+  })
+  exit 0
+end
+unless File.file?(workflow_path)
+  puts JSON.pretty_generate({
+    "ok" => false,
+    "reason" => "workflow_not_found",
+    "message" => "Workflow configuration does not exist: #{workflow_config}. Run init_workflow.rb first or choose a registered flow."
+  })
+  exit 0
+end
+
+begin
+  workflow = YAML.safe_load(File.read(workflow_path), permitted_classes: [], aliases: false)
+  steps = workflow.is_a?(Hash) ? workflow["steps"] : nil
+  unless steps.is_a?(Array) && steps.any? && steps.all? { |step| step.is_a?(Hash) && step["id"].is_a?(String) && !step["id"].empty? }
+    raise ArgumentError, "workflow steps must be a non-empty list with string ids"
+  end
+  step_ids = steps.map { |step| step["id"] }
+  raise ArgumentError, "workflow step ids must be unique" unless step_ids.uniq.length == step_ids.length
+rescue Psych::Exception, ArgumentError => error
+  puts JSON.pretty_generate({
+    "ok" => false,
+    "reason" => "invalid_workflow",
+    "message" => "Invalid workflow configuration #{workflow_config}: #{error.message}"
+  })
+  exit 0
+end
+
+# The template is authored in readable sections, so physical YAML position is
+# not a scheduling contract. A step with an explicit order must initialize
+# ahead of later ordered steps even when it was inserted lower in the document.
+pending_steps = steps
+  .each_with_index
+  .sort_by do |(step, index)|
+    order = step["order"]
+    [order.is_a?(Integer) ? 0 : 1, order.is_a?(Integer) ? order : index, index]
+  end
+  .map { |(step, _index)| step.fetch("id") }
 current_step = options[:step] || pending_steps.first || "requirement-triage"
 
 state = {

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

@@ -81,7 +81,7 @@ changes = targets.map do |template_name, target_path|
   same_as_template = exists && File.read(target) == File.read(source)
   state_mismatch = blocked_target_paths.include?(target_path)
   action = if exists && !options[:force]
-             same_as_template ? "skip_existing" : "skip_existing_changed"
+             same_as_template ? "skip_existing" : "blocked_template_drift"
            elsif state_mismatch && !options[:allow_state_mismatch]
              "blocked_state_mismatch"
            elsif blocked_target_paths.any?
@@ -104,14 +104,15 @@ changes = targets.map do |template_name, target_path|
   }
 end
 
-blocked = changes.any? { |change| change["action"] == "blocked_state_mismatch" }
+blocked = changes.any? { |change| %w[blocked_state_mismatch blocked_template_drift].include?(change["action"]) }
+template_drift = changes.any? { |change| change["action"] == "blocked_template_drift" }
 result = {
   "ok" => !blocked,
   "written" => options[:write] && !blocked,
   "force" => options[:force],
   "allow_state_mismatch" => options[:allow_state_mismatch],
-  "upgrade_hint" => changes.any? { |change| change["action"] == "skip_existing_changed" } ? "Existing generated workflow differs from the bundled template. Use --force only when intentionally upgrading generated workflow files." : nil,
-  "blocked_reason" => blocked ? "active_state_step_mismatch" : nil,
+  "upgrade_hint" => template_drift ? "Existing generated workflow differs from the bundled template. Review the diff, then rerun with --force to intentionally upgrade generated workflow files." : nil,
+  "blocked_reason" => template_drift ? "template_drift" : (blocked ? "active_state_step_mismatch" : nil),
   "changes" => changes
 }.reject { |_, value| value.nil? }
 ensure

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

@@ -5,6 +5,7 @@ require "json"
 require "optparse"
 require "yaml"
 require_relative "validate_state"
+require_relative "checkpoint_meta"
 
 options = { json: false, state: nil }
 OptionParser.new do |opts|
@@ -34,11 +35,19 @@ def load_yaml_file(path)
 end
 
 def interpolate_path(path, state)
-  path
+  path.to_s
     .gsub("{feature}", state.fetch("current_feature", "").to_s)
     .gsub("{phase}", state.fetch("current_phase", "").to_s)
 end
 
+def input_payload(input, state)
+  if input.is_a?(Hash)
+    input.merge("path" => interpolate_path(input.fetch("path"), state))
+  else
+    interpolate_path(input, state)
+  end
+end
+
 def load_artifact_registry(root, workflow)
   registry_config = workflow["artifact_registry"]
   registry_path = registry_config && registry_config["source"]
@@ -121,7 +130,7 @@ def step_payload(step, state, root, artifact_by_path)
     "label" => step["label"],
     "skill" => step["skill"],
     "action" => step["action"],
-    "inputs" => Array(step["inputs"]).map { |path| interpolate_path(path, state) },
+    "inputs" => Array(step["inputs"]).map { |input| input_payload(input, state) },
     "outputs" => Array(step["outputs"]).map { |output| output_payload(output, state, root, artifact_by_path) }
   }
 end
@@ -575,7 +584,7 @@ result =
                 label: next_step["label"],
                 skill: next_step["skill"],
                 action: next_step["action"],
-                inputs: Array(next_step["inputs"]).map { |path| interpolate_path(path, state) },
+                inputs: Array(next_step["inputs"]).map { |input| input_payload(input, state) },
                 outputs: Array(next_step["outputs"]).map do |output|
                   resolved = interpolate_path(output.fetch("path"), state)
                   artifact = artifact_by_path[resolved]
@@ -624,11 +633,13 @@ result =
               missing_outputs = current_outputs
                                 .select { |output| output["required"] && !output["exists"] }
                                 .map { |output| output["resolved_path"] }
-
+              checkpoint_meta_errors = CheckpointMeta.validate(root: root, state: state, checkpoint: checkpoint)
+              missing_outputs.concat(checkpoint_meta_errors.map { |entry| entry["path"] }.compact)
               base.merge(
                 action: missing_outputs.empty? ? "await_user_confirmation" : "blocked",
                 reason: missing_outputs.empty? ? nil : "missing_checkpoint_outputs",
                 missing_outputs: missing_outputs,
+                checkpoint_meta_errors: checkpoint_meta_errors,
                 resume_behavior: checkpoint && checkpoint["resume_behavior"],
                 next_intent: ".planning/.next-intent"
               )

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

@@ -11,6 +11,8 @@ require "yaml"
 require_relative "control_io"
 require_relative "requirement_graph"
 require_relative "checker_registry"
+require_relative "checker_adapter"
+require_relative "checkpoint_meta"
 
 options = { feature: nil, step: nil, contract: nil, write: false, json: false, branch_id: nil, attempt: nil, branch_revision: nil, lock_held: false }
 OptionParser.new do |o|
@@ -199,6 +201,11 @@ begin
 
   output_specs = Array(step["outputs"]).select { |item| item["required"] }
   output_specs << step["meta_output"] if step["meta_output"].is_a?(Hash)
+  checkpoint = workflow.dig("checkpoints", step["checkpoint"])
+  checkpoint_meta_errors = CheckpointMeta.validate(root: root, state: state, checkpoint: checkpoint)
+  if checkpoint.is_a?(Hash) && checkpoint["required_meta_output"]
+    output_specs << { "path" => checkpoint["required_meta_output"], "required" => true }
+  end
   files = output_specs.map do |spec|
     path = spec["path"]
     next unless path
@@ -208,21 +215,20 @@ begin
     { "path" => relative, "required" => true, "exists" => exists, "bytes" => exists ? File.size(absolute) : 0,
       "sha256" => exists ? Digest::SHA256.file(absolute).hexdigest : nil }
   end.compact
-  input_files = Array(step["inputs"]).map { |input| file_evidence(root, interpolate(input.to_s, state)) }
+  input_files = Array(step["inputs"]).map do |input|
+    raw_path = input.is_a?(Hash) ? input.fetch("path") : input
+    file_evidence(root, interpolate(raw_path.to_s, state))
+  end
 
   graph, = RequirementGraph.load_graph(root, options[:feature])
   checkers = RequirementGraph.checker_results(graph)
   selected = configured_checkers(workflow, options[:step])
   CheckerRegistry.validate!(selected)
+  CheckerRegistry.validate_executable!(selected)
   gate = workflow.dig("governance", "requirement_graph_gate").to_s
   enforced = gate == "enforced"
   checker_results = selected.map do |id|
-    supplemental = supplemental_checker(root, options[:feature], id, options[:step])
-    next supplemental if supplemental
-
-    issues = checkers.fetch(id, ["unknown fixed checker: #{id}"])
-    { "id" => id, "origin" => "core_fixed_checker", "exit_code" => issues.empty? ? 0 : 1, "passed" => issues.empty?, "issues" => issues,
-      "counters" => { "issue_count" => issues.length } }
+    CheckerAdapter.execute(root: root, feature: options[:feature], step: options[:step], id: id, graph_results: checkers)
   end
   graph_missing = graph["revision"].zero? && !File.exist?(RequirementGraph.graph_path(root, options[:feature]).first)
   checker_passed = !enforced || (!graph_missing && checker_results.all? { |item| item["passed"] })
@@ -248,14 +254,14 @@ begin
     "counters" => { "required_file_count" => files.length, "existing_file_count" => files.count { |item| item["exists"] }, "nodes_by_kind" => node_counts,
                     "stale_node_count" => Array(graph["stale"]).length, "stale_view_count" => Hash(graph["views"]).count { |_name, view| view["needs_recheck"] } },
     "view_fingerprints" => Hash(graph["views"]).transform_values { |view| view.select { |key, _value| %w[fingerprint graph_revision state needs_recheck stale_fingerprint].include?(key) } },
-    "complete" => files.all? { |item| item["exists"] } && checker_passed && evidence_complete,
+    "complete" => files.all? { |item| item["exists"] } && checkpoint_meta_errors.empty? && checker_passed && evidence_complete,
     "evidence_complete" => evidence_complete,
     "gate_mode" => gate.empty? ? "observe" : gate
   }.compact
   suffix = binding ? ".attempt-#{binding["attempt"]}.branch-#{Digest::SHA256.hexdigest(binding["branch_id"].to_s)[0, 12]}" : ""
   destination = File.join(root, ".planning/evidence", options[:feature], "#{options[:step]}#{suffix}.machine.json")
   DevflowControlIO.atomic_write(destination, JSON.pretty_generate(pack) + "\n")
-  result = { "ok" => true, "path" => destination.sub("#{root}/", ""), "complete" => pack["complete"], "state_revision" => pack["state_revision"], "graph_revision" => pack["graph_revision"], "checkers" => checker_results, "parallel_binding" => binding }
+  result = { "ok" => true, "path" => destination.sub("#{root}/", ""), "complete" => pack["complete"], "state_revision" => pack["state_revision"], "graph_revision" => pack["graph_revision"], "checkers" => checker_results, "checkpoint_meta_errors" => checkpoint_meta_errors, "parallel_binding" => binding }
 rescue StandardError => error
   result = { "ok" => false, "reason" => "machine_evidence_failed", "message" => error.message }
 ensure