Document production-ready ramp and add run diagnostics

Update docs around the project goal: liquid-spec is an implementation
harness for gradually building a full production-ready Liquid engine. Align
AGENTS/CLAUDE, README, SPECS, generated init docs, and the complexity guide
with the current 0-1000 ramp: trivial passthrough first, then literals,
variables, control flow, standard features, compatibility quirks, and
production recordings.

Add dumb-adapter audit guidance and warn that raw pass counts can be
misleading for naive implementations; Max complexity reached is the better
progress signal. Document using source-echo, always-empty, and always-raise
adapters to catch weak specs and confusing failures.

Add runner diagnostics:
- --list-passed prints passing specs with complexity/source for ramp audits.
- --json emits a single non-benchmark JSON summary with totals, failures,
  skipped suites, max complexity, and optional passed specs.

Also include a well-hinted complexity-500 self[...] nested-loop scope spec for
dynamic lookup publication across nested loops.

Author: tobi

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What This Project Is
 
-liquid-spec is a test suite and CLI for testing Liquid template implementations. It captures test cases from the reference Shopify/liquid implementation and can verify that any Liquid implementation produces correct output.
+liquid-spec is a test suite and CLI for testing Liquid template implementations. Its purpose is to act as a harness for the gradual construction of a full, production-ready Liquid implementation: start with trivial passthrough specs, then progressively add variables, filters, control flow, partials, compatibility quirks, and finally production/theme recordings. It captures test cases from the reference Shopify/liquid implementation and can verify that any Liquid implementation produces correct output.
 
 ## CLI Usage
 
@@ -38,6 +38,25 @@ liquid-spec my_adapter.rb -l
 liquid-spec my_adapter.rb --list-suites
 ```
 
+
+### Dumb Adapter Ramp Audits
+
+When changing early complexity scores or adding beginner specs, play dumb and verify the harness still behaves like an implementation curriculum:
+
+```bash
+# Source echo adapter: should pass only raw text, then fail on first object output
+liquid-spec /tmp/echo_adapter.rb -s basics --max-failures 3 --list-passed
+
+# Always-empty adapter: may pass many empty-output specs accidentally; check max complexity
+liquid-spec /tmp/empty_adapter.rb -s basics --json --list-passed > /tmp/empty-results.json
+
+# Always-raise adapters: should fail at complexity 0 with clear Error + Hint output
+liquid-spec /tmp/raise_compile_adapter.rb -s basics --max-failures 3
+liquid-spec /tmp/raise_render_adapter.rb -s basics --max-failures 3
+```
+
+Use `--list-passed` to inspect accidental passes and `--json` for tooling. Prefer `Max complexity reached` / `max_complexity_reached` over raw pass count when judging partial or deliberately naive adapters.
+
 ### Result Logging
 
 Each test run appends results to `/tmp/liquid-spec-results.jsonl` with the format:
@@ -73,10 +92,11 @@ LiquidSpec.setup do |ctx|
 end
 
 LiquidSpec.configure do |config|
-  config.suite = :liquid_ruby  # :all, :liquid_ruby, :shopify_theme_dawn
-  config.features = [
-    :core,                  # Basic Liquid parsing/rendering
-  ]
+  config.suite = :liquid_ruby  # :all, :basics, :liquid_ruby, :shopify_theme_dawn
+
+  # Declare what your adapter cannot support yet. Specs requiring these
+  # features are skipped so you can build incrementally.
+  config.missing_features = [:shopify_tags, :shopify_filters]
 end
 
 LiquidSpec.compile do |ctx, source, parse_options|
@@ -230,6 +250,17 @@ Spec-level settings override source-level settings. For example, a spec with its
 
 ## Good Specs
 
+Good specs preserve the project goal: help someone build a production-ready Liquid implementation gradually. A spec should teach one behavior at the right time, fail with an actionable message, and point to implementation guidance when the behavior is not obvious.
+
+### Ramp discipline
+
+- First-contact specs for a feature must be tiny, gentle, and hinted. If needed, score the first spec one point lower than follow-up specs so it appears first.
+- Keep the 0-50 band boring: passthrough, literals, missing variables, simple variable lookup, a few simple filters, and assign.
+- Keep whitespace control (`{{-`, `-}}`, `{%-`, `-%}`), drop/to_liquid boundaries, generated filter matrices, parser recovery, date/time quirks, and filesystem/security quirks out of the beginner band.
+- Generated specs should not flood the early ramp. Prefer curated beginner specs early; generated compatibility breadth generally starts at 120+ or much later.
+- If a dumb adapter that returns the input, returns `""`, or raises for everything passes a spec unexpectedly, either the spec is too weak or the complexity/hint needs review.
+- When judging naive adapters, prefer `Max complexity reached` over total pass count. An always-empty adapter can pass later specs whose correct output is empty, but it should not advance through the contiguous ramp.
+
 ### Error specs: prefer raised errors over inline errors
 
 Most specs that exercise an error path should let the error **raise** and
@@ -376,20 +407,20 @@ defaults:
 
 ### Complexity Scoring
 
-Each spec should have a `complexity` field indicating implementation difficulty. Lower scores = simpler features to implement first. Specs without explicit complexity default to 1000 or the suite's `minimum_complexity`.
+Each spec should have a `complexity` field indicating implementation difficulty. Lower scores = simpler features to implement first. Specs without explicit complexity default to 1000 or the suite's `minimum_complexity`. Complexity is capped at 1000; do not score specs above 1000.
 
 | Range | Feature |
 |-------|---------|
-| 10-20 | Literals, raw text output |
-| 30-50 | Variables, filters, assign |
-| 55-60 | Whitespace control, if/else/unless |
-| 70-80 | For loops, operators, filter chains |
-| 85-100 | Math filters, forloop object, capture, case/when |
-| 105-130 | String filters, increment, comment, raw, echo, liquid tag |
-| 140-180 | Array filters, property access, truthy/falsy, cycle, tablerow |
-| 190-220 | Advanced: offset:continue, parentloop, partials |
-| 300-500 | Edge cases, deprecated features |
-| 1000+ | Production recordings, unscored specs (default) |
+| 0-1 | Foundation: empty template, literal passthrough, whitespace/newline preservation |
+| 5-20 | First object output and literal breadth: strings, numbers, booleans, nil-as-empty |
+| 30-50 | Variables, missing variables, very simple filters, assign |
+| 55-65 | Basic if/else/unless and simple boolean composition |
+| 70-100 | Gentle loops, comparisons, forloop basics, capture, simple case/when |
+| 105-150 | Common filters/tags: string filters, comment/raw, increment, interrupts, loop modifiers, whitespace control |
+| 160-220 | Generated filter breadth, truthy/falsy edge cases, cycle/tablerow, first partials/filesystem, Ruby/reference quirks |
+| 230-400 | Long-tail standard behavior: advanced lookup, parser edge cases, scope/filesystem interactions |
+| 500-900 | Mature compatibility: parser mutation matrices, recursion/resource limits, security-sensitive quirks, date/time/Ruby quirks |
+| 1000 | Production recordings and unscored specs (default) |
 
 See [`liquid-spec docs complexity`](`liquid-spec docs complexity`) for the full guide with examples.
 See [SPECS.md](SPECS.md) for guidelines on writing effective specs.
@@ -402,41 +433,33 @@ See [SPECS.md](SPECS.md) for guidelines on writing effective specs.
 
 ### Features
 
-Adapters declare which features they support. Suites and individual specs can require specific features:
+Adapters declare which features they do **not** support yet. Suites and individual specs can require capabilities; any required capability listed in `missing_features` is skipped so implementations can grow incrementally:
 
 ```ruby
 LiquidSpec.configure do |config|
-  config.features = [:core, :shopify_tags]
+  # Empty means "try every spec". Add unsupported capabilities here.
+  config.missing_features = [:shopify_tags]
 end
 ```
 
 ### Available Features
 
-The `:core` feature is the recommended target for most implementations. It's an alias that automatically expands to include other essential features:
-
-```ruby
-# From lib/liquid/spec/cli/adapter_dsl.rb
-FEATURE_EXPANSIONS = {
-  core: [:runtime_drops, :inline_errors],
-}
-```
-
-**Core features (most implementations should declare `:core`):**
-- `:core` - Full Liquid implementation. Expands to include `:runtime_drops` and `:inline_errors`
-- `:runtime_drops` - Supports bidirectional communication for drop callbacks (test harness invokes adapter to access drop properties)
-- `:inline_errors` - Errors are rendered inline in output rather than raised as exceptions
-- `:strict_parsing` - Supports error_mode: :strict (default for most implementations)
+Feature selection is denylist-based. Leave `missing_features` empty to try everything, or add unsupported capabilities while the implementation is still growing.
 
-**Optional features:**
-- `:lax_parsing` - Supports error_mode: :lax for lenient parsing
-- `:ruby_types` - Supports Ruby-specific types in environment (Integer, Float, Range, etc.)
+**Common features to list in `missing_features`:**
+- `:runtime_drops` - Adapter cannot support bidirectional drop callbacks yet
+- `:inline_errors` - Adapter cannot render errors inline yet
+- `:lax_parsing` - Adapter does not support `error_mode: :lax`
+- `:ruby_types` / `:ruby_drops` / `:binary_data` - Adapter cannot consume Ruby-specific values from specs
+- `:template_factory` - Adapter cannot support template factory/artifact callbacks
 
 **Shopify-specific features:**
 - `:shopify_tags` - Shopify-specific tags (schema, style, section)
 - `:shopify_objects` - Shopify-specific objects (section, block)
 - `:shopify_filters` - Shopify-specific filters (asset_url, image_url)
+- `:shopify_includes`, `:shopify_blank`, `:shopify_error_handling`, `:shopify_error_format`, `:shopify_string_access` - Shopify platform/theme behavior beyond portable Liquid
 
-**JSON-RPC adapters** that can't support bidirectional communication for runtime drops should declare `features = []` to opt out of `:core` and `:runtime_drops`. They will still run all specs except those requiring `:runtime_drops`.
+**JSON-RPC adapters** that can't support bidirectional communication for runtime drops should set `config.missing_features = [:runtime_drops, :ruby_types, :ruby_drops, :binary_data]` (plus any Shopify capabilities they lack).
 
 ## The Eval Tool
 
@@ -490,7 +513,7 @@ For complex tests, use YAML input via stdin or file:
 cat <<EOF | liquid-spec eval adapter.rb --compare
 name: test_for_loop_with_break
 hint: "break should exit the loop immediately"
-complexity: 75
+complexity: 120
 template: |
   {% for i in (1..5) %}
     {% if i == 3 %}{% break %}{% endif %}

README.md

@@ -2,12 +2,13 @@
 
 [![CI](https://github.com/Shopify/liquid-spec/actions/workflows/ruby.yml/badge.svg)](https://github.com/Shopify/liquid-spec/actions/workflows/ruby.yml)
 
-A conformance test suite for [Liquid](https://github.com/Shopify/liquid) template implementations. Run **4,600+ test cases** extracted from Shopify's reference implementation to verify your Liquid parser/renderer produces correct output.
+A conformance test suite for [Liquid](https://github.com/Shopify/liquid) template implementations. Run **7,000+ test cases** extracted from Shopify's reference implementation, curated basics, parser-error matrices, Dawn theme fixtures, and production recordings to verify your Liquid parser/renderer produces correct output.
 
 ## Why liquid-spec?
 
 Building a Liquid implementation (compiler, interpreter, or transpiler)? liquid-spec helps you:
 
+- **Build gradually** from an empty-template renderer into a production-ready Liquid implementation
 - **Verify correctness** against the reference Shopify/liquid behavior
 - **Catch regressions** when optimizing or refactoring
 - **Discover edge cases** you might not have considered
@@ -152,30 +153,36 @@ regular runs.
 
 | Suite | Tests | Description |
 |-------|-------|-------------|
-| **basics** | 183 | Essential Liquid features - start here! Ordered by complexity with implementation hints |
-| **liquid_ruby** | ~1,700 | Core Liquid specs from [Shopify/liquid](https://github.com/Shopify/liquid) integration tests |
-| **shopify_production_recordings** | ~3,000 | Recorded behavior from Shopify's production Liquid compiler |
+| **basics** | 850 | Essential Liquid features - start here! Ordered by complexity with implementation hints |
+| **liquid_ruby** | 2,101 | Core Liquid specs from [Shopify/liquid](https://github.com/Shopify/liquid) integration tests |
+| **liquid_ruby_lax** | 121 | Lax-mode reference behavior |
+| **parser_errors** | 1,901 | Strict parser error compatibility and mutation matrices |
+| **partials** | 12 | Include/render focused compatibility specs |
+| **shopify_production_recordings** | 2,260 | Recorded behavior from Shopify's production Liquid compiler |
 | **shopify_theme_dawn** | 26 | Real-world templates from [Shopify Dawn](https://github.com/Shopify/dawn) theme |
 
 ### The Basics Suite
 
 If you're building a new Liquid implementation, **start with the basics suite**. It runs first and covers all fundamental features from the [official Liquid documentation](https://shopify.github.io/liquid/).
 
-Specs are ordered by complexity so you can implement features progressively:
+Specs are ordered by complexity so you can implement features progressively. The goal is a smooth ramp: a toy renderer should pass only the trivial first specs, then fail on a small, actionable next behavior.
 
 | Complexity | Features |
 |------------|----------|
-| 10-20 | Raw text output, string/number/boolean literals |
-| 30-40 | Variables, basic filters (upcase, size, default) |
-| 50-60 | Assign tag, simple if/else conditionals |
-| 70-80 | For loops, filter chains, comparison operators |
-| 85-90 | Math filters, forloop object, capture tag |
-| 100-110 | Case/when, elsif, string manipulation filters |
-| 115-130 | Increment/decrement, comments, echo, liquid tag |
-| 140-150 | Array filters, property access (dot/bracket notation) |
-| 170-180 | Truthy/falsy edge cases, cycle, tablerow |
-
-Each spec includes a detailed `hint` explaining how the feature should be implemented.
+| 0-1 | Empty template and literal passthrough |
+| 5-20 | First object output, literal strings/numbers/booleans/nil |
+| 30-50 | Variables, missing variables, very simple filters, assign |
+| 55-65 | Basic if/else/unless and simple boolean composition |
+| 70-100 | Gentle loops, comparisons, forloop basics, capture, simple case/when |
+| 105-150 | Common filters/tags, comments/raw, interrupts, loop modifiers, whitespace control |
+| 160-220 | Generated filter breadth, truthy/falsy edges, cycle/tablerow, first partials/filesystem |
+| 230-400 | Long-tail standard behavior and parser/scope/filesystem edge cases |
+| 500-900 | Mature compatibility: parser mutations, recursion/resource limits, date/time/Ruby quirks |
+| 1000 | Production recordings and unscored specs |
+
+Each non-trivial spec includes a detailed `hint` explaining how the feature should be implemented. If the first failure is surprising or unactionable, the spec probably needs a better hint or a higher complexity score.
+
+**Read `Max complexity reached`, not just total passes.** A naive adapter that always returns `""` can accidentally pass many later specs whose expected output is empty, but its max reached complexity should remain at 0. The max-complexity line tells you how far the implementation progressed through the ordered curriculum.
 
 ### Feature-Based Suite Selection
 
@@ -215,6 +222,9 @@ Run Options:
   --list-suites            List available test suites
   --max-failures N         Stop after N failures (default: 10)
   --no-max-failures        Run all specs without stopping
+  --list-passed           List specs that passed after the run (ramp/debug audits)
+  --json                  Output a single JSON summary (for tools)
+  --jsonl                 Output one JSON event per line (for benchmark streaming/tools)
   -h, --help               Show help
 
 Examples:
@@ -228,6 +238,24 @@ Examples:
   liquid-spec inspect my_adapter.rb -n "case"      # Debug specific specs
 ```
 
+
+### Auditing the Ramp with Dumb Adapters
+
+When changing complexity scores or adding early specs, test the harness with intentionally bad adapters:
+
+- an adapter that returns the template source unchanged
+- an adapter that always returns `""`
+- an adapter that raises during compile or render
+
+Use `--list-passed` to see accidental passes and `--json` for machine-readable analysis:
+
+```bash
+liquid-spec /tmp/echo_adapter.rb -s basics --max-failures 3 --list-passed
+liquid-spec /tmp/empty_adapter.rb -s basics --json --list-passed > empty-results.json
+```
+
+A source-echo adapter should only pass raw-text specs before failing on first object output. An always-empty adapter may pass many empty-output specs, so judge progress by `max_complexity_reached`, not by total passes.
+
 ### Matrix Command
 
 The `matrix` command runs specs across multiple adapters simultaneously and shows differences between implementations. This is useful for comparing behavior across different Liquid implementations or configurations.
@@ -442,15 +470,17 @@ Specs are automatically saved to `/tmp/liquid-spec-{date}.yml` for easy contribu
 ```
 $ liquid-spec examples/liquid_ruby.rb
 
-Features: core, lax_parsing
+Missing features: shopify_tags, shopify_objects, shopify_filters
 
-Basics ................................. 183/183 passed
-Liquid Ruby ............................ 1683/1683 passed
-Liquid Ruby (Lax Mode) ................. 6/6 passed
-Shopify Production Recordings .......... 2338/2338 passed
-Shopify Theme Dawn ..................... skipped (needs shopify_tags, shopify_objects, shopify_filters)
+Basics ................................. 850/850 passed
+Liquid Ruby ............................ 2101/2101 passed
+Liquid Ruby (Lax Mode) ................. 121/121 passed
+Parser Errors .......................... 1901/1901 passed
+Partials ............................... 12/12 passed
+Shopify Production Recordings .......... 2260/2260 passed
+Shopify Theme Dawn ..................... skipped (adapter opts out of: shopify_filters)
 
-Total: 4210 passed, 0 failed, 0 errors
+Total: 7245 passed, 0 failed, 0 errors
 ```
 
 ## Example Adapters
@@ -484,7 +514,7 @@ Each spec defines:
 - **template** - Liquid source to compile and render
 - **environment** - Variables available during rendering
 - **expected** - Expected output string
-- **complexity** - Optional: ordering hint (lower = simpler, runs first)
+- **complexity** - Optional: ordering hint (lower = simpler, runs first; defaults to 1000 and must not exceed 1000)
 - **hint** - Optional: implementation guidance for this feature
 - **error_mode** - Optional: `:lax` or `:strict`
 - **filesystem** - Optional: mock files for include/render tags