@guanlin4924/devflow-pi 0.1.38 → 0.1.40

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

@@ -0,0 +1,148 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Validates the existing workflow topology as a GateContract source.  This is
+# intentionally declarative and read-only: it does not advance STATE or alter
+# failure-branch behavior.
+require "json"
+require "optparse"
+require "yaml"
+require_relative "checker_registry"
+
+module WorkflowGateContract
+  CHECKPOINT_FIELDS = %w[gate_after producing_step required_outputs required_meta_output required_meta_fields prompt confirm_options skip_policy resume_behavior].freeze
+
+  module_function
+
+  def validate(workflow)
+    errors = []
+    unless workflow.is_a?(Hash)
+      return [error("WORKFLOW_SCHEMA_INVALID", "workflow must be a mapping")]
+    end
+    steps = Array(workflow["steps"])
+    step_by_id = steps.each_with_object({}) { |step, index| index[step["id"].to_s] = step if step.is_a?(Hash) && step["id"] }
+    checkpoints = workflow["checkpoints"]
+    unless checkpoints.is_a?(Hash)
+      return [error("CHECKPOINTS_SCHEMA_INVALID", "workflow checkpoints must be a mapping")]
+    end
+    checkpoints.each do |id, checkpoint|
+      unless checkpoint.is_a?(Hash)
+        errors << error("CHECKPOINT_SCHEMA_INVALID", "checkpoint must be a mapping", checkpoint: id)
+        next
+      end
+      CHECKPOINT_FIELDS.each do |field|
+        errors << error("CHECKPOINT_FIELD_MISSING", "checkpoint field is required", checkpoint: id, field: field) unless checkpoint.key?(field)
+      end
+      errors << error("CHECKPOINT_PRODUCER_MISMATCH", "gate_after must equal producing_step", checkpoint: id) if checkpoint["gate_after"].to_s != checkpoint["producing_step"].to_s
+      errors << error("CHECKPOINT_OUTPUTS_INVALID", "required_outputs must be an array", checkpoint: id) unless checkpoint["required_outputs"].is_a?(Array)
+      errors << error("CHECKPOINT_META_FIELDS_INVALID", "required_meta_fields must be an array", checkpoint: id) unless checkpoint["required_meta_fields"].is_a?(Array)
+      errors << error("CHECKPOINT_OPTIONS_INVALID", "confirm_options must include approve and needs_fix", checkpoint: id) unless Array(checkpoint["confirm_options"]).sort == %w[approve needs_fix]
+    end
+
+    Array(workflow.dig("governance", "enforced_checkpoints")).each do |id|
+      errors << error("CHECKPOINT_REF_NOT_FOUND", "enforced checkpoint is not defined", checkpoint: id) unless checkpoints.key?(id)
+    end
+
+    step_checkers = workflow.dig("governance", "step_checkers")
+    if step_checkers.is_a?(Hash)
+      step_checkers.each do |step_id, checker_ids|
+        errors << error("CHECKER_STEP_REF_NOT_FOUND", "checker declaration references an unknown step", step: step_id) unless step_by_id.key?(step_id.to_s)
+        Array(checker_ids).each do |checker_id|
+          errors << error("UNKNOWN_CHECKER_ID", "workflow references an unknown checker", step: step_id, checker: checker_id) unless CheckerRegistry.known?(checker_id)
+        end
+      end
+    end
+
+    Array(workflow["parallel_windows"]).each do |window|
+      unless window.is_a?(Hash) && window["join_step"] && window["branches"].is_a?(Hash)
+        errors << error("PARALLEL_WINDOW_SCHEMA_INVALID", "parallel window must define join_step and branches", window: window.is_a?(Hash) && window["id"])
+        next
+      end
+      window_id = window["id"]
+      errors << error("PARALLEL_AFTER_STEP_NOT_FOUND", "parallel window after_step is not a workflow step", window: window_id, step: window["after_step"]) if window["after_step"] && !step_by_id.key?(window["after_step"].to_s)
+      errors << error("PARALLEL_JOIN_STEP_NOT_FOUND", "parallel join_step is not a workflow step", window: window_id, step: window["join_step"]) unless step_by_id.key?(window["join_step"].to_s)
+      errors << error("PARALLEL_WINDOW_CHECKPOINT_INVALID", "parallel join checkpoint is not defined", window: window["id"], checkpoint: window["checkpoint"]) if window["checkpoint"] && !checkpoints.key?(window["checkpoint"])
+      policy = window["execution_policy"]
+      scheduler = policy.is_a?(Hash) && policy["scheduler"]
+      unless scheduler.is_a?(Hash)
+        errors << error("PARALLEL_SCHEDULER_SCHEMA_INVALID", "parallel window must define execution_policy.scheduler", window: window_id)
+      else
+        errors << error("PARALLEL_SCHEDULER_FIELD_INVALID", "one_agent_per_step must be boolean", window: window_id, field: "one_agent_per_step") unless [true, false].include?(scheduler["one_agent_per_step"])
+        errors << error("PARALLEL_SCHEDULER_FIELD_INVALID", "max_concurrency must be a positive integer", window: window_id, field: "max_concurrency") unless scheduler["max_concurrency"].is_a?(Integer) && scheduler["max_concurrency"] > 0
+        errors << error("PARALLEL_SCHEDULER_FIELD_INVALID", "track_order must be declared", window: window_id, field: "track_order") unless scheduler["track_order"] == "declared"
+      end
+      errors << error("PARALLEL_BRANCH_STEPS_INVALID", "branch_steps must be an array", window: window_id) if window.key?("branch_steps") && !window["branch_steps"].is_a?(Array)
+      Array(window["branch_steps"]).each do |step_id|
+        errors << error("PARALLEL_BRANCH_STEP_NOT_FOUND", "branch_steps references an unknown step", window: window_id, step: step_id) unless step_by_id.key?(step_id.to_s)
+      end
+      branch_ids = []
+      step_tracks = {}
+      window["branches"].each do |track, branch_steps|
+        unless branch_steps.is_a?(Array) && !branch_steps.empty?
+          errors << error("PARALLEL_TRACK_STEPS_INVALID", "parallel track must contain an ordered step array", window: window_id, track: track)
+          next
+        end
+        positions = branch_steps.each_with_index.to_h { |step_id, position| [step_id.to_s, position] }
+        branch_steps.each_with_index do |step_id, position|
+          if positions.count { |candidate, _| candidate == step_id.to_s } > 1
+            errors << error("PARALLEL_TRACK_DUPLICATE_STEP", "parallel track repeats a step", window: window_id, track: track, step: step_id)
+          end
+          branch_ids << step_id.to_s
+          step_tracks[step_id.to_s] = track.to_s
+          errors << error("PARALLEL_BRANCH_STEP_NOT_FOUND", "parallel track references an unknown step", window: window_id, track: track, step: step_id) unless step_by_id.key?(step_id.to_s)
+          Array(step_by_id.dig(step_id.to_s, "depends_on")).each do |dependency|
+            dependency_position = positions[dependency.to_s]
+            next unless dependency_position
+            errors << error("PARALLEL_TRACK_ORDER_INVALID", "track dependency must precede dependent step", window: window_id, track: track, step: step_id, dependency: dependency) if dependency_position >= position
+          end
+        end
+      end
+      window["branches"].each do |track, branch_steps|
+        Array(branch_steps).each do |step_id|
+          Array(step_by_id.dig(step_id.to_s, "depends_on")).each do |dependency|
+            dependency_track = step_tracks[dependency.to_s]
+            next unless dependency_track && dependency_track != track.to_s
+
+            errors << error("PARALLEL_CROSS_TRACK_DEPENDENCY", "parallel branch depends on a step in another track", window: window_id, track: track, step: step_id, dependency: dependency, dependency_track: dependency_track)
+          end
+        end
+      end
+      counts = branch_ids.each_with_object(Hash.new(0)) { |step_id, result| result[step_id] += 1 }
+      duplicate_steps = counts.select { |_, count| count > 1 }.keys
+      duplicate_steps.each { |step_id| errors << error("PARALLEL_STEP_DUPLICATED", "step appears in multiple parallel branches", window: window_id, step: step_id) }
+      errors << error("PARALLEL_JOIN_IN_BRANCH", "join_step cannot also be a branch step", window: window_id, step: window["join_step"]) if branch_ids.include?(window["join_step"].to_s)
+    end
+
+    (workflow["failure_branches"] || {}).each do |source_step, branch|
+      errors << error("FAILURE_SOURCE_STEP_NOT_FOUND", "failure branch source step is not defined", source_step: source_step) unless step_by_id.key?(source_step.to_s)
+      errors << error("FAILURE_BRANCH_SCHEMA_INVALID", "failure branch must be a mapping", source_step: source_step) unless branch.is_a?(Hash)
+      resume = branch.is_a?(Hash) && branch["resume_after_success"]
+      unless resume.is_a?(Hash) && %w[flow step status checkpoint].all? { |field| resume.key?(field) }
+        errors << error("FAILURE_RETURN_TO_INVALID", "failure branch must declare flow, step, status and checkpoint", source_step: source_step)
+        next
+      end
+      errors << error("FAILURE_RETURN_CHECKPOINT_INVALID", "failure branch return checkpoint is not defined", source_step: source_step, checkpoint: resume["checkpoint"]) unless checkpoints.key?(resume["checkpoint"])
+    end
+    errors
+  end
+
+  def error(code, message, **extra)
+    { "code" => code, "message" => message }.merge(extra)
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+  options = {}
+  OptionParser.new do |opts|
+    opts.on("--workflow PATH") { |value| options[:workflow] = value }
+    opts.on("--json") { options[:json] = true }
+  end.parse!
+  raise ArgumentError, "--workflow is required" unless options[:workflow]
+  result = WorkflowGateContract.validate(YAML.safe_load(File.read(options[:workflow]), permitted_classes: [], aliases: false))
+  puts(options[:json] ? JSON.generate(result) : YAML.dump(result))
+  rescue StandardError => e
+    warn e.message
+    exit 1
+  end
+end

package/plugins/devflow-core/skills/workflow-orchestrator/templates/feature-development.yaml

@@ -17,12 +17,15 @@ phase_scope:
 # files without governance_started_revision remain legacy_unattested and are
 # only reported until their next newly-started governed step.
 governance:
+  gate_contract_version: 3
   requirement_graph_gate: enforced
+  requirement_coverage_gate: enforced
   enforced_checkpoints:
     - CP-1
     - CP-API
     - CP-2
     - CP-3
+    - CP-4
   step_checkers:
     requirement-baseline:
       - requirement-graph-check
@@ -42,6 +45,7 @@ governance:
       - slice-independence-check
       - contract-coverage-check
       - change-impact-check
+      - cross-track-consistency-check
     acceptance-test-design:
       - requirement-graph-check
       - contract-coverage-check
@@ -120,6 +124,10 @@ parallel_windows:
     checkpoint: CP-2
     execution_policy:
       mode: parallel_when_supported
+      scheduler:
+        one_agent_per_step: true
+        max_concurrency: 2
+        track_order: declared
       serial_fallback_order:
         - backend-tech-spec
         - api-call-guide
@@ -311,6 +319,7 @@ checkpoints:
     producing_step: run-acceptance-tests
     required_outputs:
       - ".planning/test-runs/{feature}/acceptance-results.json"
+    required_meta_output: ".planning/test-runs/{feature}/acceptance-results.meta.json"
     required_meta_fields:
       - acceptance_tc_passed
       - acceptance_tc_failed
@@ -365,6 +374,7 @@ steps:
     order: 6
     label: Requirement wayfinder
     skill: workflow-wayfinder
+    engine_evidence_gate: enforced
     depends_on:
       - requirement-triage
     inputs:
@@ -392,6 +402,7 @@ steps:
     order: 7
     label: Domain modeling
     skill: workflow-domain-modeling
+    engine_evidence_gate: enforced
     depends_on:
       - requirement-wayfinder
     inputs:
@@ -417,6 +428,7 @@ steps:
     order: 8
     label: Requirement feasibility review
     skill: requirement-feasibility-review
+    engine_evidence_gate: enforced
     depends_on:
       - domain-modeling
     inputs:
@@ -443,6 +455,7 @@ steps:
     order: 10
     label: Requirement baseline
     skill: workflow-requirement-baseline
+    engine_evidence_gate: enforced
     depends_on:
       - requirement-feasibility-review
     inputs:
@@ -478,6 +491,7 @@ steps:
     order: 15
     label: API contract
     skill: workflow-api-contract
+    engine_evidence_gate: enforced
     depends_on:
       - requirement-baseline
     inputs:
@@ -504,6 +518,7 @@ steps:
     order: 18
     label: Architecture feasibility
     skill: workflow-architecture-feasibility
+    engine_evidence_gate: enforced
     depends_on:
       - api-contract
     inputs:
@@ -535,6 +550,7 @@ steps:
     order: 20
     label: UI spec
     skill: workflow-ui-spec
+    engine_evidence_gate: enforced
     depends_on:
       - api-contract
       - architecture-feasibility
@@ -551,6 +567,7 @@ steps:
     order: 30
     label: Feature breakdown
     skill: workflow-feature-breakdown
+    engine_evidence_gate: enforced
     depends_on:
       - ui-spec
     inputs:
@@ -565,6 +582,7 @@ steps:
     order: 40
     label: Frontend tech spec
     skill: workflow-frontend-tech-spec
+    engine_evidence_gate: enforced
     depends_on:
       - feature-breakdown
       - api-contract
@@ -598,6 +616,7 @@ steps:
     order: 50
     label: Backend tech spec
     skill: workflow-backend-tech-spec
+    engine_evidence_gate: enforced
     depends_on:
       - api-contract
       - architecture-feasibility
@@ -625,6 +644,7 @@ steps:
     order: 55
     label: API call guide
     skill: workflow-api-call-guide
+    engine_evidence_gate: enforced
     depends_on:
       - api-contract
       - backend-tech-spec
@@ -649,6 +669,7 @@ steps:
     order: 56
     label: API supplement
     skill: workflow-api-supplement
+    engine_evidence_gate: enforced
     depends_on:
       - frontend-tech-spec
       - api-contract
@@ -672,6 +693,7 @@ steps:
     order: 58
     label: Integration verify
     skill: workflow-integration-verify
+    engine_evidence_gate: enforced
     depends_on:
       - api-call-guide
       - frontend-tech-spec
@@ -702,6 +724,7 @@ steps:
     order: 60
     label: Change plan
     skill: workflow-change-plan
+    engine_evidence_gate: enforced
     depends_on:
       - acceptance-test-design
     inputs:
@@ -735,6 +758,7 @@ steps:
     order: 59
     label: Acceptance test design
     skill: workflow-acceptance-test-design
+    engine_evidence_gate: enforced
     depends_on:
       - integration-verify
     inputs:
@@ -774,6 +798,7 @@ steps:
     order: 70
     label: Phase structure
     action: initialize-phase-structure
+    engine_evidence_gate: enforced
     depends_on:
       - change-plan
     inputs:
@@ -791,6 +816,7 @@ steps:
     order: 80
     label: Execute
     skill: workflow-execute-phase
+    engine_evidence_gate: enforced
     depends_on:
       - phase-structure
     inputs:
@@ -835,6 +861,7 @@ steps:
     order: 85
     label: Code Review
     skill: code-review
+    engine_evidence_gate: enforced
     depends_on:
       - code-index-refresh
     inputs:
@@ -849,6 +876,7 @@ steps:
     order: 86
     label: Generate mainflow cases
     skill: workflow-generate-mainflow-cases
+    engine_evidence_gate: enforced
     depends_on:
       - code-index-refresh
     inputs:
@@ -887,6 +915,7 @@ steps:
     order: 88
     label: Run frozen acceptance tests
     skill: workflow-run-acceptance-tests
+    engine_evidence_gate: enforced
     depends_on:
       - code-review
     inputs:

package/src/constants.ts

@@ -1,5 +1,5 @@
 export const PRODUCT_NAME = "Devflow Pi";
-export const PRODUCT_VERSION = "0.1.38";
+export const PRODUCT_VERSION = "0.1.40";
 export const PROJECT_SCHEMA_VERSION = 1;
 export const OMP_RUNTIME_VERSION = "17.2.7";
 

package/src/runtime.ts

@@ -36,12 +36,18 @@ const MANAGED_SETTINGS: Record<string, unknown> = {
   "skills.enableAgentsProject": false,
   // The interactive session is the high-capability Planner. Low-cost agents
   // are dispatched only through explicit Devflow steps, one at a time by
-  // default, so background work cannot silently widen a user's request.
+  // default, so background work cannot silently widen a user's request.  The
+  // parallel workflow window is explicitly capped at two workers, matching
+  // its two declared tracks; serial workflows are unaffected.
   // Keep ordinary interactive turns on the user's DEFAULT role. In particular,
   // do not inherit SLOW just because a thinking model is configured.
   "defaultThinkingLevel": "low",
+  // Parallel Devflow orchestration relies on OMP's AsyncJobManager and
+  // subagent lifecycle channel. Keep this explicit instead of inheriting the
+  // SDK default so a global OMP config cannot silently disable it.
+  "async.enabled": true,
   "task.batch": false,
-  "task.maxConcurrency": 1,
+  "task.maxConcurrency": 2,
   "task.maxRecursionDepth": 1,
   "task.enableLsp": true,
   // Keep cheap workers bounded by role prompts. OMP's loop guards remain