@guanlin4924/devflow-pi 0.1.96 → 0.1.98

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

@@ -65,6 +65,16 @@ module RequirementGraph
     nil
   end
 
+  def active_flow(root)
+    state_path = File.join(root, ".devflow/planning/STATE.md")
+    return nil unless File.file?(state_path)
+    front = File.read(state_path).match(/\A---\n(.*?)\n---/m)&.[](1)
+    return nil unless front
+    YAML.safe_load(front, permitted_classes: [], aliases: false)["current_flow"]
+  rescue Psych::Exception
+    nil
+  end
+
   def assert_active_feature!(root, feature)
     current = active_feature(root)
     return if current.nil? || current == feature
@@ -188,7 +198,7 @@ module RequirementGraph
     graph["stale"].reject! { |entry| entry.is_a?(Hash) && entry["node_id"] == node_id }
   end
 
-  def proposal(graph, delta, allowed_kinds = nil)
+  def proposal(graph, delta, allowed_kinds = nil, regression: false)
     raise ArgumentError, "delta must be an object" unless delta.is_a?(Hash)
     case delta["op"]
     when "add"
@@ -198,7 +208,7 @@ module RequirementGraph
       raise ArgumentError, "node kind #{kind} is not allowed by the execution contract" if allowed_kinds && !allowed_kinds.include?(kind)
       data = normalize_data(delta["data"])
       node = { "id" => next_id(graph, prefix), "kind" => kind, "status" => "candidate", "data" => data }
-      candidate_errors = workload_node_errors(graph, node) + metric_node_errors(graph, node) + read_model_node_errors(graph, node) + architecture_decision_errors(graph, node) + architecture_risk_errors(graph, node) + test_case_errors(graph, node)
+      candidate_errors = workload_node_errors(graph, node) + metric_node_errors(graph, node) + read_model_node_errors(graph, node) + architecture_decision_errors(graph, node) + architecture_risk_errors(graph, node) + test_case_errors(graph, node, regression: regression)
       raise ArgumentError, candidate_errors.join("; ") if candidate_errors.any?
       set_node_fingerprint!(node)
       graph["nodes"] << node
@@ -220,7 +230,7 @@ module RequirementGraph
       end
       data = normalize_data(delta["data"])
       node["data"] = node.fetch("data", {}).merge(data)
-      candidate_errors = workload_node_errors(graph, node) + metric_node_errors(graph, node) + read_model_node_errors(graph, node) + architecture_decision_errors(graph, node) + architecture_risk_errors(graph, node) + test_case_errors(graph, node)
+      candidate_errors = workload_node_errors(graph, node) + metric_node_errors(graph, node) + read_model_node_errors(graph, node) + architecture_decision_errors(graph, node) + architecture_risk_errors(graph, node) + test_case_errors(graph, node, regression: regression)
       raise ArgumentError, candidate_errors.join("; ") if candidate_errors.any?
       set_node_fingerprint!(node)
       clear_stale_for!(graph, id)
@@ -301,25 +311,50 @@ module RequirementGraph
   # causally proven without a deterministic replay.
   TEST_EVIDENCE_STRATEGIES = %w[replay causal observation].freeze
   REPLAY_SCOPES = %w[component page api integration].freeze
+  ORACLE_SOURCES = %w[requirement contract invariant characterization].freeze
+
+  def oracle_source_errors(node, data, regression: false)
+    errors = []
+    source = data["oracle_source"]
+    if source.nil? && !regression
+      source = "requirement"
+    elsif !ORACLE_SOURCES.include?(source)
+      errors << "#{node["id"]}: oracle_source must be requirement, contract, invariant, or characterization"
+      return errors
+    end
+    if regression && !data.key?("oracle_source")
+      errors << "#{node["id"]}: regression TC requires explicit oracle_source"
+    end
+    if source == "requirement"
+      errors << "#{node["id"]}: requirement oracle_source requires non-empty acceptance_refs" unless data["acceptance_refs"].is_a?(Array) && !data["acceptance_refs"].empty?
+    elsif !data["oracle_evidence"].is_a?(String) || data["oracle_evidence"].strip.empty?
+      errors << "#{node["id"]}: #{source} oracle_source requires oracle_evidence"
+    end
+    errors
+  end
 
   # TC nodes are derived verification intent. They deliberately store only
   # externally observable setup, operation and oracle; implementation paths,
   # selectors and agent summaries belong to later execution bindings.
-  def test_case_errors(graph, node, require_edges: false, require_confirmed_inputs: false)
+  def test_case_errors(graph, node, require_edges: false, require_confirmed_inputs: false, regression: false)
     return [] unless node["kind"] == "test_case"
 
     data = node["data"].is_a?(Hash) ? node["data"] : {}
     errors = []
-    %w[acceptance_refs requirement_refs test_type target preconditions steps oracle automation_mode evidence_strategy].each do |field|
+    %w[test_type target preconditions steps oracle automation_mode evidence_strategy].each do |field|
       errors << "#{node["id"]}: missing #{field}" unless present?(data[field])
     end
-    errors << "#{node["id"]}: acceptance_refs must be a non-empty array" unless data["acceptance_refs"].is_a?(Array) && !data["acceptance_refs"].empty?
-    errors << "#{node["id"]}: requirement_refs must be a non-empty array" unless data["requirement_refs"].is_a?(Array) && !data["requirement_refs"].empty?
+    allow_empty_refs = regression && data["oracle_source"] && data["oracle_source"] != "requirement"
+    errors << "#{node["id"]}: acceptance_refs must be present" unless data.key?("acceptance_refs")
+    errors << "#{node["id"]}: acceptance_refs must be a non-empty array" unless data["acceptance_refs"].is_a?(Array) && (!data["acceptance_refs"].empty? || allow_empty_refs)
+    errors << "#{node["id"]}: requirement_refs must be present" unless data.key?("requirement_refs")
+    errors << "#{node["id"]}: requirement_refs must be a non-empty array" unless data["requirement_refs"].is_a?(Array) && (!data["requirement_refs"].empty? || allow_empty_refs)
     errors << "#{node["id"]}: preconditions must be a non-empty array" unless data["preconditions"].is_a?(Array) && !data["preconditions"].empty?
     errors << "#{node["id"]}: steps must be a non-empty array" unless data["steps"].is_a?(Array) && !data["steps"].empty?
     errors << "#{node["id"]}: invalid test_type" unless TEST_CASE_TYPES.include?(data["test_type"])
     errors << "#{node["id"]}: invalid automation_mode" unless TEST_AUTOMATION_MODES.include?(data["automation_mode"])
     errors << "#{node["id"]}: invalid evidence_strategy" unless TEST_EVIDENCE_STRATEGIES.include?(data["evidence_strategy"])
+    errors.concat(oracle_source_errors(node, data, regression: regression))
     case data["evidence_strategy"]
     when "replay"
       errors << "#{node["id"]}: replay tests require replay_scope" unless REPLAY_SCOPES.include?(data["replay_scope"])
@@ -447,7 +482,7 @@ module RequirementGraph
   # CP-3 is the single freeze point. Keep it here instead of in a Skill so the
   # graph revision, TC statuses, views and audit entry commit atomically under
   # the caller's control-plane lock.
-  def freeze_test_cases!(root, graph, cp_record, confirm_prerequisites: false, persist: true)
+  def freeze_test_cases!(root, graph, cp_record, confirm_prerequisites: false, persist: true, regression: false)
     cases = Array(graph["nodes"]).select { |node| node.is_a?(Hash) && node["kind"] == "test_case" }
     return { "ok" => false, "reason" => "test_suite_empty", "message" => "cannot freeze an empty TC suite" } if cases.empty?
     return { "ok" => false, "reason" => "test_suite_already_frozen", "message" => "confirmed test cases require a new candidate suite" } if cases.any? { |node| node["status"] == "confirmed" }
@@ -460,10 +495,10 @@ module RequirementGraph
                                 end
     return prerequisite_confirmation unless prerequisite_confirmation["ok"]
 
-    checkers = checker_results(graph)
+    checkers = checker_results(graph, regression: regression)
     errors = checkers.fetch("test-coverage-check", []).dup
     errors.concat(checkers.fetch("test-obligation-check", []))
-    cases.each { |node| errors.concat(test_case_errors(graph, node, require_edges: true, require_confirmed_inputs: true)) }
+    cases.each { |node| errors.concat(test_case_errors(graph, node, require_edges: true, require_confirmed_inputs: true, regression: regression)) }
     return { "ok" => false, "reason" => "test_suite_incomplete", "message" => errors.uniq.join("; "), "errors" => errors.uniq } if errors.any?
 
     cases.each do |node|
@@ -528,14 +563,14 @@ module RequirementGraph
         comparable = node.dig("data", "execution") == candidate_data["execution"] && node.dig("data", "test_obligation_refs") == candidate_data["test_obligation_refs"]
         raise ArgumentError, "#{item["key"]}: existing generated TC does not match matrix" unless comparable
       else
-        applied = proposal(graph, { "op" => "add", "kind" => "test_case", "data" => candidate_data }, ["test_case"])
+        applied = proposal(graph, { "op" => "add", "kind" => "test_case", "data" => candidate_data }, ["test_case"], regression: active_flow(root).to_s == "regression-acceptance")
         node = applied.fetch("node")
         refs = Array(candidate_data["acceptance_refs"]) + Array(candidate_data["requirement_refs"]) + Array(candidate_data["api_refs"])
         refs.each do |ref|
           edge = { "from" => ref, "to" => node["id"], "relation" => "verified_by" }
           graph["edges"] << edge unless graph["edges"].include?(edge)
         end
-        errors = test_case_errors(graph, node, require_edges: true, require_confirmed_inputs: true)
+        errors = test_case_errors(graph, node, require_edges: true, require_confirmed_inputs: true, regression: active_flow(root).to_s == "regression-acceptance")
         raise ArgumentError, errors.join("; ") if errors.any?
         existing[item["key"]] = node
         imported << node["id"]
@@ -827,7 +862,7 @@ module RequirementGraph
     !node.nil? && node["status"] == "confirmed"
   end
 
-  def checker_results(graph)
+  def checker_results(graph, regression: false)
     results = {
       "requirement-graph-check" => [], "slice-independence-check" => [], "contract-coverage-check" => [],
       "change-impact-check" => [], "acceptance-coverage-check" => [], "test-coverage-check" => [], "test-obligation-check" => [], "risk-derivation-check" => []
@@ -886,7 +921,7 @@ module RequirementGraph
         end
       when "test_case"
         results["test-coverage-check"].concat(
-          test_case_errors(graph, node, require_edges: true, require_confirmed_inputs: node["status"] == "confirmed")
+          test_case_errors(graph, node, require_edges: true, require_confirmed_inputs: node["status"] == "confirmed", regression: regression)
         )
       end
     end
@@ -1137,7 +1172,7 @@ if __FILE__ == $PROGRAM_NAME
                  delta = JSON.parse(options[:delta_json].to_s)
                  allowed_kinds = options[:allowed_kinds]&.split(",")&.map(&:strip)
                  candidate = RequirementGraph.deep_clone(graph)
-                 applied = RequirementGraph.proposal(candidate, delta, allowed_kinds)
+        applied = RequirementGraph.proposal(candidate, delta, allowed_kinds, regression: RequirementGraph.active_flow(root).to_s == "regression-acceptance")
                  candidate["revision"] += 1
                  stale = Array(candidate["stale"]).any?
                  if options[:write]

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

@@ -25,6 +25,7 @@ parser = OptionParser.new do |opts|
   opts.on("--source-session-id ID", "Source OMP session id") { |v| options[:source_session_id] = v }
   opts.on("--target-session-id ID", "Target OMP session id") { |v| options[:target_session_id] = v }
   opts.on("--reason TEXT", "Auditable rollover reason") { |v| options[:reason] = v }
+  opts.on("--carry-file PATH", "JSON carry text supplied by the Runtime") { |v| options[:carry_file] = v }
   opts.on("--lease-seconds N", Integer, "Claim lease duration") { |v| options[:lease_seconds] = v }
 end
 action = ARGV.shift
@@ -68,8 +69,64 @@ def lease_expiry(seconds)
   [[seconds.to_i, 5].max, 3600].min.then { |duration| (Time.now.utc + duration).iso8601(3) }
 end
 
+def truncate_text(value, limit)
+  return "" unless value.is_a?(String)
+  return value if value.length <= limit
+
+  value[0, limit - 1] + "…"
+end
+
+def load_carry(path)
+  parsed = JSON.parse(File.read(path))
+  raise JSON::ParserError, "carry must be a JSON object" unless parsed.is_a?(Hash)
+
+  notes = parsed["user_notes"].is_a?(Array) ? parsed["user_notes"].select { |item| item.is_a?(String) } : []
+  {
+    "user_notes" => notes.last(10).map { |item| truncate_text(item, 500) },
+    "agent_report" => truncate_text(parsed["agent_report"], 4000)
+  }
+end
+
+def previous_step_payload(root, state)
+  step_id = state["completed_steps"].is_a?(Array) ? state["completed_steps"].last : nil
+  return nil unless step_id.is_a?(String) && !step_id.empty?
+
+  workflow_path, = DevflowControlIO.resolve_control_path(root, state["workflow_config"], :workflow)
+  workflow = YAML.safe_load(File.read(workflow_path), permitted_classes: [], aliases: false)
+  step = workflow.fetch("steps", []).find { |item| item.is_a?(Hash) && item["id"] == step_id }
+  return nil unless step
+
+  render = lambda do |value|
+    value.gsub("{feature}", state["current_feature"].to_s).gsub("{phase}", state["current_phase"].to_s)
+  end
+  paths = step.fetch("outputs", []).each_with_object([]) do |item, result|
+    result << item["path"] if item.is_a?(Hash) && item["required"] == true && item["path"].is_a?(String)
+  end
+  meta = step["meta_output"]
+  paths << meta["path"] if meta.is_a?(Hash) && meta["path"].is_a?(String)
+  outputs = paths.each_with_object([]) do |raw_path, result|
+    relative = render.call(raw_path)
+    absolute = File.expand_path(relative, root)
+    next unless absolute.start_with?("#{File.realpath(root)}#{File::SEPARATOR}") && File.exist?(absolute) && File.lstat(absolute).file?
+
+    result << { "path" => relative, "sha256" => Digest::SHA256.hexdigest(File.binread(absolute)) }
+  end
+  { "id" => step_id, "label" => step["label"].to_s, "outputs" => outputs }
+rescue StandardError
+  nil
+end
+
 root = Dir.pwd
 state_path, = DevflowControlIO.resolve_control_path(root, ".devflow/planning/STATE.md", :state)
+carry = nil
+if options[:carry_file]
+  begin
+    carry = load_carry(options[:carry_file])
+  rescue JSON::ParserError, SystemCallError
+    puts JSON.pretty_generate(fail_result("invalid_carry"))
+    exit 1
+  end
+end
 result = catch(:transition_done) do
   lock = DevflowControlIO.acquire_project_lock(root)
   begin
@@ -149,6 +206,9 @@ result = catch(:transition_done) do
         "artifact_registry" => ".devflow/planning/artifacts/index.yaml"
       }
     }
+    previous_step = previous_step_payload(root, state)
+    payload["previous_step"] = previous_step if previous_step
+    payload["carry"] = carry if options[:carry_file]
     serialized = JSON.generate(payload) + "\n"
     digest = Digest::SHA256.hexdigest(serialized)
     if options[:write]

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

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Read-only startup preflight shared by every workflow execution entry path."""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+import review_preflight
+
+
+SCOPE = "startup_preflight_only_not_gate_approval"
+
+
+def render_path(value: str, feature: str, phase: str) -> str:
+    return value.replace("{feature}", feature).replace("{phase}", phase)
+
+
+def read_handoff(root: Path, relative: str, evidence: list[dict], issues: list[dict]) -> dict:
+    try:
+        handoff_path = review_preflight.within(root, relative)
+        payload = json.loads(handoff_path.read_text(encoding="utf-8"))
+        if not isinstance(payload, dict):
+            raise ValueError("handoff must be a JSON object")
+    except (OSError, ValueError, TypeError, json.JSONDecodeError) as error:
+        issues.append({"code": "HANDOFF_UNAVAILABLE", "detail": str(error), "path": relative})
+        return {}
+
+    previous = payload.get("previous_step")
+    if isinstance(previous, dict):
+        outputs = previous.get("outputs", [])
+        if isinstance(outputs, list):
+            for item in outputs:
+                if not isinstance(item, dict) or not isinstance(item.get("path"), str):
+                    continue
+                output_relative = item["path"]
+                try:
+                    output_path = review_preflight.within(root, output_relative)
+                except ValueError:
+                    issues.append({"code": "PREVIOUS_OUTPUT_MISSING", "path": output_relative})
+                    continue
+                if not output_path.is_file():
+                    issues.append({"code": "PREVIOUS_OUTPUT_MISSING", "path": output_relative})
+                elif item.get("sha256") != review_preflight.sha256(output_path):
+                    issues.append({"code": "PREVIOUS_OUTPUT_CHANGED", "path": output_relative})
+                else:
+                    evidence.append({"kind": "previous_output", "path": output_relative,
+                                     "sha256": item.get("sha256")})
+    return {
+        **({"previous_step": payload["previous_step"]} if "previous_step" in payload else {}),
+        **({"carry": payload["carry"]} if "carry" in payload else {}),
+    }
+
+
+def startup_preflight(root: Path, feature: str, step: str,
+                      contract: str | None = None, handoff: str | None = None) -> dict:
+    root = root.resolve()
+    evidence: list[dict] = []
+    issues: list[dict] = []
+    handoff_result: dict = {}
+    contract_status = "ready"
+    facts: dict = {"feature": feature}
+    try:
+        if handoff:
+            handoff_result = read_handoff(root, handoff, evidence, issues)
+
+        if contract:
+            contract_path = review_preflight.within(root, contract)
+            frozen = json.loads(contract_path.read_text(encoding="utf-8"))
+            if not isinstance(frozen, dict):
+                raise ValueError("contract must be a JSON object")
+            contract_result = review_preflight.preflight(
+                root, feature, step, contract, [], None, None, "entry"
+            )
+            evidence.extend(contract_result.get("evidence", []))
+            issues.extend(contract_result.get("issues", []))
+            contract_status = contract_result.get("status", "human_confirmation")
+            facts["allowed_paths"] = frozen.get("allowed_paths", [])
+            facts["contract_id"] = frozen.get("contract_id", "")
+
+        state = review_preflight.load_state(
+            review_preflight.within(root, ".devflow/planning/STATE.md")
+        )
+        phase = str(state.get("current_phase", ""))
+        facts["phase"] = phase
+        workflow_relative = state.get("workflow_config")
+        if not isinstance(workflow_relative, str):
+            raise ValueError("STATE workflow_config is unavailable")
+        workflow = review_preflight.load_workflow(review_preflight.within(root, workflow_relative))
+        steps = workflow.get("steps", [])
+        if not isinstance(steps, list):
+            raise ValueError("workflow steps must be an array")
+        step_index = next(
+            (index for index, item in enumerate(steps)
+             if isinstance(item, dict) and item.get("id") == step),
+            None,
+        )
+        if step_index is None:
+            issues.append({"code": "STEP_UNAVAILABLE", "detail": f"workflow step {step} is unavailable"})
+        else:
+            definition = steps[step_index]
+            step_fact = {
+                "id": step,
+                "label": definition.get("label", step),
+                "skill": definition.get("skill", ""),
+            }
+            description = definition.get("description", definition.get("summary"))
+            if isinstance(description, str) and description:
+                step_fact["description"] = description
+            facts["step"] = step_fact
+            facts["progress"] = {"index": step_index + 1, "total": len(steps)}
+            input_facts = []
+            for raw in 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 = bool(raw.get("required", True) and raw.get("required_at_entry", True))
+                else:
+                    continue
+                rendered = render_path(relative, feature, phase)
+                try:
+                    exists = review_preflight.within(root, rendered).is_file()
+                except ValueError:
+                    exists = False
+                input_facts.append({"path": rendered, "required": required, "exists": exists})
+            facts["inputs"] = input_facts
+            facts["outputs"] = [
+                render_path(item["path"], feature, phase)
+                for item in definition.get("outputs", [])
+                if isinstance(item, dict) and item.get("required") is True
+                and isinstance(item.get("path"), str)
+            ]
+    except Exception as error:
+        issues.append({"code": "STARTUP_PREFLIGHT_INPUT_UNAVAILABLE", "detail": str(error)})
+
+    status = (
+        "core_contract_conflict" if contract_status == "core_contract_conflict"
+        else "human_confirmation" if issues
+        else "ready"
+    )
+    return {
+        "status": status,
+        "scope": SCOPE,
+        "facts": facts,
+        "handoff": handoff_result,
+        "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")
+    parser.add_argument("--handoff")
+    args = parser.parse_args()
+    result = startup_preflight(args.root, args.feature, args.step, args.contract, args.handoff)
+    print(json.dumps(result, ensure_ascii=False, sort_keys=True))
+    return 0 if result["status"] == "ready" else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -55,6 +55,11 @@ module WorkflowStateValidator
     runtime_integrity_error
     acceptance_tests_not_passed
     acceptance_tests_empty
+    acceptance_test_suite_freeze_failed
+    acceptance_test_suite_freeze_attestation_invalid
+    acceptance_test_suite_freeze_attestation_failed
+    acceptance_test_suite_candidate_binding_failed
+    acceptance_test_suite_freeze_recovery_failed
   ].freeze
 
   def self.hard_validation_code?(code)