ace-test-runner-e2e 0.38.11 → 0.40.1

data/lib/ace/test/end_to_end_runner/cli/commands/run_suite.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "ace/b36ts"
 require "ace/support/cli"
 require "stringio"
 require "ace/support/cli"
@@ -23,6 +24,7 @@ module Ace
               in the monorepo. Tests run sequentially by default or in parallel
               with --parallel flag. Use --affected to only test changed packages.
               Use --only-failures to re-run only previously failed scenarios.
+              Full unfiltered suite runs retry failed scenarios once by default.
               Optionally filter to specific packages with a comma-separated list.
 
               Output:
@@ -40,6 +42,8 @@ module Ace
               "--affected --parallel 8       # Parallel affected tests only",
               "--only-failures               # Re-run failed scenarios from cache",
               "--affected --only-failures    # Re-run failed scenarios in affected packages",
+              "--no-retry-failures-once      # Disable default retry for a full suite run",
+              "--prune-artifacts             # Remove stale .ace-local/test-e2e artifacts before running",
               "--tags smoke,happy-path       # Include scenarios by tag",
               "--exclude-tags deep           # Exclude scenarios by tag",
               "--cli-args dangerously-skip-permissions  # Pass args to provider"
@@ -50,6 +54,8 @@ module Ace
             option :affected, type: :boolean, desc: "Only test affected packages"
             option :only_failures, type: :boolean,
               desc: "Re-run only previously failed scenarios"
+            option :retry_failures_once, type: :boolean,
+              desc: "Retry failed scenarios once after a full unfiltered suite run"
             option :cli_args, type: :string,
               desc: "Extra args for CLI-based LLM providers"
             option :provider, type: :string, default: Molecules::ConfigLoader.default_provider,
@@ -61,6 +67,8 @@ module Ace
             option :progress, type: :boolean, desc: "Enable live animated display"
             option :verify, type: :boolean,
               desc: "Run independent verifier pass for each scenario"
+            option :prune_artifacts, type: :boolean,
+              desc: "Remove stale .ace-local/test-e2e artifacts before running (preserves suite reports and runtime-cache)"
             option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
             option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
             option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
@@ -69,21 +77,36 @@ module Ace
               options = coerce_types(options, parallel: :integer, timeout: :integer)
 
               parallel = options[:parallel]
-              affected = options[:affected]
-              only_failures = options[:only_failures]
+              affected = !!options[:affected]
+              only_failures = !!options[:only_failures]
+              prune_artifacts = !!options[:prune_artifacts]
               tags = parse_csv_list(options[:tags])
               exclude_tags = parse_csv_list(options[:exclude_tags])
+              if only_failures && prune_artifacts
+                raise Ace::Support::Cli::Error.new(
+                  "--prune-artifacts cannot be used with --only-failures"
+                )
+              end
+              retry_failures_once = resolve_retry_failures_once(
+                requested: options[:retry_failures_once],
+                packages: packages,
+                affected: affected,
+                only_failures: only_failures,
+                tags: tags,
+                exclude_tags: exclude_tags
+              )
 
               output = quiet?(options) ? StringIO.new : $stdout
               progress = options[:progress] && !quiet?(options)
+              prune_artifacts_if_requested(output: output, prune_artifacts: prune_artifacts, quiet: quiet?(options))
 
-              orchestrator = Organisms::SuiteOrchestrator.new(
+              orchestrator = build_orchestrator(
                 max_parallel: [parallel, 1].max,
                 output: output,
                 progress: progress
               )
 
-              results = orchestrator.run(
+              run_options = {
                 parallel: parallel > 0,
                 affected: affected,
                 only_failures: only_failures,
@@ -94,6 +117,13 @@ module Ace
                 tags: tags,
                 exclude_tags: exclude_tags,
                 verify: options[:verify]
+              }
+
+              results = run_suite_with_retry(
+                orchestrator,
+                run_options: run_options,
+                output: output,
+                retry_failures_once: retry_failures_once
               )
 
               if results[:total].zero?
@@ -110,13 +140,173 @@ module Ace
               if results[:failed] > 0 || results[:errors] > 0
                 failed_count = results[:failed] + results[:errors]
                 raise Ace::Support::Cli::Error.new(
-                  "#{failed_count} test(s) failed or errored"
+                  results[:retry_attempted] ? "#{failed_count} test(s) failed or errored after retry" : "#{failed_count} test(s) failed or errored"
                 )
               end
+
+              results
             end
 
             private
 
+            def build_orchestrator(max_parallel:, output:, progress:)
+              Organisms::SuiteOrchestrator.new(
+                max_parallel: max_parallel,
+                output: output,
+                progress: progress
+              )
+            end
+
+            def build_retry_report_writer
+              Molecules::SuiteReportWriter.new(config: Molecules::ConfigLoader.load)
+            end
+
+            def build_artifact_pruner
+              Molecules::ArtifactPruner.new
+            end
+
+            def prune_artifacts_if_requested(output:, prune_artifacts:, quiet:)
+              return unless prune_artifacts
+
+              result = build_artifact_pruner.prune(base_dir: Dir.pwd)
+              return if quiet
+
+              output.puts(
+                "Pruned #{result[:deleted_count]} artifact(s) from #{result[:root_display]} (preserved suite reports and runtime-cache)"
+              )
+            end
+
+            def run_suite_with_retry(orchestrator, run_options:, output:, retry_failures_once:)
+              initial_results = orchestrator.run(run_options)
+              annotated = annotate_results(
+                initial_results,
+                retry_attempted: false,
+                attempts: 1,
+                flaky_scenarios: [],
+                remaining_failures: failure_scenarios(initial_results),
+                initial_report_path: initial_results[:report_path],
+                retry_report_path: nil,
+                report_path: initial_results[:report_path]
+              )
+              return annotated unless retry_failures_once && suite_failed?(initial_results)
+
+              output.puts "Retrying failed scenarios once..."
+              retry_results = orchestrator.run(run_options.merge(only_failures: true))
+              if retry_results[:total].zero?
+                raise Ace::Support::Cli::Error.new(
+                  "Retry pass found no failed test scenarios from attempt 1; aborting instead of silently passing"
+                )
+              end
+
+              flaky_scenarios = recovered_flaky_scenarios(initial_results, retry_results)
+              remaining_failures = failure_scenarios(retry_results)
+              final_report_path = write_retry_summary_report(initial_results, retry_results)
+              output.puts "Final Report: #{final_report_path}" if final_report_path
+
+              if remaining_failures.empty?
+                output.puts "#{flaky_scenarios.length} scenario(s) recovered on retry and were marked flaky"
+              else
+                output.puts "#{remaining_failures.length} scenario(s) still failing after retry"
+              end
+
+              annotate_results(
+                retry_results,
+                retry_attempted: true,
+                attempts: 2,
+                flaky_scenarios: flaky_scenarios,
+                remaining_failures: remaining_failures,
+                initial_report_path: initial_results[:report_path],
+                retry_report_path: retry_results[:report_path],
+                report_path: final_report_path || retry_results[:report_path]
+              )
+            end
+
+            def write_retry_summary_report(initial_results, retry_results)
+              build_retry_report_writer.write_retry_summary(
+                initial_results: initial_results,
+                retry_results: retry_results,
+                timestamp: Ace::B36ts.encode(Time.now.utc, format: :"50ms"),
+                base_dir: Dir.pwd
+              )
+            rescue => e
+              warn "Warning: Failed to write retry summary report: #{e.message}" if ENV["DEBUG"]
+              nil
+            end
+
+            def annotate_results(results, **extra)
+              results.merge(extra)
+            end
+
+            def suite_failed?(results)
+              results[:failed].to_i > 0 || results[:errors].to_i > 0
+            end
+
+            def failure_scenarios(results)
+              scenario_result_index(results)
+                .values
+                .select { |result| result[:status] != "pass" }
+                .map { |result| result[:test_id] }
+                .sort
+            end
+
+            def recovered_flaky_scenarios(initial_results, retry_results)
+              initial_by_test = scenario_result_index(initial_results)
+              retry_by_test = scenario_result_index(retry_results)
+
+              initial_by_test.each_with_object([]) do |(test_id, initial), flaky|
+                next if initial[:status] == "pass"
+
+                retry_result = retry_by_test[test_id]
+                next unless retry_result && retry_result[:status] == "pass"
+
+                flaky << {
+                  "test_id" => test_id,
+                  "initial_status" => initial[:status],
+                  "retry_status" => retry_result[:status]
+                }
+              end.sort_by { |entry| entry["test_id"] }
+            end
+
+            def scenario_result_index(results)
+              results.fetch(:packages, {}).values.flatten.each_with_object({}) do |result, index|
+                test_name = result[:test_name] || result[:test_id] || ""
+                test_id = test_name[/\A(TS-[A-Z0-9]+-\d+[a-z]*)/i, 1]&.upcase || test_name
+                next if test_id.empty?
+
+                index[test_id] = {
+                  test_id: test_id,
+                  status: result[:status],
+                  summary: result[:summary],
+                  error: result[:error]
+                }
+              end
+            end
+
+            def resolve_retry_failures_once(requested:, packages:, affected:, only_failures:, tags:, exclude_tags:)
+              scoped = scoped_suite_run?(
+                packages: packages,
+                affected: affected,
+                only_failures: only_failures,
+                tags: tags,
+                exclude_tags: exclude_tags
+              )
+              if requested == true && scoped
+                raise Ace::Support::Cli::Error.new(
+                  "--retry-failures-once is only supported for full unfiltered suite runs"
+                )
+              end
+
+              return requested unless requested.nil?
+
+              !scoped
+            end
+
+            def scoped_suite_run?(packages:, affected:, only_failures:, tags:, exclude_tags:)
+              [packages, affected, only_failures].any? ||
+                !tags.empty? ||
+                !exclude_tags.empty?
+            end
+
             def parse_csv_list(raw)
               return [] if raw.nil? || raw.strip.empty?
 

data/lib/ace/test/end_to_end_runner/cli/commands/run_test.rb

@@ -35,6 +35,7 @@ module Ace
               "ace-lint --provider gemini:flash  # Use specific provider",
               "ace-lint --provider glite     # Use API provider (predict mode)",
               "ace-lint --tags smoke         # Run only smoke-tagged scenarios",
+              "ace-lint --prune-artifacts    # Remove stale .ace-local/test-e2e artifacts before running",
               "ace-lint TS-LINT-003 --dry-run  # Preview preflight and scenario phases"
             ]
 
@@ -60,6 +61,8 @@ module Ace
               desc: "Comma-separated scenario tags to include"
             option :verify, type: :boolean,
               desc: "Run independent verifier pass after runner execution"
+            option :prune_artifacts, type: :boolean,
+              desc: "Remove stale .ace-local/test-e2e artifacts before running (preserves final reports and runtime-cache)"
             option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
             option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
             option :debug, type: :boolean, aliases: %w[-d], desc: "Show debug output"
@@ -67,13 +70,22 @@ module Ace
             def call(package:, test_id: nil, **options)
               options = coerce_types(options, timeout: :integer, parallel: :integer)
               output = quiet?(options) ? StringIO.new : $stdout
+              prune_artifacts = !!options[:prune_artifacts]
+
+              if options[:dry_run] && prune_artifacts
+                raise Ace::Support::Cli::Error.new(
+                  "--prune-artifacts cannot be used with --dry-run"
+                )
+              end
+
+              prune_artifacts_if_requested(output: output, prune_artifacts: prune_artifacts, quiet: quiet?(options))
 
               # Handle dry-run mode
               if options[:dry_run]
                 return handle_dry_run(package, test_id, output, tags: parse_tags(options[:tags]))
               end
 
-              orchestrator = Organisms::TestOrchestrator.new(
+              orchestrator = build_orchestrator(
                 provider: options[:provider],
                 timeout: options[:timeout],
                 parallel: options[:parallel],
@@ -110,6 +122,30 @@ module Ace
 
             private
 
+            def build_orchestrator(provider:, timeout:, parallel:, progress:)
+              Organisms::TestOrchestrator.new(
+                provider: provider,
+                timeout: timeout,
+                parallel: parallel,
+                progress: progress
+              )
+            end
+
+            def build_artifact_pruner
+              Molecules::ArtifactPruner.new
+            end
+
+            def prune_artifacts_if_requested(output:, prune_artifacts:, quiet:)
+              return unless prune_artifacts
+
+              result = build_artifact_pruner.prune(base_dir: Dir.pwd)
+              return if quiet
+
+              output.puts(
+                "Pruned #{result[:deleted_count]} artifact(s) from #{result[:root_display]} (preserved final reports and runtime-cache)"
+              )
+            end
+
             # Handle dry-run mode: preview which preflight tests and scenarios would run
             #
             # @param package [String] Package name

data/lib/ace/test/end_to_end_runner/molecules/artifact_pruner.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Ace
+  module Test
+    module EndToEndRunner
+      module Molecules
+        # Prunes stale E2E run artifacts while preserving suite reports and runtime cache.
+        class ArtifactPruner
+          ROOT_RELATIVE_PATH = File.join(".ace-local", "test-e2e")
+          PRESERVED_DIRECTORY_NAMES = %w[runtime-cache].freeze
+          PRESERVED_FILE_PATTERNS = [
+            /-suite-report\.md\z/,
+            /-suite-final-report\.md\z/
+          ].freeze
+
+          def prune(base_dir: Dir.pwd)
+            root = File.join(File.expand_path(base_dir), ROOT_RELATIVE_PATH)
+            return summary(root, [], []) unless Dir.exist?(root)
+
+            removed_paths = []
+            preserved_paths = []
+
+            Dir.children(root).sort.each do |entry|
+              path = File.join(root, entry)
+              if preserve_entry?(entry, path)
+                preserved_paths << path
+              else
+                FileUtils.rm_rf(path)
+                removed_paths << path
+              end
+            end
+
+            summary(root, removed_paths, preserved_paths)
+          end
+
+          private
+
+          def preserve_entry?(entry, path)
+            return true if File.directory?(path) && PRESERVED_DIRECTORY_NAMES.include?(entry)
+            return false unless File.file?(path)
+
+            PRESERVED_FILE_PATTERNS.any? { |pattern| pattern.match?(entry) }
+          end
+
+          def summary(root, removed_paths, preserved_paths)
+            {
+              root: root,
+              root_display: ROOT_RELATIVE_PATH,
+              removed_paths: removed_paths,
+              preserved_paths: preserved_paths,
+              deleted_count: removed_paths.length,
+              preserved_count: preserved_paths.length
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/test/end_to_end_runner/molecules/pipeline_executor.rb

@@ -69,7 +69,8 @@ module Ace
             runner = @prompt_bundler.prepare_runner(
               scenario: scenario,
               sandbox_path: sandbox_path,
-              test_cases: test_cases
+              test_cases: test_cases,
+              artifact_contract: declared_artifact_contract(scenario, test_cases: test_cases)
             )
             runner_response = run_llm(
               prompt_path: runner[:prompt_path],
@@ -78,10 +79,44 @@ module Ace
               cli_args: cli_args,
               env_vars: merged_env,
               subprocess_command_prefix: sandbox_backend.command_prefix(chdir: sandbox_path, env: merged_env),
-              provider: @provider
+              provider: @provider,
+              fallback: false
             )
             runner_observations = extract_runner_observations(runner_response[:text])
-            artifact_contract = snapshot_artifacts(report_dir, sandbox_path, scenario, test_cases: test_cases)
+            initial_artifact_contract = snapshot_artifacts(
+              report_dir,
+              sandbox_path,
+              scenario,
+              test_cases: test_cases,
+              snapshot_name: "artifact-snapshot.initial.json"
+            )
+            artifact_contract = initial_artifact_contract
+
+            if missing_required_artifacts?(artifact_contract)
+              write_command_record(report_dir, "runner-repair", provider: @provider, cli_args: cli_args)
+              repair_runner = @prompt_bundler.prepare_runner(
+                scenario: scenario,
+                sandbox_path: sandbox_path,
+                test_cases: test_cases,
+                artifact_contract: artifact_contract,
+                repair_mode: true
+              )
+              repair_response = run_llm(
+                prompt_path: repair_runner[:prompt_path],
+                system_path: repair_runner[:system_path],
+                output_path: repair_runner[:output_path],
+                cli_args: cli_args,
+                env_vars: merged_env,
+                subprocess_command_prefix: sandbox_backend.command_prefix(chdir: sandbox_path, env: merged_env),
+                provider: @provider,
+                fallback: false
+              )
+              repair_observations = extract_runner_observations(repair_response[:text])
+              runner_observations = merge_runner_observations(runner_observations, repair_observations)
+              artifact_contract = snapshot_artifacts(report_dir, sandbox_path, scenario, test_cases: test_cases)
+            else
+              write_artifact_snapshot(report_dir, "artifact-snapshot.json", artifact_contract)
+            end
 
             verifier = @prompt_bundler.prepare_verifier(
               scenario: scenario,
@@ -98,7 +133,8 @@ module Ace
               cli_args: cli_args,
               env_vars: merged_env,
               subprocess_command_prefix: sandbox_backend.command_prefix(chdir: sandbox_path, env: merged_env),
-              provider: @verifier_provider
+              provider: @verifier_provider,
+              fallback: query_fallback_for(@verifier_provider)
             )
 
             @report_generator.generate(
@@ -111,7 +147,8 @@ module Ace
               metadata: base_metadata(
                 report_dir,
                 runner_observations: runner_observations,
-                artifact_contract: artifact_contract
+                artifact_contract: artifact_contract,
+                initial_artifact_contract: initial_artifact_contract
               )
             )
           rescue => e
@@ -140,7 +177,7 @@ module Ace
 
           private
 
-          def run_llm(prompt_path:, system_path:, output_path:, cli_args:, env_vars:, subprocess_command_prefix:, provider:)
+          def run_llm(prompt_path:, system_path:, output_path:, cli_args:, env_vars:, subprocess_command_prefix:, provider:, fallback:)
             prompt = File.read(prompt_path)
             system = File.read(system_path)
             sandbox_dir = env_vars["PROJECT_ROOT_PATH"] || env_vars[:PROJECT_ROOT_PATH]
@@ -151,7 +188,7 @@ module Ace
               system: system,
               cli_args: cli_args,
               timeout: @timeout,
-              fallback: false,
+              fallback: fallback,
               output: output_path,
               subprocess_env: env_vars,
               subprocess_command_prefix: subprocess_command_prefix,
@@ -159,6 +196,10 @@ module Ace
             )
           end
 
+          def query_fallback_for(provider)
+            provider.to_s.start_with?("role:")
+          end
+
           def write_tc_manifests(report_dir, scenario, test_cases:)
             selected = select_test_cases(scenario, test_cases)
             selected.each do |test_case|
@@ -190,12 +231,18 @@ module Ace
             )
           end
 
-          def snapshot_artifacts(report_dir, sandbox_path, scenario, test_cases:)
-            snapshot = select_test_cases(scenario, test_cases).to_h do |test_case|
+          def snapshot_artifacts(report_dir, sandbox_path, scenario, test_cases:, snapshot_name: "artifact-snapshot.json")
+            snapshot = declared_artifact_contract(scenario, test_cases: test_cases, sandbox_path: sandbox_path)
+            write_artifact_snapshot(report_dir, snapshot_name, snapshot)
+            snapshot
+          end
+
+          def declared_artifact_contract(scenario, test_cases:, sandbox_path: nil)
+            select_test_cases(scenario, test_cases).to_h do |test_case|
               required = Array(test_case.declared_artifacts).sort
               optional = Array(test_case.optional_artifacts).sort
-              present_required = required.select { |path| File.exist?(File.join(sandbox_path, path)) }
-              present_optional = optional.select { |path| File.exist?(File.join(sandbox_path, path)) }
+              present_required = present_artifacts(required, sandbox_path)
+              present_optional = present_artifacts(optional, sandbox_path)
               missing_required = required - present_required
 
               [test_case.tc_id, {
@@ -207,8 +254,31 @@ module Ace
                 "present_optional_artifacts" => present_optional
               }]
             end
-            File.write(File.join(report_dir, "artifact-snapshot.json"), JSON.pretty_generate(snapshot))
-            snapshot
+          end
+
+          def write_artifact_snapshot(report_dir, snapshot_name, snapshot)
+            File.write(File.join(report_dir, snapshot_name), JSON.pretty_generate(snapshot))
+          end
+
+          def present_artifacts(paths, sandbox_path)
+            return [] unless sandbox_path
+
+            Array(paths).select { |path| File.exist?(File.join(sandbox_path, path)) }
+          end
+
+          def missing_required_artifacts?(artifact_contract)
+            artifact_contract.any? do |_tc_id, entry|
+              Array(entry["missing_required_artifacts"]).any?
+            end
+          end
+
+          def merge_runner_observations(initial_observations, repair_observations)
+            initial = initial_observations.to_s.strip
+            repair = repair_observations.to_s.strip
+            return initial if repair.empty?
+            return repair if initial.empty?
+
+            "#{initial}\n\nRepair pass:\n#{repair}"
           end
 
           def select_test_cases(scenario, test_cases)
@@ -218,7 +288,7 @@ module Ace
             Array(scenario.test_cases).select { |tc| wanted.include?(tc.tc_id.to_s.upcase) }
           end
 
-          def base_metadata(report_dir, runner_observations: nil, artifact_contract: nil)
+          def base_metadata(report_dir, runner_observations: nil, artifact_contract: nil, initial_artifact_contract: nil)
             metadata = {
               "runner_provider" => @provider,
               "verifier_provider" => @verifier_provider,
@@ -232,6 +302,12 @@ module Ace
                 Array(entry["missing_required_artifacts"])
               end.reject { |_tc_id, paths| paths.empty? }
             end
+            if initial_artifact_contract
+              metadata["initial_missing_required_artifacts"] = initial_artifact_contract.to_h.transform_values do |entry|
+                Array(entry["missing_required_artifacts"])
+              end.reject { |_tc_id, paths| paths.empty? }
+              metadata["artifact_repair_attempted"] = true if missing_required_artifacts?(initial_artifact_contract)
+            end
             metadata
           end
 

data/lib/ace/test/end_to_end_runner/molecules/pipeline_prompt_bundler.rb

@@ -53,21 +53,23 @@ module Ace
           # @param sandbox_path [String]
           # @param test_cases [Array<String>, nil]
           # @return [Hash]
-          def prepare_runner(scenario:, sandbox_path:, test_cases: nil)
+          def prepare_runner(scenario:, sandbox_path:, test_cases: nil, artifact_contract: nil, repair_mode: false)
             cache_dir = ensure_cache_dir(sandbox_path)
-            system_path = File.join(cache_dir, "runner-system.md")
-            prompt_path = File.join(cache_dir, "runner-prompt.md")
+            file_prefix = repair_mode ? "runner-repair" : "runner"
+            system_path = File.join(cache_dir, "#{file_prefix}-system.md")
+            prompt_path = File.join(cache_dir, "#{file_prefix}-prompt.md")
 
             File.write(system_path, RUNNER_SYSTEM_PROMPT)
 
             bundled = bundle_markdown_file(File.join(scenario.dir_path, "runner.yml.md"), test_cases: test_cases)
             bundled = bundled.gsub("Workspace root: (current directory)", "Workspace root: #{File.expand_path(sandbox_path)}")
-            File.write(prompt_path, bundled)
+            contract = build_runner_artifact_contract_section(artifact_contract, repair_mode: repair_mode)
+            File.write(prompt_path, [bundled, contract].reject(&:empty?).join("\n\n---\n\n"))
 
             {
               system_path: system_path,
               prompt_path: prompt_path,
-              output_path: File.join(cache_dir, "runner-output.md")
+              output_path: File.join(cache_dir, "#{file_prefix}-output.md")
             }
           end
 
@@ -251,6 +253,42 @@ module Ace
             MARKDOWN
           end
 
+          def build_runner_artifact_contract_section(artifact_contract, repair_mode:)
+            return "" if artifact_contract.nil? || artifact_contract.empty?
+
+            parts = []
+            parts << "# Artifact Contract"
+            parts << ""
+            if repair_mode
+              parts << "This is a bounded repair pass."
+              parts << "- Do not rerun goals whose required artifacts are already complete."
+              parts << "- For each goal with missing required artifacts, produce only the missing files."
+              parts << "- Prefer the minimal real public command needed to create the missing capture set."
+              parts << "- If the missing file is supporting evidence copied from an already-generated real artifact, copy that real artifact into `results/`."
+              parts << "- Do not invent content, fabricate captures, or rewrite unrelated artifacts."
+            else
+              parts << "A goal is not complete unless every required artifact for that goal exists on disk under `results/`."
+              parts << "- After finishing each goal, self-check the required artifact list below."
+              parts << "- If a required artifact is missing, fix it before moving on."
+            end
+            parts << ""
+
+            artifact_contract.sort.each do |tc_id, entry|
+              parts << "## #{tc_id}"
+              parts << ""
+              parts << "- Required artifacts: #{format_artifact_list(entry["required_artifacts"])}"
+              missing = Array(entry["missing_required_artifacts"])
+              unless missing.empty?
+                parts << "- Missing required artifacts: #{format_artifact_list(missing)}"
+              end
+              optional = Array(entry["optional_artifacts"])
+              parts << "- Optional artifacts: #{format_artifact_list(optional)}" unless optional.empty?
+              parts << ""
+            end
+
+            parts.join("\n").rstrip
+          end
+
           def build_artifact_contract_section(artifact_contract)
             return "# Artifact Contract\n\n(no snapshot provided)" if artifact_contract.nil? || artifact_contract.empty?