@guanlin4924/devflow-pi 0.1.38 → 0.1.40

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

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+module CheckerRegistry
+  DECLARED = %w[
+    requirement-graph-check slice-independence-check acceptance-coverage-check
+    api-test-schema-check contract-coverage-check api-test-matrix-check
+    test-coverage-check test-obligation-check acceptance-test-results-check
+    change-impact-check tdd-evidence-check test-task-binding-check
+    cross-track-consistency-check
+  ].freeze
+  EMBEDDED = %w[requirement-coverage-check source-authority-check traceability-check].freeze
+
+  module_function
+
+  def known?(id)
+    (DECLARED + EMBEDDED).include?(id.to_s)
+  end
+
+  def kind(id)
+    return "declared" if DECLARED.include?(id.to_s)
+    return "embedded" if EMBEDDED.include?(id.to_s)
+    nil
+  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?
+    true
+  end
+end

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

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "yaml"
+
+options = { feature: nil, json: false }
+OptionParser.new do |opts|
+  opts.on("--feature FEATURE") { |value| options[:feature] = value }
+  opts.on("--json") { options[:json] = true }
+end.parse!
+
+raise ArgumentError, "--feature is required" if options[:feature].to_s.empty?
+feature = options[:feature].to_s
+raise ArgumentError, "feature contains path separators" if feature.include?("/") || feature.include?("\\")
+
+root = Dir.pwd
+base = File.join(root, ".planning", "features", feature)
+files = {
+  "api_contract" => File.join(base, "api-contract.md"),
+  "api_call_guide" => File.join(base, "api-call-guide.md"),
+  "frontend_spec" => File.join(base, "前端技术方案.md"),
+  "backend_spec" => File.join(base, "后端技术方案.md"),
+  "api_supplement" => File.join(base, "api-supplement-requests.md"),
+}
+errors = []
+missing = files.select { |_, path| !File.file?(path) }.keys
+errors << { "code" => "CROSS_TRACK_ARTIFACT_MISSING", "files" => missing } unless missing.empty?
+
+read = lambda do |key|
+  path = files.fetch(key)
+  File.file?(path) ? File.read(path) : ""
+end
+contract = read.call("api_contract")
+guide = read.call("api_call_guide")
+frontend = read.call("frontend_spec")
+
+# Endpoint references are deliberately extracted from the authoritative API
+# contract and checked for textual closure in both consumers. This is a
+# deterministic reference-closure check; an AI integration summary is not used.
+endpoint_pattern = %r{\b(?:GET|POST|PUT|PATCH|DELETE)\s+(/[A-Za-z0-9_./:-]+(?:\{[A-Za-z0-9_]+\})*)}
+endpoints = contract.scan(endpoint_pattern).flatten.uniq
+unreferenced = endpoints.reject { |endpoint| guide.include?(endpoint) && frontend.include?(endpoint) }
+unless unreferenced.empty?
+  errors << { "code" => "CROSS_TRACK_ENDPOINT_REFERENCE_MISSING", "endpoints" => unreferenced }
+end
+
+contract_set = endpoints.to_h { |endpoint| [endpoint, true] }
+{
+  "api_call_guide" => guide.scan(endpoint_pattern).flatten.uniq,
+  "frontend_spec" => frontend.scan(endpoint_pattern).flatten.uniq,
+}.each do |consumer, references|
+  ghosts = references.reject { |endpoint| contract_set[endpoint] }
+  errors << { "code" => "CROSS_TRACK_ENDPOINT_NOT_IN_CONTRACT", "consumer" => consumer, "endpoints" => ghosts } unless ghosts.empty?
+end
+
+supplement = read.call("api_supplement")
+supplement_endpoints = supplement.scan(endpoint_pattern).flatten.uniq
+supplement_ghosts = supplement_endpoints.reject { |endpoint| contract_set[endpoint] }
+errors << { "code" => "CROSS_TRACK_SUPPLEMENT_ENDPOINT_NOT_IN_CONTRACT", "endpoints" => supplement_ghosts } unless supplement_ghosts.empty?
+supplement_unconsumed = supplement_endpoints.reject { |endpoint| guide.include?(endpoint) }
+errors << { "code" => "CROSS_TRACK_SUPPLEMENT_GUIDE_MISMATCH", "endpoints" => supplement_unconsumed } unless supplement_unconsumed.empty?
+
+meta_path = File.join(base, "api-call-guide.meta.json")
+if File.file?(meta_path)
+  begin
+    meta = JSON.parse(File.read(meta_path))
+    errors << { "code" => "CROSS_TRACK_API_GUIDE_NOT_CONSUMABLE" } unless meta["frontend_consumable"] == true && meta["mock_ready"] == true
+    pending = meta["pending_items"]
+    errors << { "code" => "CROSS_TRACK_API_GUIDE_PENDING_ITEMS", "pending_items" => pending } unless pending.is_a?(Array) && pending.empty?
+  rescue JSON::ParserError => error
+    errors << { "code" => "CROSS_TRACK_META_INVALID", "detail" => error.message }
+  end
+end
+
+supplement_meta = File.join(base, "api-supplement-requests.meta.json")
+if File.file?(supplement_meta)
+  begin
+    meta = JSON.parse(File.read(supplement_meta))
+    unresolved = meta["unresolved_supplement_count"]
+    errors << { "code" => "CROSS_TRACK_SUPPLEMENT_UNRESOLVED", "count" => unresolved } unless unresolved == 0
+  rescue JSON::ParserError => error
+    errors << { "code" => "CROSS_TRACK_META_INVALID", "detail" => error.message }
+  end
+end
+
+result = {
+  "ok" => errors.empty?,
+  "checker_id" => "cross-track-consistency-check",
+  "errors" => errors,
+  "evidence" => { "endpoint_count" => endpoints.length, "checked_files" => files.values.map { |path| path.sub("#{root}/", "") } },
+}
+puts(options[:json] ? JSON.generate(result) : result.to_yaml)

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

@@ -14,7 +14,7 @@ POLICY = {
   "requirement-baseline" => { "checkers" => %w[requirement-graph-check slice-independence-check acceptance-coverage-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[requirement rule boundary slice acceptance] },
   "api-contract" => { "checkers" => %w[requirement-graph-check contract-coverage-check api-test-schema-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[api] },
   "architecture-feasibility" => { "checkers" => %w[requirement-graph-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[workload_shape workload_constraint decision risk metric read_model] },
-  "integration-verify" => { "checkers" => %w[requirement-graph-check slice-independence-check contract-coverage-check change-impact-check], "agents" => ["verification-runner"], "budget" => 1, "allowed_graph_delta" => %w[requirement risk decision] },
+  "integration-verify" => { "checkers" => %w[requirement-graph-check slice-independence-check contract-coverage-check change-impact-check cross-track-consistency-check], "agents" => ["verification-runner"], "budget" => 1, "allowed_graph_delta" => %w[requirement risk decision] },
   "acceptance-test-design" => { "checkers" => %w[requirement-graph-check contract-coverage-check acceptance-coverage-check api-test-matrix-check test-coverage-check test-obligation-check change-impact-check], "agents" => [], "budget" => 0, "allowed_graph_delta" => %w[test_case] },
   "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] },

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

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "yaml"
+
+module GateContract
+  module_function
+
+  def load(path)
+    value = YAML.safe_load(File.read(path), permitted_classes: [], aliases: false)
+    validate!(value)
+    value
+  rescue Psych::Exception => e
+    raise ArgumentError, "invalid GateContract YAML: #{e.message}"
+  end
+
+  def validate!(contract)
+    raise ArgumentError, "GateContract must be a mapping" unless contract.is_a?(Hash)
+    %w[gate_id step_id topology entry outputs quality recovery].each do |field|
+      raise ArgumentError, "GateContract missing #{field}" unless contract.key?(field)
+    end
+    topology = contract["topology"]
+    raise ArgumentError, "topology must be a mapping" unless topology.is_a?(Hash)
+    %w[allowed_tracks allowed_predecessors].each do |field|
+      raise ArgumentError, "#{field} must be an array" unless topology[field].is_a?(Array)
+    end
+    raise ArgumentError, "allowed_reentry must be an array" unless topology["allowed_reentry"].is_a?(Array)
+    validate_reentries!(topology["allowed_reentry"])
+    checkpoint = topology["checkpoint"]
+    validate_checkpoint!(checkpoint) unless checkpoint.nil?
+    concurrency = contract["concurrency"]
+    raise ArgumentError, "concurrency must be a mapping" unless concurrency.is_a?(Hash)
+    %w[project_lock optimistic_revision registry_view].each do |field|
+      raise ArgumentError, "concurrency missing #{field}" unless concurrency.key?(field)
+    end
+    raise ArgumentError, "project_lock must be required" unless concurrency["project_lock"].to_s == "required"
+    raise ArgumentError, "optimistic_revision must be required" unless concurrency["optimistic_revision"].to_s == "required"
+    raise ArgumentError, "registry_view must be candidate_overlay" unless concurrency["registry_view"].to_s == "candidate_overlay"
+    recovery = contract["recovery"]
+    raise ArgumentError, "recovery must be a mapping" unless recovery.is_a?(Hash)
+    forbidden = Array(recovery["allowed"]).select { |action| action.to_s.start_with?("reenter_") || %w[confirm_checkpoint transition].include?(action.to_s) }
+    raise ArgumentError, "state transition cannot be an automatic recovery action: #{forbidden.join(", ")}" unless forbidden.empty?
+    contract
+  end
+
+  def validate_reentries!(entries)
+    entries.each do |entry|
+      raise ArgumentError, "reentry must be a mapping" unless entry.is_a?(Hash)
+      source = entry["source"]
+      target = entry["target"]
+      raise ArgumentError, "reentry source/target are required" unless source.is_a?(Hash) && target.is_a?(Hash)
+      %w[flow step].each { |field| raise ArgumentError, "reentry target missing #{field}" if target[field].to_s.empty? }
+      raise ArgumentError, "reentry must declare checkpoint reconfirmation" unless entry.key?("requires_checkpoint_reconfirm")
+    end
+  end
+
+  def validate_checkpoint!(checkpoint)
+    raise ArgumentError, "checkpoint must be a mapping" unless checkpoint.is_a?(Hash)
+    %w[id producing_step required_outputs required_meta_output prompt confirm_options skip_policy resume_behavior].each do |field|
+      raise ArgumentError, "checkpoint missing #{field}" unless checkpoint.key?(field)
+    end
+    raise ArgumentError, "checkpoint confirm_options must be an array" unless checkpoint["confirm_options"].is_a?(Array)
+  end
+end

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

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+module GateResult
+  VERDICTS = %w[allow allow_with_warning await_user waiting_external_input block_unsafe].freeze
+  CONTROL_PLANE_ERROR = "control_plane_error"
+
+  module_function
+
+  def build(verdict:, gate_id:, step_id:, errors: [], warnings: [], recovery: nil, evidence: {}, revisions: {})
+    valid = VERDICTS.include?(verdict.to_s) || verdict.to_s == CONTROL_PLANE_ERROR
+    raise ArgumentError, "invalid gate verdict: #{verdict}" unless valid
+
+    {
+      "ok" => %w[allow allow_with_warning].include?(verdict.to_s),
+      "verdict" => verdict.to_s,
+      "gate_id" => gate_id.to_s,
+      "step_id" => step_id.to_s,
+      "errors" => Array(errors),
+      "warnings" => Array(warnings),
+      "recovery" => recovery,
+      "evidence" => evidence.is_a?(Hash) ? evidence : {},
+      "revisions" => revisions.is_a?(Hash) ? revisions : {}
+    }
+  end
+
+  def allow(gate_id:, step_id:, **kwargs)
+    build(verdict: "allow", gate_id: gate_id, step_id: step_id, **kwargs)
+  end
+
+  def await_user(gate_id:, step_id:, recovery: nil, **kwargs)
+    build(verdict: "await_user", gate_id: gate_id, step_id: step_id, recovery: recovery, **kwargs)
+  end
+
+  def block(gate_id:, step_id:, code:, message:, recovery: nil, details: {}, **kwargs)
+    error = { "code" => code.to_s, "message" => message.to_s }
+    error.merge!(details) if details.is_a?(Hash)
+    build(verdict: "block_unsafe", gate_id: gate_id, step_id: step_id, errors: [error], recovery: recovery, **kwargs)
+  end
+end

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

@@ -0,0 +1,157 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require_relative "gate_result"
+require_relative "gate_contract"
+require_relative "checker_registry"
+require_relative "parallel_run"
+
+module GateRuntime
+  WORKFLOW_STATUSES = %w[in_progress waiting_checkpoint completed blocked failed cancelled remediation].freeze
+
+  module_function
+
+  def validate_contract!(contract)
+    GateContract.validate!(contract)
+    CheckerRegistry.validate!(Array(contract.dig("quality", "checker_ids")))
+    contract
+  end
+
+  def evaluate(contract:, workflow_state:, current_revision:, expected_revision:, track: nil, branch_id: nil, attempt: nil, branch_revision: nil, source: "harness", evidence: {}, root: nil, check_outputs: false, transition_kind: nil, checkpoint_authorized: false)
+    validate_contract!(contract)
+    gate_id = contract.fetch("gate_id")
+    step_id = contract.fetch("step_id")
+    base = { gate_id: gate_id, step_id: step_id, evidence: evidence.merge("collector" => source), revisions: { "state" => current_revision } }
+    return GateResult.block(**base, code: "REVISION_CONFLICT", message: "current revision does not match expected revision", recovery: { "kind" => "reinspect", "expected_revision" => expected_revision }) unless expected_revision.nil? || current_revision.to_i == expected_revision.to_i
+    unless WORKFLOW_STATUSES.include?(workflow_state["status"].to_s)
+      return GateResult.block(**base, code: "WORKFLOW_STATUS_INVALID", message: "workflow status is not recognized")
+    end
+    if workflow_state["parallel_run_ref"]
+      branch_error = validate_parallel_branch(
+        contract: contract,
+        workflow_state: workflow_state,
+        current_revision: current_revision,
+        track: track,
+        branch_id: branch_id,
+        attempt: attempt,
+        branch_revision: branch_revision,
+        evidence: evidence,
+        root: root,
+        transition_kind: transition_kind,
+      )
+      return GateResult.block(**base, **branch_error) if branch_error
+    end
+    unless %w[confirm_checkpoint enter_failure_branch exit_failure_branch parallel_join].include?(transition_kind)
+      allowed_tracks = Array(contract.dig("topology", "allowed_tracks"))
+      if track && !allowed_tracks.empty? && !allowed_tracks.include?(track)
+        return GateResult.block(**base, code: "TRACK_SCOPE_VIOLATION", message: "current track is not allowed by GateContract", recovery: { "kind" => "registered_reentry" })
+      end
+      allowed_predecessors = Array(contract.dig("topology", "allowed_predecessors"))
+      previous = workflow_state["last_completed_step"] || workflow_state["previous_step"]
+      if previous && !allowed_predecessors.empty? && !allowed_predecessors.include?(previous)
+        return GateResult.block(**base, code: "STEP_PREDECESSOR_INVALID", message: "previous step is not allowed by GateContract")
+      end
+      if root
+        missing = required_paths(contract.dig("entry", "required_inputs"), root, workflow_state)
+        return GateResult.block(**base, code: "REQUIRED_INPUT_MISSING", message: "required gate input is missing", details: { "missing" => missing }) unless missing.empty?
+        if check_outputs
+          missing_outputs = required_paths(contract.dig("outputs", "required"), root, workflow_state)
+          return GateResult.block(**base, code: "REQUIRED_OUTPUT_MISSING", message: "required step output is missing", details: { "missing" => missing_outputs }) unless missing_outputs.empty?
+        end
+      end
+    end
+    if transition_kind == "confirm_checkpoint"
+      checkpoint_id = workflow_state["checkpoint"].to_s
+      checkpoint = contract.dig("topology", "checkpoint")
+      checkpoint_matches = checkpoint.is_a?(Hash) && checkpoint["id"].to_s == checkpoint_id
+      unless workflow_state["status"].to_s == "waiting_checkpoint" && checkpoint_matches && checkpoint_authorized
+      return GateResult.block(**base, code: "CHECKPOINT_NOT_AUTHORIZED", message: "checkpoint confirmation is not authorized by the runtime", details: { "checkpoint" => checkpoint_id })
+      end
+      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
+    end
+    GateResult.allow(**base)
+  rescue KeyError, ArgumentError => e
+    GateResult.block(gate_id: contract.is_a?(Hash) ? contract["gate_id"] : "unknown", step_id: contract.is_a?(Hash) ? contract["step_id"] : "unknown", code: "GATE_CONTRACT_INVALID", message: e.message)
+  end
+
+  def validate_parallel_branch(contract:, workflow_state:, current_revision:, track:, branch_id:, attempt:, branch_revision:, evidence:, root:, transition_kind:)
+    return { code: "PARALLEL_CONTEXT_MISSING", message: "parallel workflow requires root" } unless root
+
+    record = ParallelRun.load(root, workflow_state.fetch("current_feature"))
+    return { code: "PARALLEL_RUN_NOT_FOUND", message: "parallel_run_ref does not resolve to a run record" } unless record
+    return { code: "PARALLEL_RUN_REF_MISMATCH", message: "STATE parallel_run_ref does not match run record" } unless record["run_id"].to_s == workflow_state["parallel_run_ref"].to_s
+    bound_revision = Integer(record.fetch("bound_state_revision"))
+    return { code: "PARALLEL_STATE_REVISION_MISMATCH", message: "parallel run is bound to a different STATE revision", details: { expected_state_revision: bound_revision, actual_state_revision: current_revision } } unless bound_revision == current_revision.to_i
+
+    if transition_kind.to_s == "parallel_join"
+      branches = Array(record["branches"])
+      return { code: "PARALLEL_JOIN_INCOMPLETE", message: "parallel join requires every branch to succeed", details: { incomplete: branches.reject { |item| item["status"].to_s == "succeeded" }.map { |item| item["branch_id"] } } } unless branches.any? && branches.all? { |item| item["status"].to_s == "succeeded" }
+      return nil
+    end
+    return { code: "PARALLEL_CONTEXT_MISSING", message: "parallel workflow requires branch_id" } unless branch_id
+
+    branch = Array(record["branches"]).find { |item| item["branch_id"].to_s == branch_id.to_s }
+    return { code: "PARALLEL_BRANCH_NOT_FOUND", message: "branch is not registered in the parallel run", details: { branch_id: branch_id } } unless branch
+    return { code: "PARALLEL_STEP_MISMATCH", message: "branch is bound to a different workflow step", details: { branch_step: branch["workflow_step"], gate_step: contract["step_id"] } } unless branch["workflow_step"].to_s == contract["step_id"].to_s
+    expected_track = branch["track"].to_s.sub(/\Atrack_/, "").upcase
+    return { code: "PARALLEL_TRACK_MISMATCH", message: "branch track is not the requested track", details: { branch_track: expected_track, requested_track: track } } unless track.to_s.empty? || expected_track.empty? || expected_track == track.to_s
+    return { code: "PARALLEL_BRANCH_TERMINAL", message: "terminal branch cannot pass a gate; retry must create a new attempt" } if ParallelRun::TERMINAL_BRANCH_STATUSES.include?(branch["status"].to_s) && transition_kind.to_s != "parallel_branch_retry"
+    return { code: "PARALLEL_ATTEMPT_MISMATCH", message: "branch attempt does not match the current run record" } if attempt && Integer(branch.fetch("attempt", 0)) != attempt.to_i
+    return { code: "PARALLEL_BRANCH_REVISION_MISMATCH", message: "branch revision does not match the current run record" } if branch_revision && Integer(branch.fetch("branch_revision", 0)) != branch_revision.to_i
+
+    predecessor_ids = Array(contract.dig("topology", "allowed_predecessors"))
+    completed = Array(workflow_state["completed_steps"]).map(&:to_s)
+    completed.concat(Array(record["branches"]).select { |item| item["status"].to_s == "succeeded" }.map { |item| item["workflow_step"].to_s })
+    missing_predecessors = predecessor_ids.map(&:to_s).reject { |step| completed.include?(step) }
+    return { code: "PARALLEL_PREDECESSOR_INCOMPLETE", message: "parallel branch predecessor is incomplete", details: { missing: missing_predecessors } } unless missing_predecessors.empty?
+
+    if transition_kind.to_s == "parallel_branch_complete"
+      required = %w[branch_id attempt branch_revision]
+      missing = required.reject { |field| evidence.key?(field) }
+      return { code: "PARALLEL_EVIDENCE_MISSING", message: "branch completion requires independent evidence binding", details: { missing: missing } } unless missing.empty?
+      return { code: "PARALLEL_EVIDENCE_MISMATCH", message: "branch evidence does not match current branch", details: { branch_id: branch_id } } unless evidence["branch_id"].to_s == branch_id.to_s && evidence["attempt"].to_i == branch.fetch("attempt", 0).to_i && evidence["branch_revision"].to_i == branch.fetch("branch_revision", 0).to_i
+      evidence_path = evidence["evidence_path"].to_s
+      return { code: "PARALLEL_EVIDENCE_MISSING", message: "Core machine evidence file is required" } if evidence_path.empty? || !File.file?(File.expand_path(evidence_path, root))
+      begin
+        pack = JSON.parse(File.read(File.expand_path(evidence_path, root)))
+        binding = pack.dig("evidence", "parallel_binding")
+        expected = { "run_id" => record["run_id"], "branch_id" => branch["branch_id"], "attempt" => branch.fetch("attempt", 0), "branch_revision" => branch.fetch("branch_revision", 0), "state_revision" => current_revision.to_i }
+        return { code: "PARALLEL_EVIDENCE_MISMATCH", message: "machine evidence binding does not match current branch", details: { expected: expected, actual: binding } } unless binding.is_a?(Hash) && expected.all? { |key, value| binding[key].to_s == value.to_s }
+      rescue JSON::ParserError, Errno::ENOENT
+        return { code: "PARALLEL_EVIDENCE_MISMATCH", message: "machine evidence file is not valid JSON" }
+      end
+    end
+    nil
+  rescue KeyError, ArgumentError, TypeError
+    { code: "PARALLEL_RECORD_INVALID", message: "parallel run or branch record is invalid" }
+  end
+
+  def run_checker(contract:, workflow_state:, current_revision:, expected_revision:, checker:, **kwargs)
+    boundary = evaluate(contract: contract, workflow_state: workflow_state, current_revision: current_revision, expected_revision: expected_revision, **kwargs)
+    return boundary unless boundary["verdict"] == "allow"
+    result = checker.call
+    raise ArgumentError, "checker must return a GateResult hash" unless result.is_a?(Hash) && result["verdict"]
+    result.merge(
+      "gate_id" => result["gate_id"] || boundary["gate_id"],
+      "step_id" => result["step_id"] || boundary["step_id"],
+      "evidence" => boundary.fetch("evidence", {}).merge(result.fetch("evidence", {})),
+      "revisions" => boundary.fetch("revisions", {}).merge(result.fetch("revisions", {}))
+    )
+  end
+
+  def required_paths(entries, root, state)
+    Array(entries).each_with_object([]) do |entry, missing|
+      raw = entry.is_a?(Hash) ? entry["path"] : entry
+      next if raw.to_s.empty?
+      relative = raw.to_s.gsub("{feature}", state.fetch("current_feature", "").to_s).gsub("{phase}", state.fetch("current_phase", "").to_s)
+      absolute = File.expand_path(relative, root)
+      root_real = File.realpath(root)
+      actual = File.exist?(absolute) ? File.realpath(absolute) : absolute
+      next if actual.start_with?("#{root_real}#{File::SEPARATOR}") && File.exist?(actual)
+      missing << relative
+    end
+  end
+end

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

@@ -191,6 +191,9 @@ def active_parallel_window(workflow, state, root, step_by_id, completed_ids, pen
       step = step_by_id[step_id]
       pending_ids.include?(step_id) && step && dependencies_satisfied?(step, completed_ids)
     end
+    # A single runnable branch is an intentional serial fallback (for example
+    # when active_track limits the window to one track), not a missing window.
+    # Only a genuinely multi-branch runnable set enters the parallel scheduler.
     next unless runnable_ids.length > 1
 
     policy = window["execution_policy"] || {}

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

@@ -10,14 +10,19 @@ require "optparse"
 require "yaml"
 require_relative "control_io"
 require_relative "requirement_graph"
+require_relative "checker_registry"
 
-options = { feature: nil, step: nil, contract: nil, write: false, json: false }
+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|
   o.on("--feature NAME") { |v| options[:feature] = v }
   o.on("--step ID") { |v| options[:step] = v }
   o.on("--contract PATH") { |v| options[:contract] = v }
   o.on("--write") { options[:write] = true }
   o.on("--json") { options[:json] = true }
+  o.on("--parallel-branch-id ID") { |v| options[:branch_id] = v }
+  o.on("--parallel-attempt N", Integer) { |v| options[:attempt] = v }
+  o.on("--parallel-branch-revision N", Integer) { |v| options[:branch_revision] = v }
+  o.on("--lock-held") { options[:lock_held] = true }
 end.parse!
 abort "feature, step and --write are required" unless options[:feature] && options[:step] && options[:write]
 abort "invalid feature" unless RequirementGraph.valid_feature?(options[:feature])
@@ -33,6 +38,81 @@ def interpolate(path, state)
   path.gsub("{feature}", state.fetch("current_feature", "").to_s).gsub("{phase}", state.fetch("current_phase", "").to_s)
 end
 
+def file_evidence(root, relative)
+  absolute, = DevflowControlIO.resolve_control_path(root, relative, :artifact)
+  return { "path" => relative, "exists" => false } unless File.file?(absolute)
+
+  { "path" => relative, "exists" => true, "sha256" => Digest::SHA256.file(absolute).hexdigest, "bytes" => File.size(absolute) }
+end
+
+def independent_evidence(root, feature, step, state, workflow, graph, files, checker_results, binding = nil, inputs = [])
+  source_nodes = Array(graph["nodes"]).select { |node| node.is_a?(Hash) && node["kind"] == "source" }
+  authority = source_nodes.map do |node|
+    evidence = node["evidence"].is_a?(Hash) ? node["evidence"] : {}
+    {
+      "source_id" => node["id"], "authority" => evidence["authority"], "path" => evidence["path"] || evidence["ref"],
+      "fingerprint" => evidence["sha256"] || evidence["source_document_fingerprint"]
+    }.compact
+  end
+
+  # The harness may publish an append-only event log beside the machine pack.
+  # Absence is represented as unavailable, never as false/zero, so the pack
+  # cannot manufacture proof that an engine did not invoke AI.
+  binding_attempt = binding && binding["attempt"]
+  event_name = binding_attempt.nil? ? "#{step}.engine-events.jsonl" : "#{step}.attempt-#{binding_attempt}.engine-events.jsonl"
+  event_path = File.join(".planning", "evidence", feature, event_name)
+  event_absolute, = DevflowControlIO.resolve_control_path(root, event_path, :artifact)
+  events = if File.file?(event_absolute)
+             File.foreach(event_absolute).first(10_000).each_with_object([]) do |line, parsed|
+               next if line.strip.empty?
+
+               begin
+                 parsed << JSON.parse(line)
+               rescue JSON::ParserError
+                 # A malformed event is not evidence of a clean execution;
+                 # retain the valid events and let the collector expose the
+                 # observed subset without inventing a zero count.
+               end
+             end
+           else
+             nil
+           end
+  ai_events = events ? events.select { |event| %w[ai_runtime_initialized ai_invocation].include?(event["event"]) } : []
+  dispatched_events = events ? events.select { |event| event["event"] == "engine_dispatched" } : []
+  ai_measurement_observed = !ai_events.empty?
+
+  {
+    "collector" => "core.machine_evidence/v1",
+    "state" => { "revision" => state["revision"], "step" => step },
+    "parallel_binding" => binding,
+    "input_fingerprints" => inputs.select { |item| item["exists"] }.map { |item| item["sha256"] },
+    "output_fingerprints" => files.select { |item| item["exists"] }.map { |item| item["sha256"] },
+    "source_authority" => { "status" => authority.empty? ? "unavailable" : "observed", "sources" => authority },
+    "candidate_binding" => {
+      "status" => "observed",
+      "graph_revision" => graph["revision"],
+      "test_case_ids" => Array(graph["nodes"]).each_with_object([]) { |node, ids| ids << node["id"] if node.is_a?(Hash) && node["kind"] == "test_case" }
+    },
+    "structured_execution" => {
+      "status" => "observed",
+      "required_files" => files,
+      "checker_ids" => checker_results.map { |item| item["id"] }
+    },
+    "engine_evidence" => {
+      "collector" => events ? "harness.engine-events/v1" : "unavailable",
+      "event_log" => event_path,
+      # engine_dispatched proves that the harness dispatched work, but it does
+      # not prove how many model calls the child session made. Keep unknown as
+      # nil instead of manufacturing false/zero values for branch evidence.
+      "ai_runtime_initialized" => ai_measurement_observed ? ai_events.any? { |event| event["event"] == "ai_runtime_initialized" } : nil,
+      "ai_invocation_count" => ai_measurement_observed ? ai_events.count { |event| event["event"] == "ai_invocation" } : nil,
+      "engine_dispatched_count" => events ? dispatched_events.length : nil,
+      "ai_capable_engine_dispatched" => events ? dispatched_events.any? { |event| event["ai_capable"] == true } : nil,
+      "evidence_status" => events ? "observed" : "unavailable"
+    }
+  }
+end
+
 def configured_checkers(workflow, step_id)
   explicit = workflow.dig("governance", "step_checkers", step_id)
   checkers = if explicit
@@ -92,13 +172,24 @@ rescue JSON::ParserError => error
 end
 
 root = Dir.pwd
-lock = DevflowControlIO.acquire_project_lock(root)
+lock = options[:lock_held] ? nil : DevflowControlIO.acquire_project_lock(root)
 begin
   state = state_front_matter(root)
-  unless state["current_feature"] == options[:feature] && state["current_step"] == options[:step]
+  binding = nil
+  branch = nil
+  if options[:branch_id]
+    require_relative "parallel_run"
+    record = ParallelRun.load(root, options[:feature])
+    branch = Array(record && record["branches"]).find { |item| item["branch_id"].to_s == options[:branch_id].to_s }
+    raise "parallel branch not found" unless record && branch
+    raise "parallel branch attempt mismatch" unless options[:attempt].nil? || Integer(branch.fetch("attempt", 0)) == options[:attempt]
+    raise "parallel branch revision mismatch" unless options[:branch_revision].nil? || Integer(branch.fetch("branch_revision", 0)) == options[:branch_revision]
+    binding = { "run_id" => record["run_id"], "branch_id" => branch["branch_id"], "attempt" => branch["attempt"], "branch_revision" => branch["branch_revision"], "state_revision" => state["revision"] }
+  end
+  unless state["current_feature"] == options[:feature] && (state["current_step"] == options[:step] || branch)
     result = { "ok" => false, "reason" => "state_step_mismatch", "state_feature" => state["current_feature"], "state_step" => state["current_step"] }
     puts JSON.pretty_generate(result)
-    exit 0
+    exit 1
   end
   workflow_path, = DevflowControlIO.resolve_control_path(root, state.fetch("workflow_config"), :workflow)
   workflow_raw = File.read(workflow_path)
@@ -117,10 +208,12 @@ 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)) }
 
   graph, = RequirementGraph.load_graph(root, options[:feature])
   checkers = RequirementGraph.checker_results(graph)
   selected = configured_checkers(workflow, options[:step])
+  CheckerRegistry.validate!(selected)
   gate = workflow.dig("governance", "requirement_graph_gate").to_s
   enforced = gate == "enforced"
   checker_results = selected.map do |id|
@@ -133,6 +226,7 @@ begin
   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"] })
+  engine_evidence_gate = (step["engine_evidence_gate"] || workflow.dig("governance", "engine_evidence_gate")).to_s
   contract_hash = nil
   if options[:contract]
     contract_path = File.expand_path(options[:contract], root)
@@ -140,22 +234,31 @@ begin
     contract_hash = Digest::SHA256.file(contract_path).hexdigest
   end
   node_counts = Array(graph["nodes"]).group_by { |node| node["kind"] }.transform_values(&:length)
+  independent = independent_evidence(root, options[:feature], options[:step], state, workflow, graph, files, checker_results, binding, input_files)
+  engine_evidence_complete = independent.dig("engine_evidence", "evidence_status") == "observed"
+  evidence_complete = engine_evidence_gate != "enforced" || engine_evidence_complete
   pack = {
     "schema_version" => 2, "origin" => "core_machine", "feature" => options[:feature], "step" => options[:step],
     "state_revision" => state["revision"], "graph_revision" => graph["revision"], "workflow_fingerprint" => Digest::SHA256.hexdigest(workflow_raw),
-    "contract_hash" => contract_hash, "files" => files, "checkers" => checker_results,
+    "run_id" => binding && binding["run_id"], "branch_id" => binding && binding["branch_id"],
+    "attempt" => binding && binding["attempt"], "branch_revision" => binding && binding["branch_revision"],
+    "input_fingerprints" => input_files.select { |item| item["exists"] }.map { |item| item["sha256"] },
+    "output_fingerprints" => files.select { |item| item["exists"] }.map { |item| item["sha256"] },
+    "contract_hash" => contract_hash, "files" => files, "input_files" => input_files, "checkers" => checker_results, "evidence" => independent,
     "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,
+    "complete" => files.all? { |item| item["exists"] } && checker_passed && evidence_complete,
+    "evidence_complete" => evidence_complete,
     "gate_mode" => gate.empty? ? "observe" : gate
   }.compact
-  destination = File.join(root, ".planning/evidence", options[:feature], "#{options[:step]}.machine.json")
+  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 }
+  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 }
 rescue StandardError => error
   result = { "ok" => false, "reason" => "machine_evidence_failed", "message" => error.message }
 ensure
-  DevflowControlIO.release_lock(lock)
+  DevflowControlIO.release_lock(lock) if lock
 end
 puts JSON.pretty_generate(result)