ace-sim 0.13.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3a6297bbbb7cb55c1293488c60696397ecef7f68fda202182498abd9f54e1c45
+  data.tar.gz: 90b468fe9fdad0dcc1d9325cc87ff2b7570af95d07ae4b92bec151df821cd224
+SHA512:
+  metadata.gz: cef9bb565960a1b72302e3a753f57903357fd0069e07c92c30a9b3f031fbfa8776df11bf22da22148e8997fe844bc99d98c7b683041cff7ca6afe930e5d75d41
+  data.tar.gz: c14b12a7577d119204483a67483f534d63d6cf3ece944d4e441612c111c6df5cada1e77f85227c3b0d33b20e66e45dc2136c8cfbdae4e64fa58347e3d6b55106

data/.ace-defaults/nav/protocols/wfi-sources/ace-sim.yml

@@ -0,0 +1,19 @@
+---
+# WFI Sources Protocol Configuration for ace-sim gem
+# This enables workflow discovery from the installed ace-sim gem
+
+name: ace-sim
+type: gem
+description: Simulation workflow instructions from ace-sim gem
+priority: 10
+
+# Configuration for workflow discovery within the gem
+config:
+  # Relative path within the gem (default: handbook/workflow-instructions)
+  relative_path: handbook/workflow-instructions
+
+  # Pattern for finding workflow files (default: *.wf.md)
+  pattern: "*.wf.md"
+
+  # Enable discovery
+  enabled: true

data/.ace-defaults/sim/config.yml

@@ -0,0 +1,9 @@
+sim:
+  cache_root: ".ace-local/sim"
+  default_preset: "validate-idea"
+  default_repeat: 1
+  default_steps:
+    - draft
+    - plan
+    - work
+  writeback: false

data/.ace-defaults/sim/presets/validate-idea.yml

@@ -0,0 +1,10 @@
+name: validate-idea
+steps:
+  - draft
+  - plan
+  - work
+provider:
+  - google:flash-preview
+repeat: 1
+synthesis_workflow: wfi://idea/review
+synthesis_provider: claude:haiku

data/.ace-defaults/sim/presets/validate-task.yml

@@ -0,0 +1,9 @@
+name: validate-task
+steps:
+  - plan
+  - work
+provider:
+  - google:flash-preview
+repeat: 1
+synthesis_workflow: wfi://task/review
+synthesis_provider: claude:haiku

data/.ace-defaults/sim/steps/draft.md

@@ -0,0 +1,41 @@
+---
+description: "ace-sim draft step bundle"
+bundle:
+  embed_document_source: true
+  sections:
+    project_context:
+      preset: project
+    draft_workflow:
+      files:
+        - wfi://task/draft
+    review_workflow:
+      files:
+        - wfi://task/review
+    input:
+      files:
+        - ./input.md
+---
+
+# Purpose
+
+Prepare a high-quality draft task from `<input>` using the workflow context and then self-review it.
+
+## Instructions
+
+1. Read `<project_context>` for repository constraints and conventions.
+2. Read `<input>` as the source request.
+3. Use `<draft_workflow>` to draft the task content.
+4. Use `<review_workflow>` to review the drafted task quality.
+
+## Workflow
+
+Use the embedded workflow sections directly:
+- `<draft_workflow>`
+- `<review_workflow>`
+
+## Report
+
+Return markdown only with these tags:
+1. `<observations>...</observations>`
+2. `<task>...</task>`
+3. `<task-review>...</task-review>`

data/.ace-defaults/sim/steps/plan.md

@@ -0,0 +1,54 @@
+---
+description: "ace-sim plan step bundle"
+bundle:
+  embed_document_source: true
+  sections:
+    project_context:
+      preset: project
+    plan_workflow:
+      files:
+        - wfi://task/plan
+    plan_critique:
+      files:
+        - wfi://task/review-plan
+    input:
+      files:
+        - ./input.md
+---
+
+# Purpose
+
+Create an implementation plan from the previous step output using repository context, then critically review it for completeness and executability.
+
+## Instructions
+
+### Phase 1: Build the Plan
+
+Exhaust every detail. Do NOT shortcut — a vague plan produces vague execution.
+
+1. Read `<project_context>` first.
+2. Read `<input>` as the planning source.
+3. Follow `<plan_workflow>` to produce a decision-complete implementation plan.
+4. Be so specific that an agent could execute the plan without asking a single clarifying question.
+
+### Phase 2: Critique the Plan
+
+Now you are the adversarial reviewer. Forget that you wrote this plan — tear it apart.
+
+1. Follow `<plan_critique>` to evaluate the plan you just produced.
+2. Score every dimension honestly. Do NOT give yourself a pass out of convenience.
+3. If the critique reveals gaps, fix them in the plan before reporting.
+
+## Workflow
+
+Use the embedded workflow sections:
+- `<plan_workflow>` — for Phase 1 (building the plan)
+- `<plan_critique>` — for Phase 2 (critiquing the plan)
+
+## Report
+
+Return markdown only with these tags:
+1. `<observations>...</observations>`
+2. `<implementation-plan>...</implementation-plan>`
+3. `<plan-critique>...</plan-critique>`
+4. `<open-questions>...</open-questions>`

data/.ace-defaults/sim/steps/work.md

@@ -0,0 +1,54 @@
+---
+description: "ace-sim work step bundle"
+bundle:
+  embed_document_source: true
+  sections:
+    project_context:
+      preset: project
+    work_workflow:
+      files:
+        - wfi://task/work
+    work_critique:
+      files:
+        - wfi://task/review-work
+    input:
+      files:
+        - ./input.md
+---
+
+# Purpose
+
+Execute the implementation plan from `<input>` and produce a concrete delivery report, then critically review it for completeness and credibility.
+
+## Instructions
+
+### Phase 1: Execute the Plan
+
+Be so specific that an agent could produce exact file changes from your report. Every claim must reference real files, real code patterns, and real project conventions.
+
+1. Read `<project_context>` for constraints.
+2. Read `<input>` for the implementation plan.
+3. Follow `<work_workflow>` to execute and report outcomes.
+4. Do NOT shortcut — list every file changed, every test written, every decision made.
+
+### Phase 2: Critique the Execution
+
+Now you are the adversarial reviewer. Compare the plan and the execution item-by-item.
+
+1. Follow `<work_critique>` to evaluate the execution report you just produced.
+2. Score every dimension honestly. Do NOT give yourself a pass out of convenience.
+3. If the critique reveals gaps, fix them in the report before delivering.
+
+## Workflow
+
+Use the embedded workflow sections:
+- `<work_workflow>` — for Phase 1 (executing the plan)
+- `<work_critique>` — for Phase 2 (critiquing the execution)
+
+## Report
+
+Return markdown only with these tags:
+1. `<observations>...</observations>`
+2. `<execution-report>...</execution-report>`
+3. `<work-critique>...</work-critique>`
+4. `<risks>...</risks>`

data/CHANGELOG.md

@@ -0,0 +1,266 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+## [0.13.0] - 2026-03-24
+
+### Changed
+- Rewrote "How It Works" and docs to emphasize chained feedback: each step's output feeds the next, and synthesis gathers all stage feedback to propose improvements and produce revised source artifacts.
+- Aligned README tagline and gemspec summary/description to unified framing.
+- Added experimental status note to README.
+- Removed demo GIF reference from README (dry-run hangs due to unguarded provider calls; tape has TODO).
+- Updated demo tape with sandbox-free layout and TODO for dry-run fix.
+
+## [0.12.0] - 2026-03-23
+
+### Changed
+- Refreshed `README.md` to align with the current package layout pattern, including top-level docs navigation, use-case framing, integration links, and updated feature wording.
+
+## [0.11.1] - 2026-03-22
+
+### Fixed
+- Corrected handbook documentation links in `docs/handbook.md` so skill and workflow references resolve correctly.
+- Updated usage guidance to document that `--dry-run` cannot be combined with `--writeback`, matching runtime validation behavior.
+
+### Changed
+- Re-recorded `docs/demo/ace-sim-run.gif` from the package tape so the demo reflects `ace-sim` behavior instead of a placeholder asset.
+
+## [0.11.0] - 2026-03-22
+
+### Added
+- Rebuilt package documentation as a landing-page experience with updated README, getting-started tutorial, usage reference, and handbook catalog.
+
+### Changed
+- Added a generated VHS demo tape and screenshot for the documented getting-started workflow.
+- Updated gem metadata text to reflect the new documentation-first positioning.
+
+### Fixed
+- Corrected validate-task chain phase numbering for `plan` and `work` steps so file artifacts use absolute phase indices (`02-plan`, `03-work`) when draft is intentionally omitted.
+- Require explicit `--synthesis-workflow` when `--synthesis-provider` is provided, preventing preset default fallback from masking invalid provider/workflow combinations.
+
+## [0.10.0] - 2026-03-20
+
+### Changed
+- Expanded `TS-SIM-001-next-phase-smoke` E2E coverage with two new goals: `validate-task` preset contract validation and deterministic synthesis-provider guard failure validation.
+- Strengthened existing verifier assertions for help-surface flags and explicit single-step override behavior.
+
+## [0.9.1] - 2026-03-18
+
+### Changed
+- Migrated CLI namespace from `Ace::Core::CLI::*` to `Ace::Support::Cli::*` (ace-support-cli is now the canonical home for CLI infrastructure).
+
+
+## [0.9.0] - 2026-03-18
+
+### Changed
+- Removed legacy backward-compatibility behavior as part of the 0.10 cleanup release.
+
+
+## [0.8.8] - 2026-03-17
+
+### Changed
+- Raised `TS-SIM-001-next-phase-smoke` E2E timeout from default to 15 minutes (`900` seconds).
+
+## [0.8.7] - 2026-03-15
+
+### Fixed
+- Made E2E handoff-check comparison step explicit so the runner produces non-empty verification artifacts
+
+## [0.8.6] - 2026-03-15
+
+### Changed
+- Migrated CLI framework from dry-cli to ace-support-cli
+
+## [0.8.5] - 2026-03-13
+
+### Changed
+- Updated the canonical simulation skill to explicitly run its bundled workflow in the current project and execute it end-to-end.
+
+### Fixed
+- Restored the built-in `validate-idea` and `validate-task` synthesis preset defaults to `claude:haiku` so default end-to-end simulations use the stable shipped synthesis path again.
+
+## [0.8.4] - 2026-03-13
+
+### Changed
+- Updated the `TS-SIM-001` default preset E2E scenario to verify the shipped preset contract and chained handoff behavior while accepting either successful synthesis or a cleanly recorded final-stage failure.
+
+## [0.8.2] - 2026-03-13
+
+### Changed
+- Updated the full-chain synthesis E2E scenario to verify complete chain aggregation and recorded final-stage outcomes, including cleanly captured external synthesis failures.
+
+## [0.8.1] - 2026-03-12
+
+### Fixed
+- Switched simulation bundle/stage/final synthesis subprocess execution to the shared core command executor so failed external commands do not leak Ruby thread-read exceptions into run output handling.
+
+### Technical
+- Expanded simulation runner coverage to verify failed final synthesis still leaves inspection artifacts such as `synthesis.yml` and final input/source files.
+
+## [0.8.0] - 2026-03-10
+
+### Added
+- Added the canonical handbook-owned simulation skill for scenario/provider comparison flows.
+
+
+## [0.7.2] - 2026-03-04
+
+### Changed
+- Default simulation cache root now uses `.ace-local/sim`.
+
+
+## [0.7.1] - 2026-03-04
+
+### Fixed
+- Usage docs artifact paths corrected to short-name convention (`.ace-local/sim/` not `.ace-local/ace-sim/`)
+
+## [0.7.0] - 2026-03-04
+
+### Changed
+- Default session store directory migrated from `.cache/ace-sim` to `.ace-local/sim`
+
+## [0.6.0] - 2026-02-28
+
+### Changed
+- **BREAKING**: `--source` now accepts multiple values via repeatable flag (not CSV parsing)
+- `--source` values passed directly to `ace-bundle` without Ruby preprocessing
+- `SourceResolver` deleted - ace-bundle handles glob expansion and file resolution
+- `SimulationSession.source` is now an array instead of string
+
+### Removed
+- CSV parsing for comma-separated sources (use multiple `--source` flags)
+- Ruby glob expansion (ace-bundle handles this)
+- `SourceResolver` molecule (171 lines removed)
+
+## [0.5.1] - 2026-02-28
+
+### Fixed
+- Simplify nil guard in `FinalSynthesisExecutor#copy_source` to use `||` operator
+
+## [0.5.0] - 2026-02-28
+
+### Added
+- Multi-file input support via `--source` flag (repeatable)
+- `SourceBundler` molecule creates bundle YAML and invokes `ace-bundle`
+- Writeback guard: error when `--writeback` used with multiple sources
+
+### Fixed
+- Update preset provider assertions in command tests
+
+## [0.4.4] - 2026-02-28
+
+### Changed
+- Update `sim/run` workflow: when source is a task with usage documentation (`ux/usage.md`), include both spec and usage files via comma-separated `--source` to provide behavioral acceptance context
+
+## [0.4.3] - 2026-02-28
+
+### Fixed
+- Add missing "Apply Validated Changes" step (Step 4) to `sim/run` workflow so simulation refinements are written back to original source files, not left only in the simulation cache folder
+
+### Technical
+- Update model providers in `validate-task` preset
+
+## [0.4.2] - 2026-02-28
+
+### Added
+- Add `sim/run` workflow instruction (`handbook/workflow-instructions/sim/run.wf.md`) for codified simulation execution
+- Add `ace-sim-run` Claude skill for `/ace-sim-run` invocation
+- Add WFI sources registration for `wfi://sim/*` protocol discovery
+
+## [0.4.1] - 2026-02-28
+
+### Added
+- Add built-in preset defaults so `validate-idea` and `validate-task` can run with only `--source`.
+- Add default synthesis workflow/provider mappings in preset files:
+  - `validate-idea` -> `wfi://idea/review` + `claude:haiku`
+  - `validate-task` -> `wfi://task/review` + `claude:haiku`
+
+### Changed
+- Update README and usage docs to show source-only preset invocations.
+- Update run command tests to assert default preset contract values for provider and synthesis settings.
+
+## [0.4.0] - 2026-02-27
+
+### Added
+- Add optional final synthesis stage with `--synthesis-workflow` and `--synthesis-provider` run flags.
+- Add `final/suggestions.report.md` run artifact generation with deterministic bundle/prompt/report files.
+- Add `FinalSynthesisExecutor` molecule and unit tests for success/failure paths.
+
+### Changed
+- Extend simulation session/synthesis metadata with `synthesis_workflow`, `synthesis_provider`, and `final_stage`.
+- Mark run as failed when final synthesis is enabled and fails.
+- Update docs and CLI examples for final suggestions synthesis usage.
+
+## [0.3.3] - 2026-02-27
+
+### Changed
+- Extract `normalize_list` helper to `Ace::Sim` module, replacing inline array normalization in CLI commands and session model
+- Simplify `SourceResolver#resolve` to return minimal `{"path" => expanded}` hash
+- Extract `chain_status` method from `SimulationRunner` to `SynthesisBuilder`
+- Replace `value_from`/`present?`/`normalized_providers` helpers with `pick_value` and `normalize_list`
+- Restore `dry_run?` predicate on `SimulationSession` and update all callers
+- Remove `writeback?` predicate (use `writeback` attribute directly)
+- Remove source-empty validation from `SimulationSession#validate!` (validated upstream)
+
+## [0.3.2] - 2026-02-27
+
+### Fixed
+- Handle unhandled runtime exceptions in `SimulationRunner#run` by rescuing `StandardError` and returning structured failure result
+
+## [0.3.1] - 2026-02-27
+
+### Changed
+- Add self-critic pattern to `plan.md` step: Phase 1 (Build) / Phase 2 (Critique) with `wfi://task/review-plan` embedding
+- Add self-critic pattern to `work.md` step: Phase 1 (Execute) / Phase 2 (Critique) with `wfi://task/review-work` embedding
+- Rename `<changes>` output tag to `<execution-report>` in work step for clarity
+
+## [0.3.0] - 2026-02-27
+
+### Added
+- Enforce `--source` as a readable file path and copy source bytes directly to first-step `input.md`.
+- Add strict, section-rich default step bundle templates for `draft`, `plan`, and `work` with explicit workflow/reporting structure.
+
+### Changed
+- Rewrite step runtime to markdown-first artifacts: `input.md`, `user.bundle.md`, `user.prompt.md`, `output.md`.
+- Update chain execution to pass `output.md` directly into the next step as `input.md`.
+- Update docs, help examples, and E2E scenario content to the markdown chain contract.
+
+## [0.2.0] - 2026-02-27
+
+### Changed
+- Rebuilt runtime as minimal file-chained simulation: each step reads `input.yml`, writes `output.yml`, and output feeds next step.
+- `ace-sim run` is now preset-driven with canonical `--preset` flag (no scenario flow).
+- Added strict precedence model: CLI explicit flags override preset values, which override global defaults.
+- Replaced step contract model with bundle-based step configs (`.ace/sim/steps/*.md`, fallback `.ace-defaults/sim/steps/*.md`).
+- Replaced scenario defaults with preset defaults (`.ace-defaults/sim/presets/validate-idea.yml`).
+- Provider execution now runs independent chains for each provider x repeat with failure isolation.
+
+### Removed
+- Scenario-specific machinery and schema-heavy step validation requirements.
+- Final `result.yml` artifact path in favor of chain and synthesis artifacts.
+- Default scenario file `.ace-defaults/sim/scenarios/next-phase.yml`.
+
+## [0.1.3] - 2026-02-27
+
+### Fixed
+- Disable YAML alias parsing for untrusted LLM output (security hardening)
+- Align config loading with ADR-022 pattern using Config::Models::Config.wrap
+- Remove redundant `--no-writeback` CLI flag; writeback defaults to false
+- Align dry-cli version constraint to `~> 1.0` matching monorepo convention
+
+## [0.1.2] - 2026-02-27
+
+### Fixed
+- Validate `--scenario` CLI argument against configured scenarios; reject unknown scenarios with clear error
+- Mark stage run as failed when ace-llm succeeds but output file is not created
+- Initialize output_path before rescue block to prevent nil in error reports
+- Remove redundant attr_reader shadowed by lazy initializer method
+
+## [0.1.1] - 2026-02-27
+
+### Added
+- Initial `ace-sim` package scaffold.
+- `ace-sim run` CLI for next-phase simulation execution.
+- Session/stage/synthesis artifact generation under `.cache/ace-sim/simulations/`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michal Czyz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,40 @@
+<div align="center">
+  <h1> ACE - Sim </h1>
+
+  Multi-provider LLM simulation chains for validating ideas and reviewing tasks before implementation.
+
+  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <br><br>
+
+  <a href="https://rubygems.org/gems/ace-sim"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-sim.svg" /></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
+
+</div>
+
+> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
+
+> **Experimental** — its already proof its worth, but need some more work.
+ 
+[Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md)
+
+`ace-sim` executes preset-driven simulation chains (sequential step runs per provider) across one or more providers via [ace-llm](../ace-llm), then optionally synthesizes suggestions and revised source artifacts for follow-up work. Use `/as-sim-run` to launch simulations from inside a coding agent.
+
+## How It Works
+
+1. Select a simulation preset (`validate-idea` or `validate-task`) and provide a source file, with context assembled by [ace-bundle](../ace-bundle).
+2. The simulation engine runs each step (draft, plan, work) sequentially — each step's output feeds as input into the next, building on prior reasoning through [ace-llm](../ace-llm).
+3. After all steps complete, a final synthesis stage gathers feedback from every stage to propose improvements, surface questions, and produce a revised source artifact — feeding better specs back into [ace-task](../ace-taskflow) or sharper ideas into [ace-idea](../ace-idea).
+
+## Use Cases
+
+**Validate ideas before committing to implementation** - run `validate-idea` to compare model reasoning across providers and stress-test assumptions from a single source file.
+
+**Review task specs before coding starts** - run `validate-task` to inspect plan/work outputs across providers and iteration counts, keeping [ace-task](../ace-task) specs sharp before delivery begins.
+
+**Compare provider behavior under the same workflow** - use repeated `--provider` and `--repeat` options to evaluate consistency and convergence in [ace-llm](../ace-llm) simulation outputs.
+
+**Synthesize recommendations from simulation runs** - enable `--synthesis-workflow` and `--synthesis-provider` to produce actionable suggestions, then feed results into [ace-review](../ace-review) for follow-up review.
+
+---
+[Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md) | Part of [ACE](https://github.com/cs3b/ace)

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test" << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task spec: :test
+task default: :test

data/docs/demo/ace-sim-run.tape.yml

@@ -0,0 +1,24 @@
+---
+# TODO: --dry-run does not skip ace-llm provider calls (flag is metadata-only),
+#   so the run scene hangs. Fix ace-sim dry-run to skip stage execution, then re-enable.
+description: Showcase ace-sim CLI help and dry-run
+tags:
+- ace-sim
+- docs
+- getting-started
+settings:
+  font_size: 12
+  width: 960
+  height: 540
+  format: gif
+  env:
+    PROJECT_ROOT_PATH: /home/mc/ace-t.5nx
+scenes:
+- name: Switch to project root for gem resolution
+  commands:
+  - type: cd $PROJECT_ROOT_PATH && clear
+    sleep: 1s
+- name: Show help
+  commands:
+  - type: ace-sim run --help
+    sleep: 4s

data/docs/getting-started.md

@@ -0,0 +1,95 @@
+---
+doc-type: user
+title: ace-sim Getting Started
+purpose: Tutorial for first-run ace-sim workflows
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# Getting Started with ace-sim
+
+`ace-sim` gives you a controlled way to validate ideas and tasks with multiple LLMs before you make changes.
+
+## 1. Prerequisites
+
+- Ruby 3.2+
+- `ace-sim` installed
+- `vhs` installed when you want to run the demonstration recording
+- Access to at least one LLM provider configured in your environment
+
+## 2. Prepare your source
+
+`ace-sim` reads one or more markdown sources. A source can be:
+
+- A draft issue file
+- A task specification
+- A short prompt file for idea checks
+
+## 3. First dry-run simulation
+
+Use a dry run to inspect the plan without executing providers:
+
+```bash
+ace-sim run --preset validate-idea --source idea.md --dry-run
+```
+
+Expected behavior:
+
+- A run is prepared with a generated run directory under `.ace-local/sim/simulations/<run-id>`
+- No final artifacts are written by providers because dry-run disables mutations
+- You can still inspect the run metadata output in the command result
+
+## 4. Understand the output
+
+Each run produces a directory under `.ace-local/sim/simulations/<run-id>/`:
+
+- `input.md` and `input.bundle.md` — the bundled source used as initial input
+- `chains/<provider>-<iteration>/` — step-by-step outputs where each step's result feeds into the next (draft -> plan -> work)
+- `final/` — synthesis results that gather feedback from all stages, propose improvements, and produce a revised source artifact
+
+The chain is sequential: each step builds on the previous step's output, so the final work step has the benefit of the draft and plan reasoning before it. The synthesis stage then reviews everything to surface questions and actionable suggestions.
+
+## 5. Run for real
+
+Remove `--dry-run` to execute real simulation providers:
+
+```bash
+ace-sim run --preset validate-idea --source idea.md
+```
+
+## 6. Validate a task
+
+Use the task preset for task-oriented review:
+
+```bash
+ace-sim run --preset validate-task --source path/to/task.s.md
+```
+
+`validate-task` defaults to a shorter `plan -> work` flow with task-oriented synthesis.
+
+## 7. Override providers
+
+You can compare outputs by provider:
+
+```bash
+ace-sim run --preset validate-task --source task.md --provider codex:mini --provider google:gflash
+```
+
+## 8. Common commands
+
+| Goal | Command |
+|---|---|
+| Run idea validation (dry) | `ace-sim run --preset validate-idea --source idea.md --dry-run` |
+| Run task validation | `ace-sim run --preset validate-task --source task.md` |
+| Use a different provider mix | `ace-sim run --preset validate-task --source task.md --provider codex:mini --provider google:gflash` |
+| Repeat each provider chain | `ace-sim run --preset validate-task --source task.md --repeat 2` |
+| See full command reference | [`docs/usage.md`](usage.md) |
+
+## 9. What to try next
+
+- Add a custom step override (`--steps`) to focus on only `plan` or only `work`
+- Pair with `--repeat` for stress-testing convergence
+- Use `--synthesis-workflow` for custom review logic
+- Explore all switches in [`docs/usage.md`](usage.md)
+