@guanlin4924/devflow-pi 0.1.15 → 0.1.17

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

@@ -0,0 +1,256 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Core-derived human view of graph facts. This renderer owns neither the
+# workload/decision truth nor a free-text assessment: delete it and the same
+# inputs reproduce it. It deliberately does not write a selection on behalf of
+# an agent.
+require "digest"
+require "json"
+require "optparse"
+require_relative "architecture_feasibility"
+require_relative "control_io"
+
+module ArchitectureBrief
+  ROOT = ".planning/features"
+  SCHEMA_VERSION = 1
+
+  module_function
+
+  def paths(root, feature)
+    raise ArgumentError, "invalid feature" unless RequirementGraph.valid_feature?(feature)
+
+    directory = File.expand_path(File.join(ROOT, feature), root)
+    root_real = File.realpath(root)
+    raise ArgumentError, "architecture brief path escapes project root" unless directory.start_with?("#{root_real}#{File::SEPARATOR}")
+    [directory, File.join(directory, "architecture-brief.md"), File.join(directory, "architecture-brief.meta.json")]
+  end
+
+  def read_meta(path)
+    return { "brief_revision" => 0 } unless File.file?(path)
+
+    data = JSON.parse(File.read(path))
+    raise ArgumentError, "architecture brief meta is invalid" unless data.is_a?(Hash) && data["brief_revision"].is_a?(Integer)
+
+    data
+  rescue JSON::ParserError
+    raise ArgumentError, "architecture brief meta is invalid"
+  end
+
+  def text(value)
+    value.to_s.gsub("|", "\\|").gsub("\n", " ")
+  end
+
+  def connected_architecture_decisions(graph)
+    decisions = Array(graph["nodes"]).select { |node| RequirementGraph.architecture_option_decision?(node) }
+    decisions.select do |decision|
+      Array(graph["edges"]).any? do |edge|
+        edge.is_a?(Hash) && edge["to"] == decision["id"] && %w[informs_decision constrains_decision].include?(edge["relation"])
+      end
+    end
+  end
+
+  def connected_architecture_risks(graph)
+    risks = Array(graph["nodes"]).select { |node| RequirementGraph.architecture_option_risk?(node) }
+    risks.select do |risk|
+      Array(graph["edges"]).any? do |edge|
+        edge.is_a?(Hash) && edge["to"] == risk["id"] && edge["relation"] == "has_architecture_risk"
+      end
+    end
+  end
+
+  def comparison_status(assessment, decisions, risks)
+    return "not_required" if assessment["level"] == "not_triggered"
+    return "missing" if decisions.empty?
+    return "awaiting_user_confirmation" if decisions.any? { |decision| decision["status"] != "confirmed" }
+    if assessment["level"] == "full"
+      return "missing_risk" if risks.empty?
+      return "awaiting_risk_confirmation" if risks.any? { |risk| risk["status"] != "confirmed" }
+    end
+
+    "confirmed"
+  end
+
+  def render_markdown(graph, assessment, decisions, risks, comparison)
+    workload_shapes = Array(graph["nodes"]).select { |node| node["kind"] == "workload_shape" }
+    constraints = Array(graph["nodes"]).select { |node| node["kind"] == "workload_constraint" }
+    lines = [
+      "# 架构评估简报：#{graph["feature"]}",
+      "",
+      "> 本文由 Core 从需求图谱和静态上下文快照派生。它不是生产拓扑、实时容量或监控结论；删除后可用同一 revision 重建。",
+      "",
+      "## 固定输入",
+      "",
+      "- 需求图谱：schema v#{graph["schema_version"]} / revision #{graph["revision"]}",
+      "- 静态上下文：#{assessment.dig("static_context", "available") ? "snapshot #{assessment.dig("static_context", "snapshot_revision")}（#{assessment.dig("static_context", "path")}）" : "缺失或无效"}",
+      "- 推导状态：#{assessment["assessment_status"]}",
+      "- 评估级别：#{assessment["level"]}",
+      "- 方案比较状态：#{comparison}",
+      "",
+      "## 触发事实",
+      ""
+    ]
+    if assessment["triggers"].empty?
+      lines << "- 未从已确认的 P2 工作负载节点观察到触发项。此结论不等于不存在所有架构风险。"
+    else
+      assessment["triggers"].each { |trigger| lines << "- `#{trigger["code"]}` — #{trigger["node_id"]}" }
+    end
+
+    lines.concat(["", "## 工作负载形态", "", "| 节点 | 状态 | 执行 | 操作 | 扇出 | 数据影响 | 外部调用 |", "|---|---|---|---|---|---|---|"])
+    if workload_shapes.empty?
+      lines << "| — | — | — | — | — | — | — |"
+    else
+      workload_shapes.each do |node|
+        facts = node.fetch("data", {}).fetch("facts", {})
+        lines << "| #{node["id"]} | #{node["status"]} | #{text(facts["execution"])} | #{text(facts["operation"])} | #{text(facts["fanout"])} | #{text(facts["data_effect"])} | #{text(Array(facts["external_calls"]).join(", "))} |"
+      end
+    end
+
+    lines.concat(["", "## 工作负载约束", "", "| 节点 | 状态 | 指标 | 来源状态 | 目标或缺口 |", "|---|---|---|---|---|"])
+    if constraints.empty?
+      lines << "| — | — | — | — | — |"
+    else
+      constraints.each do |node|
+        data = node.fetch("data", {})
+        target = if data["source_status"] == "unknown"
+                   unknown = data.fetch("unknown", {})
+                   "unknown: #{text(unknown["reason"])}（#{text(unknown["required_before"])} 前处理）"
+                 else
+                   value = data.fetch("target", {})
+                   "#{text(value["value"])} #{text(value["unit"])} / #{text(value["window"])}"
+                 end
+        lines << "| #{node["id"]} | #{node["status"]} | #{text(data["metric"])} | #{text(data["source_status"])} | #{target} |"
+      end
+    end
+
+    lines.concat(["", "## 方案比较（DECISION 派生）", ""])
+    if decisions.empty?
+      lines << "- 尚无与工作负载事实连接的架构方案比较 DECISION。"
+    else
+      decisions.each do |decision|
+        comparison_data = decision.dig("data", "comparison") || {}
+        lines << "### #{decision["id"]}（#{decision["status"]}）"
+        lines << ""
+        lines << "- 模式：#{comparison_data["mode"]}"
+        lines << "- 用户确认的推荐：#{comparison_data["recommendation_option_id"]}" if decision["status"] == "confirmed"
+        lines << "- 候选推荐：#{comparison_data["recommendation_option_id"]}" unless decision["status"] == "confirmed"
+        lines << ""
+        lines << "| 选项 | 机制 | 事实引用 | 放弃/代价 |"
+        lines << "|---|---|---|---|"
+        Array(comparison_data["options"]).each do |option|
+          lines << "| #{text(option["option_key"])} | #{text(option["mechanism"])} | #{text(Array(option["fact_refs"]).join(", "))} | #{text(Array(option["tradeoffs"]).join("；"))} |"
+        end
+        lines << ""
+      end
+    end
+
+    lines.concat(["## 架构风险（RISK 派生）", "", "| 节点 | 状态 | 失败模式 | 影响 | 处理 | 负责人 / 复核条件 |", "|---|---|---|---|---|---|"])
+    if risks.empty?
+      lines << "| — | — | — | — | — | — |"
+    else
+      risks.each do |risk|
+        data = risk.fetch("data", {})
+        lines << "| #{risk["id"]} | #{risk["status"]} | #{text(data["failure_mode"])} | #{text(data["impact"])} | #{text(data["treatment"])}: #{text(data["mitigation"])} | #{text(data["owner"])} / #{text(data["review_condition"])} |"
+      end
+    end
+
+    lines.concat(["## 未决项", ""])
+    if assessment["unresolved"].empty?
+      lines << "- 无 Core 推导的未决输入。"
+    else
+      assessment["unresolved"].each do |item|
+        suffix = item.reject { |key, _| key == "code" }.map { |key, value| "#{key}=#{text(value)}" }.join("；")
+        lines << "- `#{item["code"]}`#{suffix.empty? ? "" : " — #{suffix}"}"
+      end
+    end
+
+    lines.concat(["", "## 边界", ""] + assessment["limitations"].map { |item| "- #{item}" })
+    lines.join("\n") + "\n"
+  end
+
+  def build(root, feature)
+    graph, = RequirementGraph.load_graph(root, feature)
+    assessment = ArchitectureFeasibility.assessment(graph, ArchitectureFeasibility.safe_static_context(root))
+    decisions = connected_architecture_decisions(graph)
+    risks = connected_architecture_risks(graph)
+    comparison = comparison_status(assessment, decisions, risks)
+    markdown = render_markdown(graph, assessment, decisions, risks, comparison)
+    source = {
+      "graph_revision" => graph["revision"],
+      "graph_schema_version" => graph["schema_version"],
+      "static_context_snapshot_revision" => assessment.dig("static_context", "snapshot_revision"),
+      "assessment_status" => assessment["assessment_status"],
+      "assessment_level" => assessment["level"],
+      "trigger_codes" => assessment["triggers"].map { |item| item["code"] },
+      "unresolved_codes" => assessment["unresolved"].map { |item| item["code"] },
+      "comparison_status" => comparison,
+      "decision_ids" => decisions.map { |node| node["id"] },
+      "confirmed_decision_ids" => decisions.select { |node| node["status"] == "confirmed" }.map { |node| node["id"] },
+      "risk_ids" => risks.map { |node| node["id"] },
+      "confirmed_risk_ids" => risks.select { |node| node["status"] == "confirmed" }.map { |node| node["id"] }
+    }
+    [graph, assessment, source, markdown]
+  end
+
+  def inspect(root, feature)
+    _directory, _markdown, meta = paths(root, feature)
+    current = read_meta(meta)
+    { "ok" => true, "brief_revision" => current["brief_revision"], "meta" => current }
+  end
+
+  def write(root, feature, expected_revision)
+    directory, markdown_path, meta_path = paths(root, feature)
+    existing = read_meta(meta_path)
+    actual = existing["brief_revision"]
+    return { "ok" => false, "reason" => "stale_brief_revision", "expected_revision" => expected_revision, "actual_revision" => actual } unless actual == expected_revision
+
+    _graph, _assessment, source, markdown = build(root, feature)
+    source_fingerprint = Digest::SHA256.hexdigest(JSON.generate(source))
+    if existing["source_fingerprint"] == source_fingerprint && File.file?(markdown_path)
+      return { "ok" => true, "reused" => true, "brief_revision" => actual, "path" => File.join(ROOT, feature, "architecture-brief.md"), "meta_path" => File.join(ROOT, feature, "architecture-brief.meta.json"), "meta" => existing }
+    end
+
+    revision = actual + 1
+    meta = source.merge(
+      "schema_version" => SCHEMA_VERSION,
+      "origin" => "core_architecture_brief",
+      "feature" => feature,
+      "brief_revision" => revision,
+      "source_fingerprint" => source_fingerprint,
+      "content_sha256" => Digest::SHA256.hexdigest(markdown)
+    )
+    DevflowControlIO.atomic_write(markdown_path, markdown)
+    DevflowControlIO.atomic_write(meta_path, JSON.pretty_generate(meta) + "\n")
+    { "ok" => true, "reused" => false, "brief_revision" => revision, "path" => File.join(ROOT, feature, "architecture-brief.md"), "meta_path" => File.join(ROOT, feature, "architecture-brief.meta.json"), "meta" => meta }
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  options = { feature: nil, expected_brief_revision: nil, write: false }
+  command = ARGV.shift
+  OptionParser.new do |opts|
+    opts.banner = "Usage: architecture_brief.rb inspect|render --feature NAME [options]"
+    opts.on("--feature NAME") { |value| options[:feature] = value }
+    opts.on("--expected-brief-revision N", Integer) { |value| options[:expected_brief_revision] = value }
+    opts.on("--write") { options[:write] = true }
+    opts.on("--json") {}
+  end.parse!
+  root = Dir.pwd
+  lock = command == "render" && options[:write] ? DevflowControlIO.acquire_project_lock(root) : nil
+  begin
+    result = case command
+             when "inspect" then ArchitectureBrief.inspect(root, options[:feature])
+             when "render"
+               raise ArgumentError, "--write is required" unless options[:write]
+               raise ArgumentError, "--expected-brief-revision is required" if options[:expected_brief_revision].nil?
+               ArchitectureBrief.write(root, options[:feature], options[:expected_brief_revision])
+             else
+               { "ok" => false, "reason" => "invalid_command", "message" => "command must be inspect or render" }
+             end
+  rescue ArgumentError => error
+    result = { "ok" => false, "reason" => "architecture_brief_failed", "message" => error.message }
+  ensure
+    DevflowControlIO.release_lock(lock)
+  end
+  puts JSON.pretty_generate(result)
+end

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

@@ -0,0 +1,155 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# P2 candidate-only validator. It deliberately validates only the shapes an
+# agent may propose; confirmation, persistence, ID assignment, and gate
+# decisions remain Core responsibilities in later slices.
+require "json"
+require "optparse"
+require "time"
+
+module ArchitectureConstraints
+  EXECUTIONS = %w[sync async scheduled].freeze
+  OPERATIONS = %w[read write batch_read batch_write].freeze
+  FANOUTS = %w[none bounded unbounded unknown].freeze
+  DATA_EFFECTS = %w[none update append_only migration unknown].freeze
+  METRICS = %w[peak_qps data_growth p95_latency rpo rto].freeze
+  SOURCE_STATUSES = %w[measured contracted approved_assumption unknown].freeze
+  EVIDENCE_KINDS = %w[source_file cp_record external_measurement].freeze
+  ASSUMPTION_FIELDS = %w[owner observability_metric review_date escalation_trigger].freeze
+  UNKNOWN_FIELDS = %w[reason resolution_owner required_before].freeze
+
+  module_function
+
+  def present?(value)
+    !value.to_s.strip.empty?
+  end
+
+  def reference?(value, prefixes)
+    value.to_s.match?(Regexp.new("\\A(?:#{prefixes.join("|")})-\\d+\\z"))
+  end
+
+  def errors_for_enum(errors, object, key, values)
+    value = object[key].to_s
+    errors << "#{key} is required" if value.empty?
+    errors << "invalid #{key}" if !value.empty? && !values.include?(value)
+  end
+
+  # The public CLI is deliberately candidate-only.  Core-owned persistence
+  # needs to revalidate the same shape after it adds its own confirmation
+  # envelope, so it can opt into accepting the graph-owned status field.
+  def validate_shape(shape, allow_confirmed: false)
+    errors = []
+    errors << "feature is required" unless present?(shape["feature"])
+    refs = shape["behavior_refs"]
+    errors << "behavior_refs must be a non-empty array" unless refs.is_a?(Array) && !refs.empty?
+    Array(refs).each { |ref| errors << "behavior_refs must reference BEH" unless reference?(ref, ["BEH"]) }
+    errors_for_enum(errors, shape.fetch("facts", {}), "execution", EXECUTIONS) if shape["facts"].is_a?(Hash)
+    errors << "facts is required" unless shape["facts"].is_a?(Hash)
+    facts = shape["facts"].is_a?(Hash) ? shape["facts"] : {}
+    errors_for_enum(errors, facts, "operation", OPERATIONS)
+    errors_for_enum(errors, facts, "fanout", FANOUTS)
+    errors_for_enum(errors, facts, "data_effect", DATA_EFFECTS)
+    external_calls = facts["external_calls"]
+    errors << "external_calls must be an array" unless external_calls.nil? || external_calls.is_a?(Array)
+    source_refs = shape["source_refs"]
+    errors << "source_refs must be a non-empty array" unless source_refs.is_a?(Array) && !source_refs.empty?
+    Array(source_refs).each { |ref| errors << "source_refs must reference REQ/BEH/API" unless reference?(ref, %w[REQ BEH API]) }
+    allowed_statuses = allow_confirmed ? %w[candidate confirmed] : %w[candidate]
+    errors << "candidate shapes cannot set status confirmed" if !allow_confirmed && shape["status"].to_s == "confirmed"
+    errors << "invalid status" if present?(shape["status"]) && !allowed_statuses.include?(shape["status"])
+    errors.uniq
+  end
+
+  def valid_target?(target)
+    target.is_a?(Hash) && target["value"].is_a?(Numeric) && target["value"].positive? && present?(target["unit"]) && present?(target["window"])
+  end
+
+  def validate_evidence(errors, evidence)
+    unless evidence.is_a?(Hash)
+      errors << "evidence is required"
+      return
+    end
+    errors_for_enum(errors, evidence, "kind", EVIDENCE_KINDS)
+    errors << "evidence.ref is required" unless present?(evidence["ref"])
+    return unless evidence["kind"] == "source_file"
+
+    errors << "source_file evidence.git_revision is required" unless present?(evidence["git_revision"])
+    errors << "source_file evidence.sha256 must be a SHA-256 hex digest" unless evidence["sha256"].to_s.match?(/\A[0-9a-f]{64}\z/i)
+  end
+
+  def validate_assumption(errors, assumption)
+    unless assumption.is_a?(Hash)
+      errors << "assumption is required"
+      return
+    end
+    ASSUMPTION_FIELDS.each { |field| errors << "approved_assumption requires #{field}" unless present?(assumption[field]) }
+    Time.iso8601(assumption["review_date"].to_s) if present?(assumption["review_date"])
+  rescue ArgumentError
+    errors << "approved_assumption review_date must be ISO-8601"
+  end
+
+  def validate_unknown(errors, unknown)
+    unless unknown.is_a?(Hash)
+      errors << "unknown is required"
+      return
+    end
+    UNKNOWN_FIELDS.each { |field| errors << "unknown requires #{field}" unless present?(unknown[field]) }
+  end
+
+  def validate_constraint(constraint, allow_confirmed: false)
+    errors = []
+    errors << "feature is required" unless present?(constraint["feature"])
+    errors << "workload_ref must reference BEH/SL/API" unless reference?(constraint["workload_ref"], %w[BEH SL API])
+    errors_for_enum(errors, constraint, "metric", METRICS)
+    errors_for_enum(errors, constraint, "source_status", SOURCE_STATUSES)
+    allowed_statuses = allow_confirmed ? %w[candidate confirmed] : %w[candidate]
+    errors << "candidate constraints cannot set status confirmed" if !allow_confirmed && constraint["status"].to_s == "confirmed"
+    errors << "invalid status" if present?(constraint["status"]) && !allowed_statuses.include?(constraint["status"])
+
+    case constraint["source_status"]
+    when "measured", "contracted"
+      errors << "target requires positive numeric value, unit, and window" unless valid_target?(constraint["target"])
+      validate_evidence(errors, constraint["evidence"])
+      errors << "unknown is only valid for source_status unknown" if constraint.key?("unknown")
+    when "approved_assumption"
+      errors << "target requires positive numeric value, unit, and window" unless valid_target?(constraint["target"])
+      validate_assumption(errors, constraint["assumption"])
+      errors << "unknown is only valid for source_status unknown" if constraint.key?("unknown")
+    when "unknown"
+      errors << "unknown constraints must not contain target" if constraint.key?("target")
+      errors << "unknown constraints must not contain evidence" if constraint.key?("evidence")
+      errors << "unknown constraints must not contain assumption" if constraint.key?("assumption")
+      validate_unknown(errors, constraint["unknown"])
+    end
+    errors.uniq
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  options = { shape_json: nil, constraint_json: nil }
+  command = ARGV.shift
+  OptionParser.new do |o|
+    o.on("--shape-json JSON") { |value| options[:shape_json] = value }
+    o.on("--constraint-json JSON") { |value| options[:constraint_json] = value }
+    o.on("--json") {}
+  end.parse!
+  begin
+    result =
+      case command
+      when "validate-shape"
+        raise ArgumentError, "--shape-json is required" unless options[:shape_json]
+        errors = ArchitectureConstraints.validate_shape(JSON.parse(options[:shape_json]))
+        { "ok" => errors.empty?, "errors" => errors }
+      when "validate-constraint"
+        raise ArgumentError, "--constraint-json is required" unless options[:constraint_json]
+        errors = ArchitectureConstraints.validate_constraint(JSON.parse(options[:constraint_json]))
+        { "ok" => errors.empty?, "errors" => errors }
+      else
+        raise ArgumentError, "command must be validate-shape or validate-constraint"
+      end
+  rescue StandardError => error
+    result = { "ok" => false, "reason" => "architecture_constraints_failed", "message" => error.message }
+  end
+  puts JSON.pretty_generate(result)
+end

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

@@ -0,0 +1,176 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Read-only P2 trigger derivation. It never claims a repository declaration is
+# production capacity, never chooses an option, and never persists a decision.
+# Its sole job is to turn already-confirmed graph facts into a reproducible
+# assessment level and an honest list of unresolved inputs for the next skill.
+require "json"
+require "optparse"
+require "pathname"
+require_relative "requirement_graph"
+require_relative "static_runtime_context_collector"
+
+module ArchitectureFeasibility
+  LEVELS = { "not_triggered" => 0, "lightweight" => 1, "full" => 2 }.freeze
+  STATIC_POINTER = StaticRuntimeContextCollector::POINTER
+
+  module_function
+
+  def promote(level, candidate)
+    LEVELS.fetch(candidate) > LEVELS.fetch(level) ? candidate : level
+  end
+
+  def safe_static_context(root)
+    pointer_path = File.join(root, STATIC_POINTER)
+    return { "available" => false, "code" => "ARC_STATIC_CONTEXT_MISSING" } unless File.file?(pointer_path)
+
+    pointer = JSON.parse(File.read(pointer_path))
+    relative = pointer.fetch("path")
+    raise ArgumentError, "static runtime-context pointer path is invalid" unless relative.is_a?(String) && relative.start_with?(".context/static-runtime-context/revisions/")
+
+    absolute = File.expand_path(relative, root)
+    root_real = File.realpath(root)
+    raise ArgumentError, "static runtime-context pointer escapes project root" unless absolute.start_with?("#{root_real}#{File::SEPARATOR}")
+
+    snapshot = JSON.parse(File.read(absolute))
+    revision = snapshot["snapshot_revision"]
+    raise ArgumentError, "static runtime-context snapshot revision is invalid" unless revision.is_a?(Integer) && revision.positive?
+    raise ArgumentError, "static runtime-context pointer revision does not match snapshot" unless pointer["current_revision"] == revision
+    raise ArgumentError, "static runtime-context snapshot schema is unsupported" unless snapshot["schema_version"] == StaticRuntimeContextCollector::SCHEMA_VERSION
+
+    {
+      "available" => true,
+      "path" => relative,
+      "snapshot_revision" => revision,
+      "repository_revision" => snapshot["repository_revision"],
+      "coverage" => Array(snapshot["coverage"]).map { |item| item.slice("subject_class", "status", "rule") }
+    }
+  rescue JSON::ParserError, KeyError => error
+    { "available" => false, "code" => "ARC_STATIC_CONTEXT_INVALID", "detail" => error.message }
+  end
+
+  def valid_confirmed_workload?(graph, node)
+    node["status"] == "confirmed" && RequirementGraph.workload_node_errors(
+      graph, node, require_edges: true, require_confirmed_inputs: true
+    ).empty?
+  end
+
+  def assessment(graph, static_context)
+    level = "not_triggered"
+    triggers = []
+    unresolved = []
+    graph_errors = RequirementGraph.validate(graph)
+    Array(graph["nodes"]).each do |node|
+      next unless node.is_a?(Hash) && %w[workload_shape workload_constraint].include?(node["kind"])
+
+      if node["status"] != "confirmed"
+        level = promote(level, "lightweight")
+        unresolved << { "code" => "ARC_WORKLOAD_CANDIDATE_UNCONFIRMED", "node_id" => node["id"] }
+        next
+      end
+      unless valid_confirmed_workload?(graph, node)
+        level = promote(level, "lightweight")
+        unresolved << { "code" => "ARC_WORKLOAD_CONFIRMED_BUT_INVALID", "node_id" => node["id"] }
+        next
+      end
+
+      data = node.fetch("data")
+      if node["kind"] == "workload_shape"
+        facts = data.fetch("facts")
+        case facts["data_effect"]
+        when "migration"
+          level = promote(level, "full")
+          triggers << { "code" => "ARC_DATA_MIGRATION", "node_id" => node["id"] }
+        end
+        case facts["fanout"]
+        when "unbounded"
+          level = promote(level, "full")
+          triggers << { "code" => "ARC_UNBOUNDED_FANOUT", "node_id" => node["id"] }
+        when "bounded"
+          level = promote(level, "lightweight")
+          triggers << { "code" => "ARC_BOUNDED_FANOUT", "node_id" => node["id"] }
+        when "unknown"
+          level = promote(level, "lightweight")
+          unresolved << { "code" => "ARC_FANOUT_UNKNOWN", "node_id" => node["id"] }
+        end
+        case facts["execution"]
+        when "async"
+          level = promote(level, "lightweight")
+          triggers << { "code" => "ARC_ASYNC_EXECUTION", "node_id" => node["id"] }
+        when "scheduled"
+          level = promote(level, "lightweight")
+          triggers << { "code" => "ARC_SCHEDULED_EXECUTION", "node_id" => node["id"] }
+        end
+        if %w[batch_read batch_write].include?(facts["operation"])
+          level = promote(level, "lightweight")
+          triggers << { "code" => "ARC_BATCH_OPERATION", "node_id" => node["id"] }
+        end
+        if Array(facts["external_calls"]).any?
+          level = promote(level, "lightweight")
+          triggers << { "code" => "ARC_EXTERNAL_CALL", "node_id" => node["id"] }
+        end
+      else
+        if data["source_status"] == "unknown"
+          level = promote(level, "lightweight")
+          unresolved << { "code" => "ARC_CONSTRAINT_UNKNOWN", "node_id" => node["id"], "required_before" => data.dig("unknown", "required_before") }
+        else
+          level = promote(level, "lightweight")
+          triggers << { "code" => "ARC_WORKLOAD_CONSTRAINT", "node_id" => node["id"], "metric" => data["metric"], "source_status" => data["source_status"] }
+        end
+      end
+    end
+
+    unless static_context["available"]
+      unresolved << { "code" => static_context["code"], "detail" => static_context["detail"] }.compact
+    end
+    workload_errors = graph_errors.grep(/\A(?:WSH|WLC)-/)
+    unresolved << { "code" => "ARC_WORKLOAD_GRAPH_INVALID", "count" => workload_errors.length } if workload_errors.any?
+
+    # P2 deliberately uses no numeric threshold. A numeric constraint is a
+    # reason to compare alternatives, not evidence that a made-up "high load"
+    # threshold has been crossed.
+    status = unresolved.empty? ? "ready" : "incomplete"
+    required_follow_up =
+      case level
+      when "full" then %w[option_comparison decision risk]
+      when "lightweight" then %w[option_comparison]
+      else []
+      end
+    {
+      "ok" => true,
+      "origin" => "core_architecture_feasibility",
+      "feature" => graph["feature"],
+      "graph_revision" => graph["revision"],
+      "graph_schema_version" => graph["schema_version"],
+      "static_context" => static_context,
+      "assessment_status" => status,
+      "level" => level,
+      "triggers" => triggers.uniq,
+      "unresolved" => unresolved.uniq,
+      "required_follow_up" => required_follow_up,
+      "limitations" => [
+        "Static context records repository declarations/references only; it is not production topology, health, or capacity.",
+        "This derivation does not select an implementation option or accept a risk.",
+        "P0 dependency-delta assessment remains a separate input until the combined evaluator is implemented."
+      ]
+    }
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  options = { feature: nil }
+  OptionParser.new do |opts|
+    opts.banner = "Usage: architecture_feasibility.rb assess --feature NAME --json"
+    opts.on("--feature NAME") { |value| options[:feature] = value }
+    opts.on("--json") {}
+  end.parse!
+
+  begin
+    root = Dir.pwd
+    graph, = RequirementGraph.load_graph(root, options[:feature])
+    puts JSON.pretty_generate(ArchitectureFeasibility.assessment(graph, ArchitectureFeasibility.safe_static_context(root)))
+  rescue ArgumentError => error
+    puts JSON.pretty_generate({ "ok" => false, "reason" => "architecture_feasibility_failed", "message" => error.message })
+  end
+end

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

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 require "fileutils"
+require "json"
 require "pathname"
 require "securerandom"
 
@@ -81,4 +82,49 @@ module DevflowControlIO
   ensure
     File.delete(temporary) if temporary && File.exist?(temporary)
   end
+
+  # Create-once counterpart to atomic_write. Control artifacts that represent
+  # a human confirmation or a historical revision must never be silently
+  # replaced. The hard-link publish step is atomic and fails when the final
+  # name already exists.
+  def atomic_create(path, content)
+    directory = File.dirname(path)
+    FileUtils.mkdir_p(directory)
+    temporary = File.join(directory, ".#{File.basename(path)}.#{Process.pid}.#{SecureRandom.hex(6)}.tmp")
+
+    File.open(temporary, File::WRONLY | File::CREAT | File::EXCL, 0o644) do |file|
+      file.write(content)
+      file.flush
+      file.fsync
+    end
+    File.link(temporary, path)
+  rescue Errno::EEXIST
+    raise InvalidControlPath, "refusing to overwrite immutable control artifact: #{path}"
+  ensure
+    File.delete(temporary) if temporary && File.exist?(temporary)
+  end
+
+  # Callers hold the project lock while appending. JSONL keeps a durable,
+  # append-only audit trail without turning the current pointer into history.
+  def append_audit(path, entry)
+    FileUtils.mkdir_p(File.dirname(path))
+    File.open(path, File::WRONLY | File::CREAT | File::APPEND, 0o644) do |file|
+      file.write(JSON.generate(entry) + "\n")
+      file.flush
+      file.fsync
+    end
+  end
+
+  # 独立受控工件登记：与 sync_artifacts 的 workflow-outputs registry 分开，
+  # 避免被 workflow 重建覆盖。按 path 去重，last-write-wins。
+  def register_control_artifact(root, entry)
+    path = File.join(root, ".planning", "artifacts", "control-artifacts.json")
+    existing = File.exist?(path) ? JSON.parse(File.read(path)) : { "schema_version" => 1, "artifacts" => [] }
+    existing["artifacts"] ||= []
+    existing["artifacts"].reject! { |item| item["path"] == entry["path"] }
+    existing["artifacts"] << entry
+    atomic_write(path, JSON.pretty_generate(existing) + "\n")
+  rescue JSON::ParserError
+    atomic_write(path, JSON.pretty_generate({ "schema_version" => 1, "artifacts" => [entry] }) + "\n")
+  end
 end