@guanlin4924/devflow-pi 0.1.86 → 0.1.88

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

package/plugins/devflow-core/skills/workflow-orchestrator/scripts/review_preflight.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""Read-only Core review preflight. Never runs an AI review or changes project files."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import subprocess
+import sys
+
+
+def sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def within(root: Path, relative: str) -> Path:
+    if not isinstance(relative, str) or not relative or Path(relative).is_absolute() or "\x00" in relative:
+        raise ValueError("invalid relative path")
+    path = (root / relative).resolve()
+    if not path.is_relative_to(root):
+        raise ValueError("path escapes project")
+    return path
+
+
+def load_workflow(path: Path) -> dict:
+    command = ["ruby", "-ryaml", "-rjson", "-e",
+               "puts JSON.generate(YAML.safe_load(File.read(ARGV.fetch(0)), permitted_classes: [], aliases: false))",
+               str(path)]
+    result = subprocess.run(command, text=True, capture_output=True, timeout=15, check=False)
+    if result.returncode:
+        raise ValueError(f"workflow cannot be read: {result.stderr.strip()}")
+    return json.loads(result.stdout)
+
+
+def load_state(path: Path) -> dict:
+    command = ["ruby", "-ryaml", "-rjson", "-e",
+               "front = File.read(ARGV.fetch(0)).match(/\\A---\\n(.*?)\\n---/m); "
+               "abort 'STATE front matter missing' unless front; "
+               "puts JSON.generate(YAML.safe_load(front[1], permitted_classes: [], aliases: false))",
+               str(path)]
+    result = subprocess.run(command, text=True, capture_output=True, timeout=15, check=False)
+    if result.returncode:
+        raise ValueError(f"STATE cannot be read: {result.stderr.strip()}")
+    return json.loads(result.stdout)
+
+
+def preflight(root: Path, feature: str, step: str, contract_path: str,
+              obligations: list[dict], review_agent: str | None = None,
+              review_contract_path: str | None = None, stage: str = "completion") -> dict:
+    root = root.resolve()
+    evidence, issues = [], []
+    if stage not in {"entry", "completion"}:
+        return {"status": "human_confirmation", "scope": "snapshot_preflight_only_not_gate_approval",
+                "evidence": [], "issues": [{"code": "INVALID_STAGE"}]}
+    try:
+        frozen_path = within(root, contract_path)
+        frozen = json.loads(frozen_path.read_text(encoding="utf-8"))
+        command = ["ruby", str(Path(__file__).with_name("execution_contract.rb")),
+                   "inspect", "--feature", feature, "--step", step, "--json"]
+        run = subprocess.run(command, cwd=root, text=True, capture_output=True, timeout=15, check=False)
+        current_result = json.loads(run.stdout)
+        if run.returncode or not current_result.get("ok"):
+            return {"status": "human_confirmation", "evidence": evidence,
+                    "issues": [{"code": "CURRENT_TRUTH_UNAVAILABLE", "detail": current_result.get("message", run.stderr)}]}
+        current = current_result["contract"]
+        evidence.extend([
+            {"kind": "state_graph", "state_revision": current["state_revision"],
+             "graph_revision": current["graph_revision"]},
+            {"kind": "contract", "path": contract_path, "sha256": sha256(frozen_path),
+             "contract_id": frozen.get("contract_id")},
+        ])
+        if frozen != current:
+            return {"status": "human_confirmation", "evidence": evidence,
+                    "issues": [{"code": "STALE_EXECUTION_CONTRACT",
+                                "detail": "frozen contract differs from current Core snapshot; recreate and retry"}]}
+        if frozen.get("feature") != feature or frozen.get("step") != step:
+            issues.append({"code": "CONTRACT_TARGET_MISMATCH", "detail": "contract feature/step mismatch"})
+        workflow_path = within(root, current["workflow_path"])
+        if sha256(workflow_path) != current["workflow_fingerprint"]:
+            return {"status": "human_confirmation", "evidence": evidence,
+                    "issues": [{"code": "STALE_WORKFLOW_SNAPSHOT"}]}
+        workflow = load_workflow(workflow_path)
+        state = load_state(within(root, ".planning/STATE.md"))
+        if state.get("revision") != current["state_revision"] or state.get("current_feature") != feature or state.get("current_step") != step:
+            return {"status": "human_confirmation", "evidence": evidence,
+                    "issues": [{"code": "STALE_STATE_SNAPSHOT"}]}
+        step_definition = next((item for item in workflow.get("steps", [])
+                                if isinstance(item, dict) and item.get("id") == step), None)
+        if step_definition is None:
+            raise ValueError("current workflow step unavailable")
+        render = lambda value: value.replace("{feature}", feature).replace("{phase}", str(state["current_phase"]))
+        derived = []
+        for raw in step_definition.get("inputs", []):
+            if isinstance(raw, str):
+                relative, required = raw, True
+            elif isinstance(raw, dict) and isinstance(raw.get("path"), str):
+                relative = raw["path"]
+                required = (raw.get("required", True) and raw.get("required_at_entry", True)) if stage == "entry" else raw.get("required_at_completion", raw.get("required", True))
+            else:
+                issues.append({"code": "INVALID_WORKFLOW_INPUT", "detail": "unrecognized input obligation"})
+                continue
+            if required and relative != ".planning/execution-contract.md":
+                derived.append({"path": render(relative), "producer": "existing"})
+        for item in step_definition.get("outputs", []):
+            if isinstance(item, dict) and item.get("required") is True and isinstance(item.get("path"), str):
+                derived.append({"path": render(item["path"]), "producer": "step"})
+        meta = step_definition.get("meta_output")
+        if isinstance(meta, dict) and isinstance(meta.get("path"), str):
+            derived.append({"path": render(meta["path"]), "producer": "step"})
+        evidence.append({"kind": "workflow", "path": current["workflow_path"],
+                         "sha256": current["workflow_fingerprint"],
+                         "required_obligation_count": len(derived),
+                         "checker_ids": current.get("checker_ids", [])})
+        if step == "code-review":
+            graph_relative = f".planning/requirements/{feature}/governance.json"
+            graph_path = within(root, graph_relative)
+            if not graph_path.is_file():
+                issues.append({"code": "CONFIRMED_EXPECTATIONS_UNAVAILABLE", "path": graph_relative})
+            else:
+                graph = json.loads(graph_path.read_text(encoding="utf-8"))
+                stale = {entry.get("node_id") for entry in graph.get("stale", []) if isinstance(entry, dict)}
+                relevant = [node for node in graph.get("nodes", [])
+                            if isinstance(node, dict) and node.get("kind") in {"requirement", "rule", "boundary", "acceptance"}]
+                unconfirmed = [node.get("id", "unknown") for node in relevant
+                               if node.get("status") != "confirmed" or node.get("id") in stale
+                               or not isinstance(node.get("confirmation"), dict)
+                               or node["confirmation"].get("origin") != "core"
+                               or not node["confirmation"].get("evidence")]
+                if graph.get("feature") != feature or graph.get("revision") != current["graph_revision"] or not relevant:
+                    issues.append({"code": "CONFIRMED_EXPECTATIONS_UNAVAILABLE", "path": graph_relative})
+                elif unconfirmed:
+                    issues.append({"code": "UNCONFIRMED_EXPECTATIONS", "path": graph_relative,
+                                   "node_ids": unconfirmed,
+                                   "detail": "Core review scope is not available; confirm or scope these nodes before task dispatch"})
+                else:
+                    evidence.append({"kind": "confirmed_expectations", "path": graph_relative,
+                                     "sha256": sha256(graph_path), "graph_revision": graph["revision"],
+                                     "node_ids": [node["id"] for node in relevant]})
+        if not derived and not current.get("checker_ids"):
+            issues.append({"code": "NO_REVIEW_OBLIGATIONS", "detail": "Core workflow defines no review obligations"})
+        supplied = {item.get("path"): item for item in obligations if isinstance(item, dict)}
+        for item in derived:
+            supplement = supplied.get(item["path"], {})
+            if supplement.get("producer") not in (None, item["producer"]):
+                issues.append({"code": "OBLIGATION_PRODUCER_MISMATCH", "path": item["path"]})
+            item.update({key: value for key, value in supplement.items() if key == "sha256"})
+        obligations = derived + [item for item in obligations if not isinstance(item, dict) or item.get("path") not in {d["path"] for d in derived}]
+        allowed = set(current.get("allowed_paths", []))
+        for index, obligation in enumerate(obligations):
+            if not isinstance(obligation, dict) or not isinstance(obligation.get("path"), str):
+                issues.append({"code": "INVALID_OBLIGATION", "index": index})
+                continue
+            relative = obligation["path"]
+            try:
+                path = within(root, relative)
+            except ValueError as error:
+                issues.append({"code": "INVALID_OBLIGATION_PATH", "index": index, "detail": str(error)})
+                continue
+            producer = obligation.get("producer")
+            if producer == "existing":
+                if not path.is_file():
+                    issues.append({"code": "MISSING_INPUT_FACT", "index": index, "path": relative})
+                elif obligation.get("sha256") is not None and obligation.get("sha256") != sha256(path):
+                    issues.append({"code": "STALE_INPUT_FACT", "index": index, "path": relative})
+                else:
+                    evidence.append({"kind": "input", "path": relative, "sha256": sha256(path)})
+            elif producer == "step":
+                if relative not in allowed:
+                    issues.append({"code": "UNREACHABLE_OBLIGATION", "index": index, "path": relative,
+                                   "detail": "step contract does not allow producing this path"})
+                else:
+                    evidence.append({"kind": "producer", "path": relative, "step": step,
+                                     "contract_id": current["contract_id"]})
+                    if path.is_file():
+                        evidence.append({"kind": "output_snapshot", "path": relative, "sha256": sha256(path)})
+                    elif stage == "completion":
+                        issues.append({"code": "MISSING_REVIEW_OUTPUT", "index": index, "path": relative})
+            else:
+                issues.append({"code": "UNKNOWN_PRODUCER", "index": index, "path": relative})
+        if step == "code-review" and review_agent not in (None, "devflow-code-reviewer"):
+            issues.append({"code": "REVIEW_AGENT_MISMATCH", "agent": review_agent,
+                           "detail": "code-review requires the independent devflow-code-reviewer"})
+        if step == "code-review":
+            review_agent = "devflow-code-reviewer"
+        if review_agent:
+            reviewer_contract = current
+            if review_contract_path:
+                review_path = within(root, review_contract_path)
+                reviewer_contract = json.loads(review_path.read_text(encoding="utf-8"))
+                evidence.append({"kind": "review_contract", "path": review_contract_path,
+                                 "sha256": sha256(review_path)})
+                if reviewer_contract.get("feature") != feature or reviewer_contract.get("graph_revision") != current.get("graph_revision"):
+                    issues.append({"code": "STALE_REVIEW_CONTRACT"})
+                # A separate step cannot be inspected while STATE points at the execution
+                # step. A supplied JSON file alone is not Core authority.
+                issues.append({"code": "REVIEW_CONTRACT_UNVERIFIED",
+                               "detail": "separate review contract needs a Core-verified step transition"})
+            if review_agent not in reviewer_contract.get("allowed_agents", []) or reviewer_contract.get("tool_budget", 0) < 1:
+                issues.append({"code": "REVIEW_AGENT_UNREACHABLE", "agent": review_agent,
+                               "detail": "review agent is not allowed or task budget is insufficient"})
+    except (OSError, ValueError, KeyError, TypeError, subprocess.TimeoutExpired) as error:
+        return {"status": "human_confirmation", "evidence": evidence,
+                "issues": [{"code": "PREFLIGHT_INPUT_UNAVAILABLE", "detail": str(error)}]}
+    conflict_codes = {"CONTRACT_TARGET_MISMATCH", "UNREACHABLE_OBLIGATION", "REVIEW_AGENT_MISMATCH",
+                      "REVIEW_AGENT_UNREACHABLE", "STALE_REVIEW_CONTRACT"}
+    status = ("core_contract_conflict" if any(issue["code"] in conflict_codes for issue in issues)
+              else "human_confirmation" if issues else "ready")
+    return {"status": status, "scope": "snapshot_preflight_only_not_gate_approval",
+            "evidence": evidence, "issues": issues}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--root", type=Path, default=Path.cwd())
+    parser.add_argument("--feature", required=True)
+    parser.add_argument("--step", required=True)
+    parser.add_argument("--contract", required=True, help="project-relative frozen contract JSON")
+    parser.add_argument("--obligations", required=True, help="JSON array: {path, producer: existing|step, sha256?}")
+    parser.add_argument("--review-agent")
+    parser.add_argument("--review-contract", help="separate project-relative reviewer contract JSON")
+    parser.add_argument("--stage", choices=["entry", "completion"], default="completion")
+    args = parser.parse_args()
+    try:
+        obligations = json.loads(args.obligations)
+        if not isinstance(obligations, list):
+            raise ValueError("obligations must be an array")
+        result = preflight(args.root.resolve(), args.feature, args.step, args.contract,
+                           obligations, args.review_agent, args.review_contract, args.stage)
+    except ValueError as error:
+        result = {"status": "human_confirmation", "evidence": [],
+                  "issues": [{"code": "INVALID_INPUT", "detail": str(error)}]}
+    print(json.dumps(result, ensure_ascii=False, sort_keys=True))
+    return 0 if result["status"] == "ready" else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())