@guanlin4924/devflow-pi 0.1.40 → 0.1.47

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

@@ -0,0 +1,570 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Core-owned deterministic aggregate/canonical builder. It never makes a
+# semantic choice: differing definitions remain unresolved conflicts until a
+# later runtime-confirmed adjudication applies a complete candidate delta.
+require "digest"
+require "json"
+require "open3"
+require "optparse"
+require "pathname"
+require "set"
+require "tempfile"
+require "time"
+require "yaml"
+require_relative "control_io"
+require_relative "requirement_graph"
+
+module BusinessModelCommit
+  COLLECTIONS = %w[actors entities components boundaries resources rules actions assumptions].freeze
+  REFERENCE_LISTS = %w[requirement_refs decision_refs resolved_assumption_refs].freeze
+  VALIDATOR = File.expand_path("business_model_validate.py", __dir__)
+
+  module_function
+
+  def deep_sort(value)
+    case value
+    when Hash then value.keys.sort.to_h { |key| [key, deep_sort(value[key])] }
+    when Array then value.map { |item| deep_sort(item) }
+    else value
+    end
+  end
+
+  def fingerprint(value)
+    "sha256:#{Digest::SHA256.hexdigest(JSON.generate(deep_sort(value)))}"
+  end
+
+  def valid_feature?(feature)
+    RequirementGraph.valid_feature?(feature)
+  end
+
+  def feature_dir(root, feature)
+    raise ArgumentError, "invalid feature" unless valid_feature?(feature)
+
+    root_real = File.realpath(root)
+    relative = File.join(".planning", "business-model", feature)
+    absolute = File.expand_path(relative, root_real)
+    raise ArgumentError, "business model path escapes project root" unless absolute.start_with?("#{root_real}#{File::SEPARATOR}")
+
+    cursor = root_real
+    relative.split(File::SEPARATOR).each do |segment|
+      cursor = File.join(cursor, segment)
+      next unless File.symlink?(cursor)
+
+      resolved = File.realpath(cursor)
+      raise ArgumentError, "business model path escapes through symlink" unless resolved == root_real || resolved.start_with?("#{root_real}#{File::SEPARATOR}")
+    end
+
+    absolute
+  end
+
+  def proposal_path(root, feature, raw)
+    root_real = File.realpath(root)
+    value = raw.to_s
+    raise ArgumentError, "proposal path is required" if value.empty?
+    raise ArgumentError, "proposal path must be project-relative" if Pathname.new(value).absolute?
+    raise ArgumentError, "proposal path contains control characters" if value.match?(/[\x00-\x1F\x7F]/)
+
+    normalized = Pathname.new(value).cleanpath.to_s.tr("\\", "/")
+    prefix = File.join(".planning", "business-model", feature, "proposals").tr("\\", "/") + "/"
+    raise ArgumentError, "proposal path is outside the feature proposal directory" unless normalized.start_with?(prefix)
+    absolute = File.expand_path(normalized, root_real)
+    raise ArgumentError, "proposal path escapes project root" unless absolute.start_with?("#{root_real}#{File::SEPARATOR}")
+    raise ArgumentError, "proposal file is missing" unless File.file?(absolute)
+
+    cursor = root_real
+    normalized.split("/").each do |segment|
+      cursor = File.join(cursor, segment)
+      next unless File.symlink?(cursor)
+
+      resolved = File.realpath(cursor)
+      raise ArgumentError, "proposal path escapes through symlink" unless resolved == root_real || resolved.start_with?("#{root_real}#{File::SEPARATOR}")
+    end
+    [absolute, normalized]
+  end
+
+  def proposal_paths(root, feature, requested)
+    if requested.empty?
+      directory = File.join(feature_dir(root, feature), "proposals")
+      requested = Dir.glob(File.join(directory, "*.{yaml,yml,json}")).sort.map do |path|
+        Pathname.new(path).relative_path_from(Pathname.new(File.realpath(root))).to_s
+      end
+    end
+    raise ArgumentError, "at least one proposal is required" if requested.empty?
+
+    requested.map { |raw| proposal_path(root, feature, raw) }.sort_by { |_absolute, relative| relative }
+  end
+
+  def validate_proposal(absolute, relative, feature)
+    stdout, stderr, status = Open3.capture3("python3", VALIDATOR, "--proposal", absolute)
+    payload = JSON.parse(stdout)
+    unless status.success? && payload["valid"] == true
+      details = Array(payload["errors"]).map { |error| error["code"] }.uniq.join(", ")
+      raise ArgumentError, "proposal #{relative} is invalid: #{details.empty? ? stderr.strip : details}"
+    end
+    canonical = payload.fetch("canonical")
+    raise ArgumentError, "proposal #{relative} feature does not match" unless canonical["feature"] == feature
+
+    { "path" => relative, "fingerprint" => payload.fetch("canonical_fingerprint"), "model" => canonical }
+  rescue JSON::ParserError => e
+    raise ArgumentError, "proposal validator returned invalid JSON for #{relative}: #{e.message}"
+  end
+
+  def grouped_alternatives(entries, field)
+    groups = {}
+    entries.each do |entry|
+      present = entry["value"].key?(field)
+      value = present ? entry["value"][field] : nil
+      key = fingerprint({ "present" => present, "value" => value })
+      groups[key] ||= { "present" => present, "value" => value, "proposal_refs" => [] }
+      groups[key]["proposal_refs"] << entry["proposal_ref"]
+    end
+    groups.values.each { |item| item["proposal_refs"].sort! }
+    groups.values.sort_by { |item| fingerprint(item) }
+  end
+
+  def conflict_id(subject, field)
+    "CONFLICT-#{subject}-#{field}".gsub(/[^A-Za-z0-9_-]/, "-")
+  end
+
+  def merge_collection(collection, proposals, conflicts)
+    by_id = {}
+    proposals.each do |proposal|
+      Array(proposal["model"][collection]).each do |value|
+        id = value["id"].to_s
+        by_id[id] ||= []
+        by_id[id] << { "value" => value, "proposal_ref" => "#{proposal['path']}##{id}" }
+      end
+    end
+    merged = []
+    # Proposal files are sorted before union. Preserve the first appearance of
+    # every ID so business-order arrays remain semantic and fingerprint-stable;
+    # sorting IDs here would silently rewrite the model.
+    by_id.keys.each do |id|
+      entries = by_id[id]
+      variants = entries.group_by { |entry| fingerprint(entry["value"]) }
+      if variants.length == 1
+        merged << entries.first["value"]
+        next
+      end
+      fields = entries.flat_map { |entry| entry["value"].keys }.uniq.sort
+      fields.each do |field|
+        alternatives = grouped_alternatives(entries, field)
+        next if alternatives.length == 1
+
+        conflicts << {
+          "id" => conflict_id(id, field),
+          "subject_ref" => id,
+          "collection" => collection,
+          "field" => field,
+          "alternatives" => alternatives,
+          "status" => "unresolved"
+        }
+      end
+      # The whole subject stays out of merged while any field differs. This
+      # prevents an incomplete hybrid object from looking canonical.
+    end
+    merged
+  end
+
+  def detect_cross_collection_ids(proposals, conflicts)
+    locations = {}
+    proposals.each do |proposal|
+      COLLECTIONS.each do |collection|
+        Array(proposal["model"][collection]).each do |value|
+          id = value["id"].to_s
+          locations[id] ||= {}
+          locations[id][collection] ||= []
+          locations[id][collection] << "#{proposal['path']}##{id}"
+        end
+      end
+    end
+    collisions = Set.new
+    locations.each do |id, collections|
+      next unless collections.length > 1
+
+      collisions << id
+      conflicts << {
+        "id" => conflict_id(id, "collection"),
+        "subject_ref" => id,
+        "collection" => "cross_collection",
+        "field" => "collection",
+        "alternatives" => collections.keys.sort.map { |collection| { "present" => true, "value" => collection, "proposal_refs" => collections[collection].uniq.sort } },
+        "status" => "unresolved"
+      }
+    end
+    collisions
+  end
+
+  def build_aggregate_payload(feature, proposals, revision)
+    conflicts = []
+    merged = {
+      "schema_version" => 1,
+      "feature" => feature
+    }
+    collisions = detect_cross_collection_ids(proposals, conflicts)
+    COLLECTIONS.each do |collection|
+      merged[collection] = merge_collection(collection, proposals, conflicts).reject { |value| collisions.include?(value["id"].to_s) }
+    end
+    REFERENCE_LISTS.each do |key|
+      merged[key] = proposals.flat_map { |proposal| Array(proposal["model"][key]) }.uniq
+    end
+    source_registry_groups = proposals.group_by { |proposal| proposal["model"]["source_registry_ref"] }
+    source_registry_refs = source_registry_groups.keys
+    if source_registry_refs.length == 1
+      merged["source_registry_ref"] = source_registry_refs.first
+    else
+      conflicts << {
+        "id" => "CONFLICT-BUSINESS-MODEL-source_registry_ref",
+        "subject_ref" => "BUSINESS-MODEL",
+        "collection" => "root",
+        "field" => "source_registry_ref",
+        "alternatives" => source_registry_refs.sort.map do |value|
+          { "present" => true, "value" => value, "proposal_refs" => source_registry_groups[value].map { |proposal| proposal["path"] }.sort }
+        end,
+        "status" => "unresolved"
+      }
+    end
+    proposal_meta = proposals.map { |proposal| proposal.slice("path", "fingerprint") }
+    payload = {
+      "schema_version" => 1,
+      "feature" => feature,
+      "revision" => revision,
+      "proposal_set_fingerprint" => fingerprint(proposal_meta),
+      "proposals" => proposal_meta,
+      "merged" => merged,
+      "conflicts" => conflicts.sort_by { |conflict| conflict["id"] }
+    }
+    payload["content_fingerprint"] = fingerprint(payload.reject { |key, _| %w[revision content_fingerprint].include?(key) })
+    payload
+  end
+
+  def load_existing_aggregate(path, feature)
+    return nil unless File.file?(path)
+
+    value = JSON.parse(File.read(path))
+    valid = value.is_a?(Hash) && value["schema_version"] == 1 && value["feature"] == feature && value["revision"].is_a?(Integer)
+    raise ArgumentError, "invalid existing aggregate" unless valid
+
+    value
+  rescue JSON::ParserError
+    raise ArgumentError, "invalid existing aggregate"
+  end
+
+  def load_delta(root, feature, raw)
+    raise ArgumentError, "candidate delta path is required" if raw.to_s.empty?
+    path = File.expand_path(raw, root)
+    feature_root = File.expand_path(File.join(".planning", "business-model", feature, "candidates"), root)
+    raise ArgumentError, "candidate delta is missing" unless File.file?(path)
+    path = File.realpath(path)
+    feature_root = File.realpath(feature_root)
+    raise ArgumentError, "candidate delta must be inside the feature candidate directory" unless path.start_with?("#{feature_root}#{File::SEPARATOR}")
+    value = YAML.safe_load(File.read(path), permitted_classes: [], aliases: false)
+    raise ArgumentError, "candidate delta must be a mapping" unless value.is_a?(Hash)
+    required = %w[schema_version feature aggregate_revision aggregate_fingerprint source_registry_fingerprint conflict_ids assumption_ids proposed_by operations]
+    missing = required.reject { |key| value.key?(key) }
+    raise ArgumentError, "candidate delta missing #{missing.join(', ')}" unless missing.empty?
+    raise ArgumentError, "candidate delta schema_version is invalid" unless value["schema_version"] == 1
+    raise ArgumentError, "candidate delta feature mismatch" unless value["feature"] == feature
+    raise ArgumentError, "candidate delta must target a conflict or assumption" if Array(value["conflict_ids"]).empty? && Array(value["assumption_ids"]).empty?
+    operations = Array(value["operations"])
+    raise ArgumentError, "candidate delta operations are required" if operations.empty?
+    operations.each_with_index do |operation, index|
+      raise ArgumentError, "candidate delta operation #{index} must be a mapping" unless operation.is_a?(Hash)
+      %w[op collection target_id].each { |key| raise ArgumentError, "candidate delta operation #{index} missing #{key}" if operation[key].to_s.empty? }
+      raise ArgumentError, "candidate delta operation #{index} has invalid op" unless %w[add replace remove].include?(operation["op"].to_s)
+      raise ArgumentError, "candidate delta operation #{index} has invalid collection" unless COLLECTIONS.include?(operation["collection"].to_s)
+      if %w[add replace].include?(operation["op"].to_s)
+        value_object = operation["value"]
+        raise ArgumentError, "candidate delta operation #{index} requires a complete value object" unless value_object.is_a?(Hash) && value_object["id"].to_s == operation["target_id"].to_s
+      elsif operation.key?("value") && !operation["value"].nil?
+        raise ArgumentError, "remove operation cannot carry a value"
+      end
+    end
+    [value, Pathname.new(path).relative_path_from(Pathname.new(File.realpath(root))).to_s]
+  rescue Psych::Exception => e
+    raise ArgumentError, "invalid candidate delta YAML: #{e.message}"
+  end
+
+  def source_registry_fingerprint(root, feature, aggregate)
+    registry_ref = aggregate.dig("merged", "source_registry_ref").to_s
+    return "" if registry_ref.empty?
+    path = if registry_ref.start_with?(".planning/")
+             File.expand_path(registry_ref, root)
+           else
+             File.expand_path(registry_ref, feature_dir(root, feature))
+           end
+    return "" unless File.file?(path)
+    "sha256:#{Digest::SHA256.file(path).hexdigest}"
+  end
+
+  def load_canonical(root, feature)
+    path = File.join(feature_dir(root, feature), "canonical.json")
+    raise ArgumentError, "canonical is missing" unless File.file?(path)
+    value = JSON.parse(File.read(path))
+    raise ArgumentError, "canonical feature mismatch" unless value.is_a?(Hash) && value["feature"] == feature
+    [path, value]
+  rescue JSON::ParserError => e
+    raise ArgumentError, "invalid canonical JSON: #{e.message}"
+  end
+
+  def canonical_fingerprint_from_python(root, path)
+    Tempfile.create(["business-meta", ".json"]) do |output|
+      stdout, stderr, status = Open3.capture3("python3", VALIDATOR, "--proposal", path, "--canonical-out", output.path)
+      payload = JSON.parse(stdout)
+      raise ArgumentError, "canonical validation failed: #{stderr.strip}" unless status.success? && payload["valid"] == true
+      [payload.fetch("canonical_fingerprint"), payload.fetch("canonical")]
+    end
+  rescue JSON::ParserError => e
+    raise ArgumentError, "canonical validator returned invalid JSON: #{e.message}"
+  end
+
+  def meta(root:, feature:, expected_revision:, write:)
+    path, canonical = load_canonical(root, feature)
+    fingerprint_value, = canonical_fingerprint_from_python(root, path)
+    aggregate = load_existing_aggregate(File.join(feature_dir(root, feature), "aggregate.json"), feature)
+    aggregate_revision = aggregate ? aggregate["revision"].to_i : expected_revision.to_i
+    raise ArgumentError, "canonical revision mismatch" unless aggregate.nil? || aggregate_revision == expected_revision.to_i
+    source_fingerprint = aggregate ? source_registry_fingerprint(root, feature, aggregate) : ""
+    metadata = {
+      "schema_version" => 1,
+      "feature" => feature,
+      "prototype_fingerprint" => fingerprint_value,
+      "source_document_fingerprint" => source_fingerprint,
+      "aggregate_revision" => aggregate_revision,
+      "checker_summary" => { "structural" => "passed", "closure" => "required_before_approval" },
+      "generated_at" => Time.now.utc.iso8601
+    }
+    target = File.join(feature_dir(root, feature), "canonical.meta.json")
+    DevflowControlIO.atomic_write(target, JSON.pretty_generate(metadata) + "\n") if write
+    { "ok" => true, "action" => "meta", "meta" => metadata, "path" => relative_to_root(root, target) }
+  end
+
+  def approve(root:, feature:, expected_revision:, approved_by:, runtime_confirmed:, write:)
+    raise ArgumentError, "runtime confirmation is required" unless runtime_confirmed
+    raise ArgumentError, "approved_by is required" if approved_by.to_s.empty?
+    path, canonical = load_canonical(root, feature)
+    fingerprint_value, = canonical_fingerprint_from_python(root, path)
+    aggregate = load_existing_aggregate(File.join(feature_dir(root, feature), "aggregate.json"), feature)
+    revision = aggregate ? aggregate["revision"].to_i : expected_revision.to_i
+    raise ArgumentError, "canonical revision mismatch" unless revision == expected_revision.to_i
+    source_fingerprint = aggregate ? source_registry_fingerprint(root, feature, aggregate) : ""
+    approval = {
+      "schema_version" => 1,
+      "feature" => feature,
+      "status" => "approved",
+      "approved_by" => approved_by,
+      "approved_at" => Time.now.utc.iso8601,
+      "prototype_fingerprint" => fingerprint_value,
+      "source_document_fingerprint" => source_fingerprint,
+      "revision" => revision,
+      "canonical_screens" => [],
+      "confirmed_screens" => []
+    }
+    target = File.join(feature_dir(root, feature), "approval.json")
+    DevflowControlIO.atomic_write(target, JSON.pretty_generate(approval) + "\n") if write
+    { "ok" => true, "action" => "approve", "approval" => approval, "path" => relative_to_root(root, target) }
+  end
+
+  def approval_status(root:, feature:, expected_revision:)
+    approval_path = File.join(feature_dir(root, feature), "approval.json")
+    raise ArgumentError, "approval is missing" unless File.file?(approval_path)
+    approval = JSON.parse(File.read(approval_path))
+    canonical_path, = load_canonical(root, feature)
+    fingerprint_value, = canonical_fingerprint_from_python(root, canonical_path)
+    aggregate = load_existing_aggregate(File.join(feature_dir(root, feature), "aggregate.json"), feature)
+    source_fingerprint = aggregate ? source_registry_fingerprint(root, feature, aggregate) : ""
+    current = approval["status"] == "approved" && approval["prototype_fingerprint"] == fingerprint_value && approval["source_document_fingerprint"].to_s == source_fingerprint.to_s && approval["revision"].to_i == expected_revision.to_i
+    { "ok" => true, "action" => "approval-status", "current" => current, "approval" => approval, "actual" => { "prototype_fingerprint" => fingerprint_value, "source_document_fingerprint" => source_fingerprint, "revision" => expected_revision } }
+  rescue JSON::ParserError => e
+    raise ArgumentError, "invalid approval JSON: #{e.message}"
+  end
+
+  def write_decision(root, feature, decision)
+    path = File.join(feature_dir(root, feature), "business-decisions.json")
+    existing = if File.file?(path)
+                 JSON.parse(File.read(path))
+               else
+                 { "schema_version" => 1, "feature" => feature, "revision" => 0, "decisions" => [] }
+               end
+    existing["revision"] = existing.fetch("revision", 0).to_i + 1
+    existing["decisions"] = Array(existing["decisions"]) + [decision.merge("revision" => existing["revision"])]
+    existing["fingerprint"] = fingerprint(existing.reject { |key, _| key == "fingerprint" })
+    DevflowControlIO.atomic_write(path, JSON.pretty_generate(existing) + "\n")
+    [path, existing]
+  rescue JSON::ParserError => e
+    raise ArgumentError, "invalid business decision registry: #{e.message}"
+  end
+
+  def adjudicate(root:, feature:, expected_revision:, delta_path:, decision_id:, decided_by:, accept:, write:)
+    directory = feature_dir(root, feature)
+    aggregate_path = File.join(directory, "aggregate.json")
+    aggregate = load_existing_aggregate(aggregate_path, feature)
+    raise ArgumentError, "aggregate is missing" unless aggregate
+    delta, relative_delta = load_delta(root, feature, delta_path)
+    raise ArgumentError, "aggregate revision mismatch" unless expected_revision == aggregate["revision"]
+    raise ArgumentError, "candidate delta aggregate revision is stale" unless delta["aggregate_revision"].to_i == aggregate["revision"].to_i
+    raise ArgumentError, "candidate delta aggregate fingerprint is stale" unless delta["aggregate_fingerprint"].to_s == aggregate["content_fingerprint"].to_s
+    actual_source = source_registry_fingerprint(root, feature, aggregate)
+    if !actual_source.empty? && delta["source_registry_fingerprint"].to_s != actual_source
+      raise ArgumentError, "candidate delta source registry fingerprint is stale"
+    end
+    current_conflicts = Array(aggregate["conflicts"]).select { |item| item["status"].to_s != "resolved" }.map { |item| item["id"].to_s }
+    targeted = Array(delta["conflict_ids"]).map(&:to_s) + Array(delta["assumption_ids"]).map(&:to_s)
+    raise ArgumentError, "candidate delta targets a changed conflict set" unless (targeted & current_conflicts).sort == Array(delta["conflict_ids"]).map(&:to_s).sort
+
+    decision = {
+      "id" => decision_id.to_s,
+      "kind" => accept ? "accept_candidate_delta" : "reject_candidate_delta",
+      "decided_by" => decided_by.to_s,
+      "delta_path" => relative_delta,
+      "aggregate_revision" => aggregate["revision"],
+      "aggregate_fingerprint" => aggregate["content_fingerprint"],
+      "conflict_ids" => Array(delta["conflict_ids"]),
+      "assumption_ids" => Array(delta["assumption_ids"]),
+      "created_at" => Time.now.utc.iso8601
+    }
+    raise ArgumentError, "decision id and decided_by are required" if decision_id.to_s.empty? || decided_by.to_s.empty?
+    return { "ok" => true, "action" => "adjudicate", "changed" => false, "decision" => write_decision(root, feature, decision)[1] } unless accept
+
+    updated = JSON.parse(JSON.generate(aggregate))
+    delta["operations"].each do |operation|
+      collection = updated.fetch("merged").fetch(operation.fetch("collection"))
+      index = collection.index { |item| item["id"].to_s == operation["target_id"].to_s }
+      case operation["op"]
+      when "add"
+        raise ArgumentError, "candidate add target already exists" if index
+        collection << operation.fetch("value")
+      when "replace"
+        raise ArgumentError, "candidate replace target does not exist" unless index
+        collection[index] = operation.fetch("value")
+      when "remove"
+        raise ArgumentError, "candidate remove target does not exist" unless index
+        collection.delete_at(index)
+      end
+    end
+    updated["conflicts"].each { |conflict| conflict["status"] = "resolved" if Array(delta["conflict_ids"]).include?(conflict["id"]) }
+    updated["merged"]["assumptions"] = [] if Array(delta["assumption_ids"]).any?
+    updated["revision"] = aggregate["revision"] + 1
+    updated["content_fingerprint"] = fingerprint(updated.reject { |key, _| %w[revision content_fingerprint].include?(key) })
+    decision["resulting_aggregate_revision"] = updated["revision"]
+    if write
+      DevflowControlIO.atomic_write(aggregate_path, JSON.pretty_generate(updated) + "\n")
+      write_decision(root, feature, decision)
+    end
+    { "ok" => true, "action" => "adjudicate", "changed" => true, "aggregate" => updated, "decision" => decision, "path" => relative_to_root(root, aggregate_path) }
+  end
+
+  def aggregate(root:, feature:, expected_revision:, requested_proposals:, write:)
+    directory = feature_dir(root, feature)
+    path = File.join(directory, "aggregate.json")
+    existing = load_existing_aggregate(path, feature)
+    current_revision = existing ? existing["revision"] : 0
+    raise ArgumentError, "aggregate revision mismatch: expected #{expected_revision}, current #{current_revision}" unless expected_revision == current_revision
+
+    proposals = proposal_paths(root, feature, requested_proposals).map { |absolute, relative| validate_proposal(absolute, relative, feature) }
+    candidate = build_aggregate_payload(feature, proposals, current_revision + 1)
+    if existing && existing["content_fingerprint"] == candidate["content_fingerprint"]
+      return { "ok" => true, "action" => "aggregate", "changed" => false, "aggregate" => existing, "path" => relative_to_root(root, path) }
+    end
+    DevflowControlIO.atomic_write(path, JSON.pretty_generate(candidate) + "\n") if write
+    { "ok" => true, "action" => "aggregate", "changed" => true, "aggregate" => candidate, "path" => relative_to_root(root, path) }
+  end
+
+  def canonical(root:, feature:, expected_revision:, write:)
+    directory = feature_dir(root, feature)
+    aggregate_path = File.join(directory, "aggregate.json")
+    aggregate = load_existing_aggregate(aggregate_path, feature)
+    raise ArgumentError, "aggregate is missing" unless aggregate
+    raise ArgumentError, "aggregate revision mismatch: expected #{expected_revision}, current #{aggregate['revision']}" unless expected_revision == aggregate["revision"]
+    unresolved = Array(aggregate["conflicts"]).select { |conflict| conflict["status"] != "resolved" }
+    raise ArgumentError, "canonical build requires all conflicts to be resolved" if unresolved.any?
+
+    model = JSON.parse(JSON.generate(aggregate.fetch("merged")))
+    assumptions = Array(model.delete("assumptions"))
+    raise ArgumentError, "canonical build requires assumptions to be adjudicated by Core" if assumptions.any?
+
+    Tempfile.create(["business-canonical", ".json"]) do |proposal_file|
+      proposal_file.write(JSON.generate(model))
+      proposal_file.flush
+      Tempfile.create(["business-canonical-out", ".json"]) do |canonical_file|
+        stdout, stderr, status = Open3.capture3("python3", VALIDATOR, "--proposal", proposal_file.path, "--canonical-out", canonical_file.path)
+        payload = JSON.parse(stdout)
+        unless status.success? && payload["valid"] == true
+          details = Array(payload["errors"]).map { |error| error["code"] }.uniq.join(", ")
+          raise ArgumentError, "canonical model is invalid: #{details.empty? ? stderr.strip : details}"
+        end
+        target = File.join(directory, "canonical.json")
+        DevflowControlIO.atomic_write(target, File.read(canonical_file.path)) if write
+        return {
+          "ok" => true,
+          "action" => "canonical",
+          "canonical_fingerprint" => payload["canonical_fingerprint"],
+          "canonical" => payload["canonical"],
+          "path" => relative_to_root(root, target),
+          "aggregate_revision" => aggregate["revision"]
+        }
+      end
+    end
+  rescue JSON::ParserError => e
+    raise ArgumentError, "canonical validator returned invalid JSON: #{e.message}"
+  end
+
+  def relative_to_root(root, path)
+    Pathname.new(path).relative_path_from(Pathname.new(File.realpath(root))).to_s
+  end
+
+  def execute(root:, action:, feature:, expected_revision:, requested_proposals:, write:, delta_path: nil, decision_id: nil, decided_by: nil, accept: false, approved_by: nil, runtime_confirmed: false)
+    root = File.realpath(root)
+    lock = DevflowControlIO.acquire_project_lock(root)
+    case action
+    when "aggregate"
+      aggregate(root: root, feature: feature, expected_revision: expected_revision, requested_proposals: requested_proposals, write: write)
+    when "canonical"
+      canonical(root: root, feature: feature, expected_revision: expected_revision, write: write)
+    when "adjudicate"
+      adjudicate(root: root, feature: feature, expected_revision: expected_revision, delta_path: delta_path, decision_id: decision_id, decided_by: decided_by, accept: accept, write: write)
+    when "meta"
+      meta(root: root, feature: feature, expected_revision: expected_revision, write: write)
+    when "approve"
+      approve(root: root, feature: feature, expected_revision: expected_revision, approved_by: approved_by, runtime_confirmed: runtime_confirmed, write: write)
+    when "approval-status"
+      approval_status(root: root, feature: feature, expected_revision: expected_revision)
+    else
+      raise ArgumentError, "action must be aggregate or canonical"
+    end
+  rescue ArgumentError, DevflowControlIO::InvalidControlPath => e
+    { "ok" => false, "reason" => "business_model_commit_failed", "message" => e.message }
+  ensure
+    DevflowControlIO.release_lock(lock)
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  options = { root: ".", proposals: [], write: false, accept: false, runtime_confirmed: false }
+  OptionParser.new do |opts|
+    opts.on("--root PATH") { |value| options[:root] = value }
+    opts.on("--action ACTION") { |value| options[:action] = value }
+    opts.on("--feature NAME") { |value| options[:feature] = value }
+    opts.on("--expected-revision N", Integer) { |value| options[:expected_revision] = value }
+    opts.on("--proposal PATH") { |value| options[:proposals] << value }
+    opts.on("--delta PATH") { |value| options[:delta_path] = value }
+    opts.on("--decision-id ID") { |value| options[:decision_id] = value }
+    opts.on("--decided-by USER") { |value| options[:decided_by] = value }
+    opts.on("--accept") { options[:accept] = true }
+    opts.on("--approved-by USER") { |value| options[:approved_by] = value }
+    opts.on("--runtime-confirmed") { options[:runtime_confirmed] = true }
+    opts.on("--write") { options[:write] = true }
+    opts.on("--json") { options[:json] = true }
+  end.parse!
+  abort("--action, --feature and --expected-revision are required") unless options[:action] && options[:feature] && !options[:expected_revision].nil?
+  abort("--delta, --decision-id and --decided-by are required for adjudicate") if options[:action] == "adjudicate" && [options[:delta_path], options[:decision_id], options[:decided_by]].any?(&:nil?)
+  abort("--approved-by and --runtime-confirmed are required for approve") if options[:action] == "approve" && [options[:approved_by], options[:runtime_confirmed]].any? { |value| value == false || value.nil? }
+  payload = BusinessModelCommit.execute(
+    root: options[:root], action: options[:action], feature: options[:feature], expected_revision: options[:expected_revision],
+    requested_proposals: options[:proposals], write: options[:write], delta_path: options[:delta_path], decision_id: options[:decision_id], decided_by: options[:decided_by], accept: options[:accept], approved_by: options[:approved_by], runtime_confirmed: options[:runtime_confirmed]
+  )
+  puts JSON.pretty_generate(payload)
+  exit(payload["ok"] ? 0 : 1)
+end

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

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+require "yaml"
+require_relative "gate_result"
+
+module BusinessModelGate
+  POLICY_PATH = File.expand_path("../contracts/business-model-policy.yaml", __dir__)
+  TRANSITIONS = %w[modeling adjudicating freeze consume_downstream].freeze
+
+  module_function
+
+  def load_policy(path = POLICY_PATH)
+    value = YAML.safe_load(File.read(path), permitted_classes: [], aliases: false)
+    raise ArgumentError, "business model policy must be a mapping" unless value.is_a?(Hash)
+    transitions = Array(value["transition_kinds"])
+    raise ArgumentError, "business model policy transition kinds are invalid" unless transitions.sort == TRANSITIONS.sort
+    value
+  rescue Psych::Exception => e
+    raise ArgumentError, "invalid business model policy: #{e.message}"
+  end
+
+  def verdict_for(policy, code, transition_kind)
+    transition = transition_kind.to_s
+    raise ArgumentError, "unknown business model transition kind: #{transition}" unless TRANSITIONS.include?(transition)
+    rule = Array(policy["rules"]).find { |item| Array(item["codes"]).map(&:to_s).include?(code.to_s) }
+    (rule && rule[transition]) || policy.fetch("default").fetch(transition)
+  end
+
+  def evaluate(violations:, transition_kind:, gate_id: "business-model-closure", step_id: "business-model")
+    policy = load_policy
+    transition = transition_kind.to_s
+    raise ArgumentError, "unknown business model transition kind: #{transition}" unless TRANSITIONS.include?(transition)
+    items = Array(violations).select { |item| item.is_a?(Hash) }
+    return GateResult.allow(gate_id: gate_id, step_id: step_id, evidence: { "checker" => "business-closure-check", "violation_count" => 0 }) if items.empty?
+
+    decisions = items.map do |item|
+      code = item["code"].to_s
+      { "code" => code, "subject_ref" => item["subject_ref"], "verdict" => verdict_for(policy, code, transition_kind), "facts" => item["facts"] || {} }
+    end
+    verdict = if decisions.any? { |item| item["verdict"] == "block_unsafe" }
+                "block_unsafe"
+              else
+                "await_user"
+              end
+    errors = decisions.map do |item|
+      { "code" => item["code"], "message" => "business model closure violation", "subject_ref" => item["subject_ref"], "facts" => item["facts"] }
+    end
+    if verdict == "await_user"
+      GateResult.await_user(
+        gate_id: gate_id,
+        step_id: step_id,
+        errors: errors,
+        recovery: { "kind" => "user_adjudication", "transition_kind" => transition_kind },
+        evidence: { "checker" => "business-closure-check", "violations" => decisions },
+      )
+    else
+      GateResult.block(
+        gate_id: gate_id,
+        step_id: step_id,
+        code: "BUSINESS_MODEL_GATE_BLOCKED",
+        message: "business model cannot enter this transition",
+        details: { "violations" => errors, "transition_kind" => transition_kind },
+        evidence: { "checker" => "business-closure-check", "violations" => decisions },
+      )
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  options = { transition_kind: nil, gate_id: "business-model-closure", step_id: "business-model" }
+  OptionParser.new do |parser|
+    parser.on("--transition-kind KIND") { |value| options[:transition_kind] = value }
+    parser.on("--gate-id ID") { |value| options[:gate_id] = value }
+    parser.on("--step-id ID") { |value| options[:step_id] = value }
+  end.parse!
+
+  begin
+    raise ArgumentError, "--transition-kind is required" if options[:transition_kind].to_s.empty?
+    input = JSON.parse($stdin.read)
+    violations = input.is_a?(Array) ? input : input.fetch("violations", [])
+    puts JSON.pretty_generate(BusinessModelGate.evaluate(violations: violations, transition_kind: options[:transition_kind], gate_id: options[:gate_id], step_id: options[:step_id]))
+  rescue StandardError => error
+    puts JSON.pretty_generate(GateResult.block(gate_id: options[:gate_id], step_id: options[:step_id], code: "BUSINESS_GATE_POLICY_INVALID", message: error.message))
+    exit 1
+  end
+end