@guanlin4924/devflow-pi 0.1.16 → 0.1.17

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

@@ -0,0 +1,518 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Static Runtime Context P1. Unlike runtime_context_collector.rb (P0), this
+# produces a separate v2 evidence projection. It must never turn a repository
+# declaration or code reference into a statement about a running environment.
+require "digest"
+require "json"
+require "open3"
+require "optparse"
+require "rexml/document"
+require "rexml/xpath"
+require "time"
+require "yaml"
+require_relative "control_io"
+
+module StaticRuntimeContextCollector
+  SCHEMA_VERSION = 2
+  COLLECTOR_VERSION = "static-runtime-context-v2.1"
+  ROOT_DIR = File.join(".context", "static-runtime-context")
+  HISTORY_DIR = File.join(ROOT_DIR, "revisions")
+  POINTER = ".context/static-runtime-context.json"
+  AUDIT_PATH = File.join(ROOT_DIR, "audit.jsonl")
+  MAX_COMPOSE_BYTES = 1_048_576
+  EXCLUDED_ROOTS = %w[node_modules vendor dist build .git].freeze
+  MANIFEST_EXTRACTORS = {
+    "package.json" => :extract_package_json,
+    "composer.json" => :extract_composer_json,
+    "requirements.txt" => :extract_requirements_txt,
+    "pom.xml" => :extract_pom_xml,
+    "go.mod" => :extract_go_mod
+  }.freeze
+
+  module_function
+
+  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 safe_version(value)
+    text = value.to_s.strip
+    return nil if text.empty? || text.match?(%r{[:/@]}) || text.match?(/(?:token|secret|password)=/i)
+
+    text
+  end
+
+  def extract_package_json(content)
+    parsed = JSON.parse(content)
+    dependencies = parsed["dependencies"].is_a?(Hash) ? parsed["dependencies"] : {}
+    dependencies.map { |name, version| { "subject" => normalize_subject(name), "version" => safe_version(version) } }
+  rescue JSON::ParserError
+    raise "parse_error"
+  end
+
+  def extract_composer_json(content)
+    parsed = JSON.parse(content)
+    dependencies = parsed["require"].is_a?(Hash) ? parsed["require"] : {}
+    dependencies.map { |name, version| { "subject" => normalize_subject(name), "version" => safe_version(version) } }
+  rescue JSON::ParserError
+    raise "parse_error"
+  end
+
+  def extract_requirements_txt(content)
+    content.lines.map(&:strip).reject { |line| line.empty? || line.start_with?("#", "-e", "--", "-r", "-f") }.map do |line|
+      name = line.split(/[<>=!\[\s]/, 2).first.to_s
+      version = line.match(/\A[^<>=!\[\s]+\s*(?:==|>=|<=|~=|>|<)\s*([^\s;]+)\z/)&.[](1)
+      { "subject" => normalize_subject(name), "version" => safe_version(version) }
+    end
+  end
+
+  def extract_pom_xml(content)
+    document = REXML::Document.new(content)
+    REXML::XPath.match(document, "//dependency").map do |dependency|
+      group = dependency.elements["groupId"]&.text.to_s.strip
+      artifact = dependency.elements["artifactId"]&.text.to_s.strip
+      next if group.empty? || artifact.empty?
+
+      { "subject" => normalize_subject("#{group}:#{artifact}"), "version" => safe_version(dependency.elements["version"]&.text) }
+    end.compact
+  rescue REXML::ParseException
+    raise "parse_error"
+  end
+
+  # The grammar used here is deliberately small: direct and parenthesized
+  # require directives. Unsupported Go syntax becomes a parse failure instead
+  # of an incomplete-looking positive inventory.
+  def extract_go_mod(content)
+    entries = []
+    in_block = false
+    content.each_line do |line|
+      stripped = line.strip
+      next if stripped.empty? || stripped.start_with?("//")
+
+      if stripped == "require ("
+        in_block = true
+        next
+      end
+      if in_block && stripped == ")"
+        in_block = false
+        next
+      end
+      candidate = in_block ? stripped : stripped.sub(/\Arequire\s+/, "")
+      next if !in_block && candidate == stripped
+
+      match = candidate.match(/\A([^\s]+)\s+([^\s]+)(?:\s+\/\/.*)?\z/)
+      raise "parse_error" unless match
+
+      entries << { "subject" => normalize_subject(match[1]), "version" => safe_version(match[2]) }
+    end
+    raise "parse_error" if in_block
+
+    entries
+  end
+
+  def git_capture(root, *args)
+    stdout, stderr, status = Open3.capture3("git", "-C", root, *args)
+    [stdout, stderr, status.success?]
+  end
+
+  def git_revision(root)
+    output, _error, success = git_capture(root, "rev-parse", "HEAD")
+    success ? output.strip : ""
+  end
+
+  def git_paths(root, revision)
+    output, error, success = git_capture(root, "ls-tree", "-r", "--name-only", revision)
+    raise "git_tree_unavailable: #{error.strip}" unless success
+
+    output.lines.map(&:strip).reject(&:empty?).sort
+  end
+
+  def git_content(root, revision, path)
+    output, error, success = git_capture(root, "show", "#{revision}:#{path}")
+    raise "git_show_failed: #{error.strip}" unless success
+
+    output
+  end
+
+  def excluded_path?(path)
+    path.split("/").any? { |segment| EXCLUDED_ROOTS.include?(segment) }
+  end
+
+  def dependency_discovery(root, revision)
+    all_paths = git_paths(root, revision)
+    matching = all_paths.select { |path| MANIFEST_EXTRACTORS.key?(File.basename(path)) }
+    included, excluded = matching.partition { |path| !excluded_path?(path) }
+    files = excluded.map { |path| { "path" => path, "status" => "excluded", "reason" => "third_party_or_build_output" } }
+    entries = []
+    included.each do |path|
+      extractor = MANIFEST_EXTRACTORS.fetch(File.basename(path))
+      begin
+        content = git_content(root, revision, path)
+        extract = send(extractor, content)
+        digest = sha256(content)
+        extract.each do |entry|
+          subject = normalize_subject(entry["subject"])
+          next if subject.empty?
+
+          entries << {
+            "subject" => subject,
+            "version" => entry["version"],
+            "evidence" => {
+              "source_type" => "manifest",
+              "path" => path,
+              "git_revision" => revision,
+              "sha256" => digest,
+              "extractor" => extractor.to_s
+            }
+          }
+        end
+        files << { "path" => path, "status" => "scanned", "extractor" => extractor.to_s, "sha256" => digest }
+      rescue StandardError => error
+        files << { "path" => path, "status" => "failed", "extractor" => extractor.to_s, "error" => error.message }
+      end
+    end
+    [files.sort_by { |file| file["path"] }, entries]
+  end
+
+  # A mini-program claim is emitted only when app.json is valid JSON and has
+  # the defining pages array. We deliberately do not infer web by default.
+  def platform_discovery(root, revision)
+    candidates = git_paths(root, revision).select { |path| File.basename(path) == "app.json" }
+    files = []
+    entries = []
+    candidates.each do |path|
+      if excluded_path?(path)
+        files << { "path" => path, "status" => "excluded", "reason" => "third_party_or_build_output" }
+        next
+      end
+      begin
+        content = git_content(root, revision, path)
+        parsed = JSON.parse(content)
+        digest = sha256(content)
+        if parsed["pages"].is_a?(Array)
+          entries << {
+            "subject" => "miniprogram",
+            "evidence" => {
+              "source_type" => "manifest",
+              "path" => path,
+              "git_revision" => revision,
+              "sha256" => digest,
+              "extractor" => "miniprogram_app_json_v1"
+            }
+          }
+          files << { "path" => path, "status" => "scanned", "extractor" => "miniprogram_app_json_v1", "sha256" => digest }
+        else
+          files << { "path" => path, "status" => "ignored", "reason" => "not_a_miniprogram_manifest", "sha256" => digest }
+        end
+      rescue JSON::ParserError
+        files << { "path" => path, "status" => "failed", "extractor" => "miniprogram_app_json_v1", "error" => "parse_error" }
+      rescue StandardError => error
+        files << { "path" => path, "status" => "failed", "extractor" => "miniprogram_app_json_v1", "error" => error.message }
+      end
+    end
+    [files.sort_by { |file| file["path"] }, entries]
+  end
+
+  def compose_path?(path)
+    File.basename(path).match?(%r{\A(?:docker-)?compose(?:[._-][A-Za-z0-9._-]+)?\.ya?ml\z}i)
+  end
+
+  # Docker Compose is intentionally the first and only configuration adapter.
+  # It proves only that a committed descriptor declares a service name; image,
+  # environment, endpoint, and deployment state are never copied or inferred.
+  def compose_discovery(root, revision)
+    candidates = git_paths(root, revision).select { |path| compose_path?(path) }
+    files = []
+    entries = []
+    candidates.each do |path|
+      if excluded_path?(path)
+        files << { "path" => path, "status" => "excluded", "reason" => "third_party_or_build_output" }
+        next
+      end
+      begin
+        content = git_content(root, revision, path)
+        raise "file_too_large" if content.bytesize > MAX_COMPOSE_BYTES
+        # Compose files commonly use x-* anchors. Allow aliases only after a
+        # bounded read and with Psych safe loading; no values are projected.
+        parsed = YAML.safe_load(content, permitted_classes: [], aliases: true)
+        digest = sha256(content)
+        services = parsed.is_a?(Hash) ? parsed["services"] : nil
+        unless services.is_a?(Hash)
+          files << { "path" => path, "status" => "ignored", "reason" => "not_a_compose_services_descriptor", "sha256" => digest }
+          next
+        end
+        services.keys.map(&:to_s).sort.each do |name|
+          next if name.strip.empty?
+
+          entries << {
+            "subject" => "compose_service:#{normalize_subject(name)}",
+            "scope" => { "repository" => "repo-default", "deployment_descriptor" => path },
+            "evidence" => {
+              "source_type" => "config_identifier",
+              "path" => path,
+              "git_revision" => revision,
+              "sha256" => digest,
+              "locator" => "services.#{name}",
+              "extractor" => "docker_compose_services_v1"
+            }
+          }
+        end
+        files << { "path" => path, "status" => "scanned", "extractor" => "docker_compose_services_v1", "sha256" => digest }
+      rescue Psych::Exception
+        files << { "path" => path, "status" => "failed", "extractor" => "docker_compose_services_v1", "error" => "parse_error" }
+      rescue StandardError => error
+        files << { "path" => path, "status" => "failed", "extractor" => "docker_compose_services_v1", "error" => error.message }
+      end
+    end
+    [files.sort_by { |file| file["path"] }, entries]
+  end
+
+  def stable_evidence(entries)
+    entries.sort_by { |entry| [entry["path"], entry["extractor"], entry["sha256"]] }.uniq
+  end
+
+  def claim_id(kind, assertion, subject, scope)
+    "CTX-#{sha256(canonical_json({ "kind" => kind, "assertion" => assertion, "subject" => subject, "scope" => scope }))[0, 16]}"
+  end
+
+  def grouped_claims(kind, assertion, default_scope, entries)
+    entries.group_by { |entry| [entry.fetch("subject"), canonical_json(entry.fetch("scope", default_scope))] }.map do |(subject, scope_json), group|
+      scope = JSON.parse(scope_json)
+      evidence = stable_evidence(group.map do |entry|
+        item = entry.fetch("evidence").dup
+        item["declared_version"] = entry["version"] if entry.key?("version") && !entry["version"].nil?
+        item
+      end)
+      {
+        "id" => claim_id(kind, assertion, subject, scope),
+        "kind" => kind,
+        "subject" => subject,
+        "assertion" => assertion,
+        "scope" => scope,
+        "evidence" => evidence,
+        "collection_state" => "proven"
+      }
+    end
+  end
+
+  def coverage(subject_class, scope, rule, status, files: [], reason: nil)
+    result = {
+      "subject_class" => subject_class,
+      "scope" => scope,
+      "rule" => rule,
+      "status" => status,
+      "files" => files
+    }
+    result["reason"] = reason if reason
+    result
+  end
+
+  def snapshot_for(root, repository_revision)
+    scope = { "repository" => "repo-default" }
+    if repository_revision.empty?
+      failure = { "path" => "<repository>", "status" => "failed", "error" => "git_revision_unavailable" }
+      return [
+        [],
+        [
+          coverage("dependency_declaration", scope, "manifests-v2", "incomplete", files: [failure]),
+          coverage("platform_declaration", scope, "miniprogram-app-json-v1", "unknown", reason: "git_revision_unavailable"),
+          coverage("resource_binding", scope, "not_enabled", "unknown", reason: "code_index_projection_not_enabled"),
+          coverage("integration_use", scope, "not_enabled", "unknown", reason: "code_index_projection_not_enabled"),
+          coverage("job_use", scope, "not_enabled", "unknown", reason: "code_index_projection_not_enabled")
+        ],
+        { "dependency_declaration" => [failure], "platform_declaration" => [] }
+      ]
+    end
+
+    begin
+      dependency_files, dependency_entries = dependency_discovery(root, repository_revision)
+    rescue StandardError => error
+      dependency_files = [{ "path" => "<repository>", "status" => "failed", "error" => error.message }]
+      dependency_entries = []
+    end
+    begin
+      platform_files, platform_entries = platform_discovery(root, repository_revision)
+    rescue StandardError => error
+      platform_files = [{ "path" => "<repository>", "status" => "failed", "error" => error.message }]
+      platform_entries = []
+    end
+    begin
+      resource_files, resource_entries = compose_discovery(root, repository_revision)
+    rescue StandardError => error
+      resource_files = [{ "path" => "<repository>", "status" => "failed", "error" => error.message }]
+      resource_entries = []
+    end
+    dependency_status = dependency_files.any? { |file| file["status"] == "failed" } ? "incomplete" : "complete"
+    platform_status = platform_files.any? { |file| file["status"] == "failed" } ? "incomplete" : "partial"
+    resource_status = resource_files.any? { |file| file["status"] == "failed" } ? "incomplete" : "partial"
+    claims = grouped_claims("dependency_declaration", "declared", scope, dependency_entries) +
+             grouped_claims("platform_declaration", "declared", scope, platform_entries) +
+             grouped_claims("resource_binding", "declared", scope, resource_entries)
+    coverages = [
+      coverage("dependency_declaration", scope, "manifests-v2", dependency_status, files: dependency_files),
+      coverage("platform_declaration", scope, "miniprogram-app-json-v1", platform_status, files: platform_files, reason: "only_miniprogram_app_json_is_supported"),
+      coverage("resource_binding", scope, "docker-compose-services-v1", resource_status, files: resource_files, reason: "only_compose_service_names_are_supported"),
+      coverage("integration_use", scope, "not_enabled", "unknown", reason: "code_index_projection_not_enabled"),
+      coverage("job_use", scope, "not_enabled", "unknown", reason: "code_index_projection_not_enabled")
+    ]
+    [claims, coverages, {
+      "dependency_declaration" => dependency_files,
+      "platform_declaration" => platform_files,
+      "resource_binding" => resource_files
+    }]
+  end
+
+  def snapshot_paths(root)
+    Dir.glob(File.join(root, HISTORY_DIR, "*.json")).sort_by { |path| File.basename(path, ".json").to_i }
+  end
+
+  def next_snapshot_revision(root)
+    latest = snapshot_paths(root).map { |path| File.basename(path, ".json").to_i }.max || 0
+    latest + 1
+  end
+
+  def matching_snapshot(root, repository_revision, input_fingerprint)
+    snapshot_paths(root).each do |path|
+      snapshot = JSON.parse(File.read(path))
+      next unless snapshot["schema_version"] == SCHEMA_VERSION
+      next unless snapshot["collector_version"] == COLLECTOR_VERSION
+      next unless snapshot["repository_revision"] == repository_revision
+      next unless snapshot["input_fingerprint"] == input_fingerprint
+
+      return [snapshot, path]
+    rescue JSON::ParserError
+      raise ArgumentError, "static runtime-context history is invalid JSON: #{path}"
+    end
+    nil
+  end
+
+  def relative_path(root, path)
+    path.sub("#{root}/", "")
+  end
+
+  def collect(root)
+    repository_revision = git_revision(root)
+    claims, coverages, discovery = snapshot_for(root, repository_revision)
+    claims = claims.sort_by { |claim| [claim["kind"], claim["subject"], claim["id"]] }
+    input_fingerprint = sha256(canonical_json({
+      "collector_version" => COLLECTOR_VERSION,
+      "repository_revision" => repository_revision,
+      "coverage" => coverages,
+      "claims" => claims,
+      "discovery" => discovery
+    }))
+    if (existing = matching_snapshot(root, repository_revision, input_fingerprint))
+      snapshot, path = existing
+      DevflowControlIO.atomic_write(File.join(root, POINTER), JSON.pretty_generate({ "current_revision" => snapshot["snapshot_revision"], "path" => relative_path(root, path) }) + "\n")
+      DevflowControlIO.append_audit(File.join(root, AUDIT_PATH), {
+        "event" => "snapshot_reused", "snapshot_revision" => snapshot["snapshot_revision"], "repository_revision" => repository_revision,
+        "input_fingerprint" => input_fingerprint, "at" => Time.now.utc.iso8601
+      })
+      return [snapshot, true]
+    end
+
+    revision = next_snapshot_revision(root)
+    snapshot = {
+      "schema_version" => SCHEMA_VERSION,
+      "context_id" => "repository-static",
+      "snapshot_revision" => revision,
+      "repository_revision" => repository_revision,
+      "collected_at" => Time.now.utc.iso8601,
+      "collector_version" => COLLECTOR_VERSION,
+      "input_fingerprint" => input_fingerprint,
+      "claims" => claims,
+      "coverage" => coverages,
+      "discovery" => discovery
+    }
+    history = File.join(root, HISTORY_DIR, "#{revision}.json")
+    DevflowControlIO.atomic_create(history, JSON.pretty_generate(snapshot) + "\n")
+    DevflowControlIO.atomic_write(File.join(root, POINTER), JSON.pretty_generate({ "current_revision" => revision, "path" => relative_path(root, history) }) + "\n")
+    DevflowControlIO.append_audit(File.join(root, AUDIT_PATH), {
+      "event" => "snapshot_collected", "snapshot_revision" => revision, "repository_revision" => repository_revision,
+      "input_fingerprint" => input_fingerprint, "claims_count" => claims.length, "at" => Time.now.utc.iso8601
+    })
+    DevflowControlIO.register_control_artifact(root, {
+      "path" => relative_path(root, history), "type" => "static_runtime_context_snapshot",
+      "produced_by" => "core", "snapshot_revision" => revision, "repository_revision" => repository_revision,
+      "input_fingerprint" => input_fingerprint
+    })
+    [snapshot, false]
+  end
+
+  def inspect(root)
+    pointer_path = File.join(root, POINTER)
+    return { "ok" => true, "pointer_exists" => false, "current_revision" => 0 } unless File.exist?(pointer_path)
+
+    pointer = JSON.parse(File.read(pointer_path))
+    history = File.join(root, pointer.fetch("path"))
+    snapshot = JSON.parse(File.read(history))
+    {
+      "ok" => true,
+      "pointer_exists" => true,
+      "current_revision" => snapshot["snapshot_revision"],
+      "repository_revision" => snapshot["repository_revision"],
+      "claims_count" => Array(snapshot["claims"]).length,
+      "path" => pointer["path"]
+    }
+  rescue JSON::ParserError, KeyError => error
+    raise ArgumentError, "static runtime-context pointer is invalid: #{error.message}"
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  options = { json: false }
+  command = ARGV.shift
+  OptionParser.new do |o|
+    o.on("--json") { options[:json] = true }
+  end.parse!
+  root = Dir.pwd
+  lock = command == "collect" ? DevflowControlIO.acquire_project_lock(root) : nil
+  begin
+    result =
+      case command
+      when "collect"
+        snapshot, reused = StaticRuntimeContextCollector.collect(root)
+        {
+          "ok" => true,
+          "snapshot_revision" => snapshot["snapshot_revision"],
+          "repository_revision" => snapshot["repository_revision"],
+          "claims_count" => snapshot["claims"].length,
+          "reused" => reused
+        }
+      when "inspect"
+        StaticRuntimeContextCollector.inspect(root)
+      else
+        raise ArgumentError, "command must be collect or inspect"
+      end
+  rescue StandardError => error
+    result = { "ok" => false, "reason" => "static_runtime_context_collector_failed", "message" => error.message }
+  ensure
+    DevflowControlIO.release_lock(lock)
+  end
+  puts JSON.pretty_generate(result)
+end

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

@@ -7,6 +7,7 @@ require "yaml"
 require_relative "control_io"
 require_relative "phase_ownership"
 require_relative "requirement_graph"
+require_relative "architecture_feasibility"
 
 module WorkflowStateValidator
   REQUIRED_STATE_FIELDS = %w[
@@ -78,7 +79,7 @@ module WorkflowStateValidator
     validate_waiting_checkpoint(issues, root, state, step_by_id, artifact_by_path, strict_artifact_status)
     validate_current_in_progress_output_drift(issues, root, state, step_by_id, artifact_by_path)
     graph_gate = workflow.dig("governance", "requirement_graph_gate").to_s
-    governed_steps = %w[requirement-baseline api-contract integration-verify change-plan execute verify]
+    governed_steps = %w[requirement-baseline api-contract architecture-feasibility integration-verify change-plan execute verify]
     # A historical completed state is never rolled back solely because it has
     # no v2 graph/evidence. Its first new governed step, however, must satisfy
     # the new contract before it can advance.
@@ -378,6 +379,8 @@ module WorkflowStateValidator
     validate_requirement_feasibility_review_gate(issues, step, data)
     validate_requirement_baseline_gate(issues, step, data)
     validate_api_contract_gate(issues, step, data)
+    validate_architecture_feasibility_gate(issues, step, data)
+    validate_architecture_consumption_gate(issues, root, state, step, data)
     validate_api_call_guide_gate(issues, step, data)
     validate_frontend_tech_spec_gate(issues, step, data)
     validate_api_supplement_gate(issues, step, data)
@@ -512,6 +515,85 @@ module WorkflowStateValidator
     end
   end
 
+  # P2 is intentionally graduated: only a structurally-derived full
+  # assessment fail-closes. Lightweight incomplete work remains visible to its
+  # technical-spec consumers rather than forcing every small feature through
+  # an invented NFR exercise.
+  def validate_architecture_feasibility_gate(issues, step, data)
+    return unless step["id"] == "architecture-feasibility"
+
+    level = data["assessment_level"]
+    status = data["assessment_status"]
+    comparison = data["comparison_status"]
+    unless %w[not_triggered lightweight full].include?(level)
+      issues << issue("error", "architecture_assessment_level_invalid", "Architecture assessment level is invalid", step: step["id"], level: level)
+      return
+    end
+    unless %w[ready incomplete].include?(status)
+      issues << issue("error", "architecture_assessment_status_invalid", "Architecture assessment status is invalid", step: step["id"], status: status)
+      return
+    end
+    unless %w[not_required missing awaiting_user_confirmation missing_risk awaiting_risk_confirmation confirmed].include?(comparison)
+      issues << issue("error", "architecture_comparison_status_invalid", "Architecture comparison status is invalid", step: step["id"], comparison_status: comparison)
+      return
+    end
+    return unless level == "full"
+    return if status == "ready" && comparison == "confirmed"
+
+    issues << issue(
+      "error",
+      "architecture_full_assessment_incomplete",
+      "A full architecture assessment requires ready inputs plus confirmed decision and risk treatment before technical specifications.",
+      step: step["id"],
+      assessment_status: status,
+      comparison_status: comparison
+    )
+  end
+
+  # A technical spec does not merely claim that it considered architecture. It
+  # pins the exact Core-derived brief it consumed. Compare the pin both to the
+  # brief and to the current graph/context so an upstream edit cannot leave a
+  # convincing but obsolete spec looking fresh.
+  def validate_architecture_consumption_gate(issues, root, state, step, data)
+    return unless %w[frontend-tech-spec backend-tech-spec].include?(step["id"])
+
+    feature = state["current_feature"]
+    brief_path = File.join(root, ".planning", "features", feature, "architecture-brief.meta.json")
+    unless File.file?(brief_path)
+      issues << issue("error", "architecture_brief_meta_missing", "Technical spec cannot be validated without the architecture brief meta", step: step["id"], path: brief_path)
+      return
+    end
+    brief = JSON.parse(File.read(brief_path))
+    expected = {
+      "architecture_brief_revision" => brief["brief_revision"],
+      "architecture_graph_revision" => brief["graph_revision"],
+      "architecture_static_context_snapshot_revision" => brief["static_context_snapshot_revision"],
+      "architecture_comparison_status" => brief["comparison_status"]
+    }
+    expected.each do |field, value|
+      next if data[field] == value
+
+      issues << issue("error", "architecture_consumption_pin_mismatch", "Technical spec architecture pin differs from the Core-derived brief", step: step["id"], field: field, spec_value: data[field], brief_value: value)
+    end
+
+    graph, = RequirementGraph.load_graph(root, feature)
+    if brief["graph_revision"] != graph["revision"]
+      issues << issue("error", "architecture_brief_graph_stale", "Architecture brief was derived from a stale graph revision", step: step["id"], brief_revision: brief["graph_revision"], graph_revision: graph["revision"])
+    end
+    current_context = ArchitectureFeasibility.safe_static_context(root)
+    current_context_revision = current_context["available"] ? current_context["snapshot_revision"] : nil
+    if brief["static_context_snapshot_revision"] != current_context_revision
+      issues << issue("error", "architecture_brief_context_stale", "Architecture brief was derived from a stale static-context snapshot", step: step["id"], brief_revision: brief["static_context_snapshot_revision"], context_revision: current_context_revision)
+    end
+    if brief["assessment_level"] == "full" && brief["comparison_status"] != "confirmed"
+      issues << issue("error", "architecture_brief_full_unconfirmed", "Technical spec cannot consume an unconfirmed full architecture assessment", step: step["id"], comparison_status: brief["comparison_status"])
+    end
+  rescue JSON::ParserError => error
+    issues << issue("error", "architecture_brief_meta_invalid", error.message, step: step["id"], path: brief_path)
+  rescue ArgumentError => error
+    issues << issue("error", "architecture_brief_graph_invalid", error.message, step: step["id"])
+  end
+
   def validate_api_call_guide_gate(issues, step, data)
     return unless step["id"] == "api-call-guide"