ace-support-config 0.17.1 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f7f5cddbf50a8da6f9f42cc644f193cd9a2898757a3417849fc4104546c8ba2
-  data.tar.gz: 54c887961b4c3473a7a4be0bc5383b2ab4975d2d779c86e98c02e180a298c082
+  metadata.gz: 9b56e7f280832462c646dce84cf5565c6ac719dfaa57e3ece2b9974f2561b0a4
+  data.tar.gz: 0bf487c765f752a14ea748f06c951a71a7aab45be83126dd42307da23e8cfebd
 SHA512:
-  metadata.gz: 5a3291da675776cd51aa9f5d888bc8f001c3f0221206c684551ec0bfaa3cbdfe94361ed3c8a56826bce3cd838a172873cdf31afa95202a4ea0dc6278afce111d
-  data.tar.gz: 570b40415d3a4b63b3762d09fea0b43c74628dd91f286818215aaa388371d26dc586f4ab00316b6c781ae38e1555477cf07a03d0340fa2e4f8d1b9ec7b0463a9
+  metadata.gz: 0f2e4c7389588f2b2e894cfb7730e6a226dbbfa36d5b9ba8bd55943e52195f28baca4bc493fed748bfba2388f4e5dfc1824aca28220219adf353ad41e5c083fc
+  data.tar.gz: f58924e6b836b963734ef369f1d548cf36a61144a07dc2d0779ed00f4c7f548a7204992badab4be93299a6772bc67b51e20c37497a7c0e57a95329ef5f8483e5

data/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.18.0] - 2026-08-13
+### Added
+- Manage expiring drift acknowledgements
+- Add profile-aware policy checks to doctor
+- Report profile-aware configuration drift in doctor
+### Technical
+- Streamline bootstrap templates around principles-first guidance
+
 ## [0.17.1] - 2026-06-30
 
 ### Changed

data/lib/ace/support/config/cli.rb

@@ -168,7 +168,19 @@ module Ace
         end
 
         def run_doctor(argv)
-          options = {json: false, no_probe: false, probe: false, hygiene: false, verbose: false, no_color: false, quiet: false}
+          options = {
+            json: false,
+            no_probe: false,
+            probe: false,
+            hygiene: false,
+            verbose: false,
+            no_color: false,
+            quiet: false,
+            recommendations: false,
+            profile: nil,
+            strict: false,
+            check_updates: false
+          }
 
           parser = OptionParser.new do |opts|
             opts.banner = <<~BANNER.chomp
@@ -181,6 +193,10 @@ module Ace
               OPTIONS
             BANNER
             opts.on("--json", "Output checks as JSON") { options[:json] = true }
+            opts.on("--recommendations", "Enable recommendation mode") { options[:recommendations] = true }
+            opts.on("--profile PROFILE", "Select profile (minimal, application, ace-development)") { |p| options[:profile] = p }
+            opts.on("--strict", "Exit nonzero on blocker or warning recommendations") { options[:strict] = true }
+            opts.on("--check-updates", "Check for package/recommendation updates") { options[:check_updates] = true }
             opts.on("--hygiene", "Show full hygiene findings") { options[:hygiene] = true }
             opts.on("-v", "--verbose", "Show full diagnostic detail") { options[:verbose] = true }
             opts.on("-q", "--quiet", "Suppress output; use exit status only") { options[:quiet] = true }
@@ -195,15 +211,28 @@ module Ace
 
           parser.parse!(argv)
 
-          exit_code = Organisms::SetupDoctor.new.run(
-            json: options[:json],
-            no_probe: options[:no_probe],
-            probe: options[:probe],
-            hygiene: options[:hygiene],
-            verbose: options[:verbose],
-            colors: !options[:no_color],
-            quiet: options[:quiet]
-          )
+          doctor = Organisms::SetupDoctor.new
+
+          if options[:recommendations]
+            exit_code = doctor.run_recommendations(
+              profile: options[:profile],
+              strict: options[:strict],
+              check_updates: options[:check_updates],
+              json: options[:json],
+              quiet: options[:quiet]
+            )
+          else
+            exit_code = doctor.run(
+              json: options[:json],
+              no_probe: options[:no_probe],
+              probe: options[:probe],
+              hygiene: options[:hygiene],
+              verbose: options[:verbose],
+              colors: !options[:no_color],
+              quiet: options[:quiet]
+            )
+          end
+
           exit(exit_code) if exit_code.positive?
         end
 

data/lib/ace/support/config/molecules/setup_doctor_reporter.rb

@@ -51,6 +51,56 @@ module Ace
             end
           end
 
+          def self.format_recommendations(profile, findings, strict: false)
+            output = []
+            output << "\n🏥 Configuration Recommendations (Profile: #{profile})"
+            output << "=" * 50
+            output << ""
+
+            # Separate acknowledged from visible findings
+            visible = findings.reject { |f| f[:severity] == "acknowledged" }
+            acknowledged_count = findings.count { |f| f[:severity] == "acknowledged" }
+
+            if visible.empty? && acknowledged_count.zero?
+              output << "✅ No recommendations found - configuration matches profile '#{profile}'."
+            elsif visible.empty?
+              output << "✅ All findings acknowledged (#{acknowledged_count} active)."
+            else
+              visible.each_with_index do |f, idx|
+                glyph = case f[:severity]
+                        when "blocker" then "❌"
+                        when "warning" then "⚠️"
+                        when "recommendation" then "💡"
+                        else "ℹ️"
+                        end
+                output << "#{idx + 1}. #{glyph} [#{f[:severity].upcase}] #{f[:id]}"
+                output << "   Source: #{f[:resolved_source]} | Version: #{f[:version]}"
+                output << "   Current: #{f[:current_value]}"
+                output << "   Recommended: #{f[:recommended_value]}"
+                output << "   Rationale: #{f[:rationale]}" if f[:rationale]
+                output << "   Next Action: #{f[:next_action]}" if f[:next_action]
+                if f[:acknowledgement_expired] && f[:acknowledgement]
+                  ack = f[:acknowledgement]
+                  output << "   Prior Acknowledgement Expired: #{ack["rationale"]} (by #{ack["actor"]})"
+                end
+                output << ""
+              end
+              if acknowledged_count.positive?
+                output << "   (#{acknowledged_count} finding#{"s" if acknowledged_count > 1} suppressed by active acknowledgement#{"s" if acknowledged_count > 1})"
+                output << ""
+              end
+            end
+
+            output << "=" * 50
+            has_failures = findings.any? { |f| %w[blocker warning].include?(f[:severity]) }
+            if strict && has_failures
+              output << "\e[31mRecommendation check failed under strict mode\e[0m"
+            else
+              output << "\e[32mRecommendation check completed\e[0m"
+            end
+            output.join("\n")
+          end
+
           def initialize(results, hygiene:, verbose:, colors:)
             @results = results
             @hygiene = hygiene

data/lib/ace/support/config/organisms/setup_doctor.rb

@@ -89,6 +89,223 @@ module Ace
             health_blocking?(checks) ? 1 : 0
           end
 
+          VALID_PROFILES = %w[minimal application ace-development].freeze
+
+          def run_recommendations(profile: nil, strict: false, check_updates: false, json: false, quiet: false, io: $stdout)
+            resolved_profile = resolve_profile(profile)
+            unless VALID_PROFILES.include?(resolved_profile)
+              io.puts "Error: Unknown profile '#{profile}'. Accepted profiles are: #{VALID_PROFILES.join(", ")}"
+              return 1
+            end
+
+            findings = evaluate_recommendations(profile: resolved_profile, check_updates: check_updates)
+
+            has_strict_failures = findings.any? { |f| %w[blocker warning].include?(f[:severity]) }
+            exit_code = (strict && has_strict_failures) ? 1 : 0
+
+            unless quiet
+              if json
+                result = {
+                  schema_version: "1.0",
+                  profile: resolved_profile,
+                  strict: strict,
+                  valid: !has_strict_failures,
+                  findings: findings
+                }
+                io.puts JSON.pretty_generate(result)
+              else
+                io.puts Molecules::SetupDoctorReporter.format_recommendations(resolved_profile, findings, strict: strict)
+              end
+            end
+
+            exit_code
+          end
+
+          def resolve_profile(cli_profile)
+            return cli_profile if cli_profile && !cli_profile.to_s.strip.empty?
+
+            root = project_root
+            proj_config = [
+              File.join(root, ".ace", "config", "config.yml"),
+              File.join(root, ".ace", "config.yml")
+            ].find { |f| File.exist?(f) }
+
+            if proj_config
+              begin
+                data = YAML.safe_load_file(proj_config, aliases: true)
+                p = data&.dig("profile") || data&.dig("config", "profile")
+                return p.to_s if p && !p.to_s.strip.empty?
+              rescue
+                # fallback
+              end
+            end
+
+            "minimal"
+          end
+
+          def evaluate_recommendations(profile:, check_updates: false)
+            findings = []
+            root = project_root
+            version = "0.38.0"
+
+            # Finding 1: Artifact Hygiene (all profiles)
+            gitignore_path = File.join(root, ".gitignore")
+            if !File.exist?(gitignore_path) || !gitignore_entry_present?(File.read(gitignore_path), ".ace-local/")
+              findings << {
+                id: "rec-artifact-hygiene",
+                severity: "blocker",
+                profile: profile,
+                evidence: ".ace-local/ is missing from .gitignore",
+                resolved_source: "project",
+                current_value: File.exist?(gitignore_path) ? "missing .ace-local/" : "missing .gitignore",
+                recommended_value: ".ace-local/ in .gitignore",
+                rationale: "Prevents committing transient agent state",
+                next_action: "Add .ace-local/ to .gitignore",
+                version: version
+              }
+            end
+
+            # Finding 2: Provider Package (all profiles)
+            installed = begin
+              Gem::Specification.find_all_by_name(PROVIDER_GEM).any?
+            rescue
+              false
+            end
+            unless installed
+              findings << {
+                id: "rec-provider-package",
+                severity: "warning",
+                profile: profile,
+                evidence: "#{PROVIDER_GEM} gem is not installed",
+                resolved_source: "package_default",
+                current_value: "not_installed",
+                recommended_value: "#{PROVIDER_GEM} installed",
+                rationale: "Required for LLM provider discovery and execution",
+                next_action: "gem install #{PROVIDER_GEM}",
+                version: version
+              }
+            end
+
+            # Finding 3: Profile declaration (minimal profile)
+            if profile == "minimal"
+              findings << {
+                id: "rec-profile-config",
+                severity: "info",
+                profile: profile,
+                evidence: "Project relies on minimal fallback profile",
+                resolved_source: "package_default",
+                current_value: "minimal (fallback)",
+                recommended_value: "explicit profile in .ace/config/config.yml",
+                rationale: "Explicit profile selection enables profile-aware lifecycle checks",
+                next_action: "Add 'profile: application' to .ace/config/config.yml",
+                version: version
+              }
+            end
+
+            # Finding 4: Profile-specific checks for application & ace-development
+            if %w[application ace-development].include?(profile)
+              wt_config = File.join(root, ".ace", "git", "worktree.yml")
+              unless File.exist?(wt_config)
+                findings << {
+                  id: "rec-worktree-bootstrap",
+                  severity: "warning",
+                  profile: profile,
+                  evidence: ".ace/git/worktree.yml is missing",
+                  resolved_source: "package_default",
+                  current_value: "not_configured",
+                  recommended_value: "project worktree policy configured",
+                  rationale: "#{profile} profile requires explicit worktree preparation policy",
+                  next_action: "ace-git-worktree config init",
+                  version: version
+                }
+              end
+
+              # Guidance check
+              agents_md = File.join(root, "AGENTS.md")
+              tools_md = File.join(root, "docs", "tools.md")
+              unless File.exist?(agents_md) && File.exist?(tools_md)
+                findings << {
+                  id: "rec-agent-guidance",
+                  severity: "warning",
+                  profile: profile,
+                  evidence: "Agent engineering guidance is incomplete or unanchored",
+                  resolved_source: "project",
+                  current_value: File.exist?(agents_md) ? "missing docs/tools.md" : "missing AGENTS.md",
+                  recommended_value: "AGENTS.md and docs/tools.md present",
+                  rationale: "Provides structured engineering principles and agent practice guidance",
+                  next_action: "Run ace-config sync ace-support-core --force",
+                  version: version
+                }
+              end
+            end
+
+            # Finding 5: Application profile policy checks (strict application workflow validation)
+            if profile == "application"
+              # Check worktree root path safety if config exists
+              wt_config = File.join(root, ".ace", "git", "worktree.yml")
+              if File.exist?(wt_config)
+                begin
+                  wt_data = YAML.safe_load_file(wt_config, aliases: true)
+                  root_p = wt_data&.dig("git", "worktree", "root_path") || wt_data&.dig("root_path")
+                  if root_p && (root_p.start_with?("/") || root_p.include?(".."))
+                    findings << {
+                      id: "rec-worktree-policy",
+                      severity: "warning",
+                      profile: "application",
+                      evidence: "Worktree root_path '#{root_p}' escapes repository boundary",
+                      resolved_source: "project",
+                      current_value: root_p,
+                      recommended_value: ".ace-wt (repository-local)",
+                      rationale: "Application profile requires repository-local or common-root worktrees",
+                      next_action: "Set git.worktree.root_path to .ace-wt in .ace/git/worktree.yml",
+                      version: version
+                    }
+                  end
+                rescue
+                  # Ignore parse failure
+                end
+              end
+            end
+
+            # Finding 6: ACE-development profile exception handling
+            if profile == "ace-development"
+              # Under ace-development profile, broad pipelines (batch worktrees, retrospectives, releases) are expected
+              findings << {
+                id: "rec-dev-pipeline",
+                severity: "info",
+                profile: "ace-development",
+                evidence: "ACE-development profile active",
+                resolved_source: "project",
+                current_value: "ace-development",
+                recommended_value: "ace-development",
+                rationale: "Broad development pipeline capabilities (batch, fork, release, demo) are enabled and accepted",
+                next_action: "No action required",
+                version: version
+              }
+            end
+
+            # Opt-in update check
+            if check_updates
+              findings << {
+                id: "rec-update-check",
+                severity: "info",
+                profile: profile,
+                evidence: "Opt-in update check feed evaluated",
+                resolved_source: "network",
+                current_value: "up_to_date",
+                recommended_value: "up_to_date",
+                rationale: "Ensures package recommendation versions match upstream releases",
+                next_action: "No update required",
+                version: version
+              }
+            end
+
+            # Apply acknowledgements: suppress acknowledged findings, re-expose expired ones
+            apply_acknowledgements(findings, profile: profile, root: root)
+
+            findings
+          end
+
           private
 
           def check_artifact_hygiene
@@ -1132,6 +1349,115 @@ module Ace
             token = token.delete_suffix("/")
             token
           end
+
+          # --- Acknowledgement support ---
+
+          # Load acknowledgements from project config and apply them to findings.
+          # Active valid acknowledgements change severity to "acknowledged".
+          # Expired acknowledgements keep original severity but attach prior context.
+          def apply_acknowledgements(findings, profile:, root:)
+            acks = load_acknowledgements(root)
+            return if acks.nil? || acks.empty?
+
+            now = Time.now
+
+            findings.each do |finding|
+              ack = acks[finding[:id]]
+              next unless ack.is_a?(Hash)
+
+              validity = validate_acknowledgement(ack, finding, profile, now)
+              case validity
+              when :active
+                finding[:original_severity] = finding[:severity]
+                finding[:severity] = "acknowledged"
+                finding[:acknowledgement] = ack
+              when :expired
+                finding[:acknowledgement] = ack
+                finding[:acknowledgement_expired] = true
+              end
+              # :invalid — leave finding unchanged, ack is silently ignored
+            end
+          end
+
+          # Load recommendation_acknowledgements from project config file.
+          # Returns a Hash keyed by finding id, or empty Hash.
+          def load_acknowledgements(root)
+            config_paths = [
+              File.join(root, ".ace", "config", "config.yml"),
+              File.join(root, ".ace", "config.yml")
+            ]
+            config_path = config_paths.find { |f| File.exist?(f) }
+            return {} unless config_path
+
+            data = YAML.safe_load_file(config_path, permitted_classes: [Time, Date], aliases: true)
+            data&.dig("recommendation_acknowledgements") || {}
+          rescue StandardError
+            {}
+          end
+
+          # Validate an acknowledgement against finding, profile, and time.
+          # Returns :active, :expired, or :invalid.
+          def validate_acknowledgement(ack, finding, profile, now)
+            # Required fields
+            rationale = ack["rationale"].to_s.strip
+            return :invalid if rationale.empty?
+
+            actor = ack["actor"].to_s.strip
+            return :invalid if actor.empty?
+
+            acknowledged_at = parse_time(ack["acknowledged_at"])
+            return :invalid unless acknowledged_at
+
+            # Profile scope: if declared, must match
+            ack_profile = ack["profile"].to_s.strip
+            return :invalid if !ack_profile.empty? && ack_profile != profile
+
+            # Version scope: if declared, must match finding version
+            ack_version = ack["recommendation_version"].to_s.strip
+            if !ack_version.empty? && finding[:version]
+              return :invalid unless version_matches?(ack_version, finding[:version])
+            end
+
+            # Time boundary: expires_at or recheck_after required
+            expires_at = parse_time(ack["expires_at"])
+            recheck_after = parse_time(ack["recheck_after"])
+            return :invalid if expires_at.nil? && recheck_after.nil?
+
+            # Expiry check: at-the-instant is expired
+            boundary = expires_at || recheck_after
+            return :expired if now >= boundary
+
+            :active
+          end
+
+          # Parse a time value from string or Time object.
+          # Returns Time or nil.
+          def parse_time(value)
+            return nil if value.nil?
+            return value if value.is_a?(Time)
+            return value.to_time if value.is_a?(Date)
+
+            Time.parse(value.to_s)
+          rescue ArgumentError, TypeError
+            nil
+          end
+
+          # Check if acknowledgement version constraint matches finding version.
+          # Supports exact match and pessimistic (~>) constraints.
+          def version_matches?(constraint, version)
+            return true if constraint == version
+
+            if constraint.start_with?("~>")
+              prefix = constraint.sub("~>", "").strip
+              parts = prefix.split(".")
+              return false if parts.length < 2
+
+              # Pessimistic: ~> 0.38 means >= 0.38.0 and < 1.0
+              version.start_with?(parts[0...-1].join(".") + ".")
+            else
+              constraint == version
+            end
+          end
         end
       end
     end

data/lib/ace/support/config/version.rb

@@ -3,7 +3,7 @@
 module Ace
   module Support
     module Config
-      VERSION = '0.17.1'
+      VERSION = '0.18.0'
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-support-config
 version: !ruby/object:Gem::Version
-  version: 0.17.1
+  version: 0.18.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-06-30 00:00:00.000000000 Z
+date: 2026-08-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-fs