@guanlin4924/devflow-pi 0.1.16 → 0.1.18

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

@@ -0,0 +1,458 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Architecture Assessment P0: the assessment never accepts a caller-supplied
+# manifest or delta set. A user-confirmed, Core-written immutable manifest is
+# the only input besides the pinned runtime-context snapshot.
+require "digest"
+require "json"
+require "open3"
+require "optparse"
+require "pathname"
+require "set"
+require "time"
+require_relative "control_io"
+require_relative "runtime_context_collector"
+
+module ArchitectureAssessment
+  SCHEMA_VERSION = 1
+  RULE_VERSION = 1
+  ROOT_DIR = File.join(".planning", "architecture-assessment")
+
+  UNRESOLVED = {
+    DELTA_SET_BINDING_FAILED: "DELTA_SET_BINDING_FAILED",
+    BASELINE_COVERAGE_INCOMPLETE: "BASELINE_COVERAGE_INCOMPLETE",
+    DELTA_SOURCE_UNVERIFIABLE: "DELTA_SOURCE_UNVERIFIABLE"
+  }.freeze
+
+  module_function
+
+  def safe_component!(value, label)
+    text = value.to_s.strip
+    unless text.match?(/\A[\p{L}\p{N}][\p{L}\p{N}._-]{0,119}\z/u)
+      raise ArgumentError, "#{label} must be a 1-120 character path-safe identifier"
+    end
+    text
+  end
+
+  # RFC 8785-style canonical JSON for the bounded P0 data model. Every key is
+  # a String before hashing, so Ruby Hash insertion order cannot change a hash.
+  def canonical_json(value)
+    case value
+    when Hash
+      "{" + value.keys.map(&:to_s).sort.map { |key| JSON.generate(key) + ":" + canonical_json(value[key]) }.join(",") + "}"
+    when Array
+      "[" + value.map { |item| canonical_json(item) }.join(",") + "]"
+    when String
+      JSON.generate(value)
+    when Numeric
+      value.to_s
+    when true, false
+      value.to_s
+    when nil
+      "null"
+    else
+      JSON.generate(value)
+    end
+  end
+
+  def sha256(value)
+    Digest::SHA256.hexdigest(value)
+  end
+
+  def normalize_subject(value)
+    value.to_s.strip.downcase
+  end
+
+  def canonical_source(source)
+    source = source.is_a?(Hash) ? source : {}
+    {
+      "kind" => source["kind"].to_s,
+      "locator" => source["locator"].to_s,
+      "input_hash" => source["input_hash"].to_s,
+      "repository_revision" => source["repository_revision"].to_s
+    }
+  end
+
+  # Only this projection is confirmed by the user and persisted in a manifest.
+  # Model-only presentation fields such as proposer/status are deliberately
+  # omitted from the decision input.
+  def canonical_delta(delta)
+    delta = delta.is_a?(Hash) ? delta : {}
+    {
+      "op" => delta["op"].to_s,
+      "subject" => normalize_subject(delta["subject"]),
+      "source" => canonical_source(delta["source"])
+    }
+  end
+
+  def canonical_delta_hash(delta)
+    sha256(canonical_json(canonical_delta(delta)))
+  end
+
+  def stable_sorted_union(lists)
+    lists.flatten.compact.uniq.sort
+  end
+
+  def manifest_path(root, feature, delta_set_id)
+    feature = safe_component!(feature, "feature")
+    delta_set_id = safe_component!(delta_set_id, "deltaSetId")
+    File.join(root, ROOT_DIR, feature, "delta-set-manifests", "#{delta_set_id}.json")
+  end
+
+  def assessment_dir(root, feature)
+    File.join(root, ROOT_DIR, safe_component!(feature, "feature"))
+  end
+
+  def assessment_pointer_path(root, feature)
+    File.join(assessment_dir(root, feature), "current.json")
+  end
+
+  def assessment_history_path(root, feature, revision)
+    File.join(assessment_dir(root, feature), "revisions", "#{revision}.json")
+  end
+
+  def assessment_audit_path(root, feature)
+    File.join(assessment_dir(root, feature), "audit.jsonl")
+  end
+
+  def current_assessment_revision(root, feature)
+    pointer = assessment_pointer_path(root, feature)
+    return 0 unless File.exist?(pointer)
+
+    JSON.parse(File.read(pointer))["current_revision"].to_i
+  rescue JSON::ParserError
+    raise ArgumentError, "assessment pointer is invalid JSON: #{pointer}"
+  end
+
+  def parse_locator(locator)
+    path, anchor = locator.to_s.split("#", 2)
+    path = path.to_s.strip
+    anchor = anchor.to_s.strip
+    raise ArgumentError, "source locator must be project-relative path#heading" if path.empty? || anchor.empty?
+    raise ArgumentError, "source locator cannot be absolute" if Pathname.new(path).absolute?
+    normalized = Pathname.new(path).cleanpath.to_s.tr("\\", "/")
+    raise ArgumentError, "source locator cannot traverse parent directories" if normalized == ".." || normalized.start_with?("../")
+    [normalized, anchor]
+  end
+
+  def git_capture(root, *args)
+    stdout, stderr, status = Open3.capture3("git", "-C", root, *args)
+    [stdout, stderr, status.success?]
+  end
+
+  def markdown_section(content, anchor)
+    lines = content.lines
+    target = anchor.to_s.strip
+    start = nil
+    level = nil
+    lines.each_with_index do |line, index|
+      match = line.match(/\A(#+)\s+(.+?)\s*\z/)
+      next unless match
+
+      title = match[2].sub(/\s+#+\s*\z/, "").strip
+      next unless title == target
+
+      start = index
+      level = match[1].length
+      break
+    end
+    return nil unless start
+
+    finish = lines.length
+    ((start + 1)...lines.length).each do |index|
+      match = lines[index].match(/\A(#+)\s+/)
+      next unless match && match[1].length <= level
+
+      finish = index
+      break
+    end
+    lines[start...finish].join
+  end
+
+  # Proves the source claim by loading the exact Git object, resolving the
+  # declared Markdown section, and comparing its bytes to input_hash.
+  def source_valid?(root, source)
+    source = canonical_source(source)
+    return false if source.values.any?(&:empty?)
+
+    path, anchor = parse_locator(source["locator"])
+    _stdout, _stderr, commit_exists = git_capture(root, "cat-file", "-e", "#{source["repository_revision"]}^{commit}")
+    return false unless commit_exists
+
+    content, _show_error, shown = git_capture(root, "show", "#{source["repository_revision"]}:#{path}")
+    return false unless shown
+
+    section = markdown_section(content, anchor)
+    !section.nil? && sha256(section) == source["input_hash"]
+  rescue ArgumentError
+    false
+  end
+
+  def validate_delta(delta, expected_source_revision: nil)
+    errors = []
+    errors << "delta must be an object" unless delta.is_a?(Hash)
+    return errors unless delta.is_a?(Hash)
+
+    safe_component!(delta["id"], "delta id")
+    errors << "delta #{delta["id"]}: only require_runtime_dep is supported in P0" unless delta["op"] == "require_runtime_dep"
+    errors << "delta #{delta["id"]}: subject is required" if normalize_subject(delta["subject"]).empty?
+    source = canonical_source(delta["source"])
+    errors << "delta #{delta["id"]}: source kind is required" if source["kind"].empty?
+    errors << "delta #{delta["id"]}: source locator is required" if source["locator"].empty?
+    errors << "delta #{delta["id"]}: source input_hash is required" if source["input_hash"].empty?
+    errors << "delta #{delta["id"]}: source repository_revision is required" if source["repository_revision"].empty?
+    if expected_source_revision && source["repository_revision"] != expected_source_revision
+      errors << "delta #{delta["id"]}: source repository_revision does not match source_bundle_revision"
+    end
+    errors
+  rescue ArgumentError => error
+    errors << error.message
+    errors
+  end
+
+  def read_manifest(root, feature, delta_set_id)
+    path = manifest_path(root, feature, delta_set_id)
+    raise ArgumentError, "confirmed delta-set manifest not found: #{path}" unless File.exist?(path)
+
+    [JSON.parse(File.read(path)), path]
+  rescue JSON::ParserError
+    raise ArgumentError, "confirmed delta-set manifest is invalid JSON: #{path}"
+  end
+
+  def manifest_errors(manifest, feature, delta_set_id)
+    errors = []
+    attestation = manifest["attestation"].is_a?(Hash) ? manifest["attestation"] : {}
+    errors << "manifest feature mismatch" unless manifest["feature"] == feature
+    errors << "manifest delta_set_id mismatch" unless manifest["delta_set_id"] == delta_set_id
+    errors << "manifest attestation.verified_by must be core" unless attestation["verified_by"] == "core"
+    errors << "manifest attestation.method must be ui_confirm" unless attestation["method"] == "ui_confirm"
+    errors << "manifest attestation.principal must be interactive-user" unless attestation["principal"] == "interactive-user"
+    errors << "manifest attestation.confirmed_at is missing" if attestation["confirmed_at"].to_s.empty?
+    source_bundle_revision = manifest["source_bundle_revision"].to_s
+    errors << "manifest source_bundle_revision is missing" if source_bundle_revision.empty?
+    items = Array(manifest["items"])
+    ids = items.map { |item| item.is_a?(Hash) ? item["id"] : nil }
+    errors << "manifest item ids are duplicated" unless ids.compact.uniq.length == ids.length && ids.none?(&:nil?)
+    items.each do |item|
+      unless item.is_a?(Hash)
+        errors << "manifest item must be an object"
+        next
+      end
+      delta = item["canonical_delta"]
+      errors.concat(validate_delta(delta, expected_source_revision: source_bundle_revision))
+      errors << "#{item["id"]}: id does not match canonical delta" unless delta.is_a?(Hash) && item["id"] == delta["id"]
+      expected_hash = delta.is_a?(Hash) ? canonical_delta_hash(delta) : nil
+      errors << "#{item["id"]}: canonical_delta_hash mismatch" unless item["canonical_delta_hash"] == expected_hash
+    end
+    errors.uniq
+  end
+
+  def in_inventory?(snapshot, subject)
+    normalized = normalize_subject(subject)
+    Array(snapshot["inventory"]).any? { |item| normalize_subject(item["subject"]) == normalized }
+  end
+
+  def classify(delta, snapshot, root)
+    coverage_complete = snapshot["coverage_status"] == "complete"
+    source_is_valid = source_valid?(root, delta["source"])
+    return { "predicate" => nil, "confidence" => "incomplete", "source_valid" => source_is_valid } unless coverage_complete && source_is_valid
+
+    subject = normalize_subject(delta["subject"])
+    predicate = in_inventory?(snapshot, subject) ? "dependency_satisfied" : "new_declared_dependency"
+    {
+      "predicate" => predicate,
+      "confidence" => "confirmed",
+      "subject" => subject,
+      "source_valid" => true,
+      "inputs" => ["snapshot:inventory", "snapshot:coverage", "delta:#{delta["id"]}"]
+    }
+  end
+
+  def assess(root, feature, snapshot, manifest, delta_set_id)
+    binding = manifest_errors(manifest, feature, delta_set_id)
+    unless binding.empty?
+      return {
+        "feature" => feature, "outcome" => "lightweight",
+        "assessment_completeness" => "incomplete",
+        "would_require" => ["re_attest_delta_set"], "would_block" => [],
+        "unresolved_questions" => [UNRESOLVED[:DELTA_SET_BINDING_FAILED]],
+        "binding_errors" => binding, "findings" => []
+      }
+    end
+
+    deltas = Array(manifest["items"]).map { |item| item["canonical_delta"] }
+    findings = deltas.map { |delta| classify(delta, snapshot, root).merge("delta_id" => delta["id"]) }
+    incomplete = snapshot["coverage_status"] != "complete" || findings.any? { |finding| finding["confidence"] == "incomplete" }
+    if incomplete
+      codes = []
+      codes << UNRESOLVED[:BASELINE_COVERAGE_INCOMPLETE] if snapshot["coverage_status"] != "complete"
+      codes << UNRESOLVED[:DELTA_SOURCE_UNVERIFIABLE] if findings.any? { |finding| finding["confidence"] == "incomplete" }
+      return {
+        "feature" => feature, "outcome" => "lightweight",
+        "assessment_completeness" => "incomplete",
+        "would_require" => ["clarify_or_rescan"], "would_block" => [],
+        "unresolved_questions" => stable_sorted_union([codes]), "findings" => findings
+      }
+    end
+
+    new_dependencies = findings.select { |finding| finding["predicate"] == "new_declared_dependency" }
+    if new_dependencies.empty?
+      {
+        "feature" => feature, "outcome" => "none",
+        "assessment_completeness" => "complete",
+        "would_require" => [], "would_block" => [], "unresolved_questions" => [], "findings" => findings
+      }
+    else
+      {
+        "feature" => feature, "outcome" => "full",
+        "assessment_completeness" => "complete",
+        "would_require" => ["decision"], "would_block" => [], "unresolved_questions" => [], "findings" => findings
+      }
+    end
+  end
+
+  def write_assessment(root, feature, expected_revision, assessment, manifest_path_value, base_snapshot_revision, delta_set_id)
+    current = current_assessment_revision(root, feature)
+    raise ArgumentError, "assessment revision conflict: expected #{expected_revision}, current #{current}" unless expected_revision == current
+
+    revision = current + 1
+    final = assessment.merge(
+      "schema_version" => SCHEMA_VERSION,
+      "rule_version" => RULE_VERSION,
+      "assessment_revision" => revision,
+      "base_snapshot_revision" => base_snapshot_revision,
+      "delta_set_id" => delta_set_id,
+      "manifest_path" => manifest_path_value.sub("#{root}/", ""),
+      "manifest_hash" => sha256(File.read(manifest_path_value))
+    )
+    history = assessment_history_path(root, feature, revision)
+    DevflowControlIO.atomic_create(history, JSON.pretty_generate(final) + "\n")
+    DevflowControlIO.atomic_write(assessment_pointer_path(root, feature), JSON.pretty_generate({ "current_revision" => revision, "path" => history.sub("#{root}/", "") }) + "\n")
+    DevflowControlIO.append_audit(assessment_audit_path(root, feature), {
+      "event" => "assessment_written", "assessment_revision" => revision,
+      "base_snapshot_revision" => base_snapshot_revision, "delta_set_id" => delta_set_id,
+      "manifest_hash" => final["manifest_hash"], "outcome" => final["outcome"], "at" => Time.now.utc.iso8601
+    })
+    DevflowControlIO.register_control_artifact(root, {
+      "path" => history.sub("#{root}/", ""), "type" => "architecture_assessment",
+      "produced_by" => "core", "assessment_revision" => revision,
+      "outcome" => final["outcome"], "base_snapshot_revision" => base_snapshot_revision,
+      "delta_set_id" => delta_set_id
+    })
+    final.merge("path" => history.sub("#{root}/", ""))
+  end
+
+  def write_manifest(root, feature, delta_set_id, source_bundle_revision, deltas)
+    raise ArgumentError, "source_bundle_revision is required" if source_bundle_revision.to_s.empty?
+    raise ArgumentError, "deltas must be a non-empty array" unless deltas.is_a?(Array) && !deltas.empty?
+    errors = deltas.flat_map { |delta| validate_delta(delta, expected_source_revision: source_bundle_revision) }
+    ids = deltas.map { |delta| delta.is_a?(Hash) ? delta["id"] : nil }
+    errors << "duplicate delta ids" unless ids.compact.uniq.length == ids.length && ids.none?(&:nil?)
+    raise ArgumentError, errors.uniq.join("; ") unless errors.empty?
+
+    manifest = {
+      "schema_version" => SCHEMA_VERSION,
+      "delta_set_id" => delta_set_id,
+      "feature" => feature,
+      "source_bundle_revision" => source_bundle_revision,
+      "items" => deltas.map do |delta|
+        canonical = canonical_delta(delta).merge("id" => delta["id"])
+        { "id" => delta["id"], "canonical_delta" => canonical, "canonical_delta_hash" => canonical_delta_hash(canonical) }
+      end,
+      "attestation" => {
+        "principal" => "interactive-user", "verified_by" => "core", "method" => "ui_confirm", "confirmed_at" => Time.now.utc.iso8601
+      }
+    }
+    destination = manifest_path(root, feature, delta_set_id)
+    DevflowControlIO.atomic_create(destination, JSON.pretty_generate(manifest) + "\n")
+    DevflowControlIO.append_audit(assessment_audit_path(root, feature), {
+      "event" => "manifest_confirmed", "delta_set_id" => delta_set_id,
+      "manifest_hash" => sha256(File.read(destination)), "at" => Time.now.utc.iso8601
+    })
+    DevflowControlIO.register_control_artifact(root, {
+      "path" => destination.sub("#{root}/", ""), "type" => "delta_set_manifest",
+      "produced_by" => "core", "delta_set_id" => delta_set_id
+    })
+    [manifest, destination]
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  options = {
+    feature: nil, base_snapshot_revision: nil, delta_set_id: nil, delta_json: nil,
+    source_bundle_revision: nil, expected_assessment_revision: nil,
+    confirmed_interactively: false, write: false, json: false
+  }
+  command = ARGV.shift
+  OptionParser.new do |o|
+    o.on("--feature NAME") { |value| options[:feature] = value }
+    o.on("--base-snapshot-revision N", Integer) { |value| options[:base_snapshot_revision] = value }
+    o.on("--delta-set-id ID") { |value| options[:delta_set_id] = value }
+    o.on("--delta-json JSON") { |value| options[:delta_json] = value }
+    o.on("--source-bundle-revision REV") { |value| options[:source_bundle_revision] = value }
+    o.on("--expected-assessment-revision N", Integer) { |value| options[:expected_assessment_revision] = value }
+    o.on("--confirmed-interactively") { options[:confirmed_interactively] = true }
+    o.on("--write") { options[:write] = true }
+    o.on("--json") { options[:json] = true }
+  end.parse!
+
+  root = Dir.pwd
+  writes = command == "write-manifest" || (command == "assess" && options[:write])
+  lock = writes ? DevflowControlIO.acquire_project_lock(root) : nil
+  begin
+    result =
+      case command
+      when "inspect"
+        raise ArgumentError, "--feature is required" if options[:feature].to_s.empty?
+        feature = ArchitectureAssessment.safe_component!(options[:feature], "feature")
+        result = {
+          "ok" => true,
+          "current_assessment_revision" => ArchitectureAssessment.current_assessment_revision(root, feature)
+        }
+        unless options[:delta_set_id].to_s.empty?
+          delta_set_id = ArchitectureAssessment.safe_component!(options[:delta_set_id], "deltaSetId")
+          manifest = ArchitectureAssessment.manifest_path(root, feature, delta_set_id)
+          result.merge!("manifest_exists" => File.exist?(manifest), "manifest_path" => manifest.sub("#{root}/", ""))
+        end
+        result
+      when "write-manifest"
+        raise ArgumentError, "--feature is required" if options[:feature].to_s.empty?
+        raise ArgumentError, "--delta-set-id is required" if options[:delta_set_id].to_s.empty?
+        raise ArgumentError, "--source-bundle-revision is required" if options[:source_bundle_revision].to_s.empty?
+        raise ArgumentError, "--delta-json is required" if options[:delta_json].to_s.empty?
+        raise ArgumentError, "--confirmed-interactively is required" unless options[:confirmed_interactively]
+        raise ArgumentError, "--write is required" unless options[:write]
+        feature = ArchitectureAssessment.safe_component!(options[:feature], "feature")
+        delta_set_id = ArchitectureAssessment.safe_component!(options[:delta_set_id], "deltaSetId")
+        deltas = JSON.parse(options[:delta_json])
+        manifest, path = ArchitectureAssessment.write_manifest(root, feature, delta_set_id, options[:source_bundle_revision], deltas)
+        { "ok" => true, "delta_set_id" => delta_set_id, "manifest_hash" => ArchitectureAssessment.sha256(File.read(path)), "path" => path.sub("#{root}/", ""), "manifest" => manifest }
+      when "assess"
+        raise ArgumentError, "--feature is required" if options[:feature].to_s.empty?
+        raise ArgumentError, "--base-snapshot-revision is required" if options[:base_snapshot_revision].nil?
+        raise ArgumentError, "--delta-set-id is required" if options[:delta_set_id].to_s.empty?
+        feature = ArchitectureAssessment.safe_component!(options[:feature], "feature")
+        delta_set_id = ArchitectureAssessment.safe_component!(options[:delta_set_id], "deltaSetId")
+        snapshot_path = File.join(root, RuntimeContextCollector::HISTORY_DIR, "#{options[:base_snapshot_revision]}.json")
+        raise ArgumentError, "base snapshot not found: #{snapshot_path}" unless File.exist?(snapshot_path)
+        snapshot = JSON.parse(File.read(snapshot_path))
+        manifest, path = ArchitectureAssessment.read_manifest(root, feature, delta_set_id)
+        assessment = ArchitectureAssessment.assess(root, feature, snapshot, manifest, delta_set_id).merge(
+          "base_snapshot_revision" => options[:base_snapshot_revision], "delta_set_id" => delta_set_id
+        )
+        if options[:write]
+          raise ArgumentError, "--expected-assessment-revision is required when writing" if options[:expected_assessment_revision].nil?
+          assessment = ArchitectureAssessment.write_assessment(root, feature, options[:expected_assessment_revision], assessment, path, options[:base_snapshot_revision], delta_set_id)
+        end
+        { "ok" => true }.merge(assessment)
+      else
+        raise ArgumentError, "command must be inspect, write-manifest, or assess"
+      end
+  rescue StandardError => error
+    result = { "ok" => false, "reason" => "architecture_assessment_failed", "message" => error.message }
+  ensure
+    DevflowControlIO.release_lock(lock)
+  end
+  puts JSON.pretty_generate(result)
+end