Reframe liquid-spec as an agent implementation curriculum

Author: tobi

CLAUDE.md

@@ -197,14 +197,14 @@ When changing early complexity scores or adding beginner specs, play dumb and ve
 
 ```bash
 # Source echo adapter: should pass only raw text, then fail on first object output
-liquid-spec run /tmp/echo_adapter.rb -s basics --list-passed
+liquid-spec run /tmp/echo_adapter.rb --list-passed
 
 # Always-empty adapter: may pass many empty-output specs accidentally; check max complexity
-liquid-spec run /tmp/empty_adapter.rb -s basics --json --list-passed > /tmp/empty-results.json
+liquid-spec run /tmp/empty_adapter.rb --json --list-passed > /tmp/empty-results.json
 
 # Always-raise adapters: should fail at complexity 0 with clear Error + Hint output
-liquid-spec run /tmp/raise_compile_adapter.rb -s basics
-liquid-spec run /tmp/raise_render_adapter.rb -s basics
+liquid-spec run /tmp/raise_compile_adapter.rb
+liquid-spec run /tmp/raise_render_adapter.rb
 ```
 
 Use `--list-passed` to inspect accidental passes and `--json` for tooling. Prefer `Complexity level cleared` (or JSON `max_complexity_reached`) over raw pass count when judging partial or deliberately naive adapters.

README.md

@@ -472,14 +472,14 @@ Saved specs go to `/tmp/liquid-spec-{date}.yml`. Browse them:
 # Run all specs
 bundle exec rake run
 
-# Run specific suite
-liquid-spec run examples/liquid_ruby.rb -s basics
+# Run the default ordered ramp
+liquid-spec run examples/liquid_ruby.rb
 
 # Filter by name pattern
 liquid-spec run examples/liquid_ruby.rb -n tablerow
 
 # Compare multiple adapters
-liquid-spec matrix --adapters=a.rb,b.rb -s basics
+liquid-spec matrix --adapters=a.rb,b.rb
 ```
 
 ---

SPECS.md

@@ -123,7 +123,7 @@ Useful checkpoints:
 liquid-spec run my_adapter.rb
 
 # Audit accidental passes when building early behavior
-liquid-spec run my_adapter.rb -s basics --list-passed --json
+liquid-spec run my_adapter.rb --list-passed --json
 
 # Validate liquid-spec/spec changes when contributing to this repository
 rake check

docs/implementers/curriculum.md

@@ -37,7 +37,7 @@ Called once when the connection starts.
     "version": "1.0",
     "implementation": "my-liquid",
     "liquid_version": "6.0.0",
-    "features": ["runtime_drops"]
+    "features": ["drops"]
   }
 }
 ```
@@ -47,10 +47,10 @@ Called once when the connection starts.
 `features` is informational metadata reported by the subprocess. The Ruby adapter file still controls which specs run via `config.missing_features` because spec selection happens in liquid-spec, not inside the subprocess.
 
 Common feature names:
-- `runtime_drops` - Supports bidirectional drop callbacks (see Drop Callbacks section)
+- `drops` - Supports Liquid drop objects. Portable standard test drops are documented in `docs/test_drops.md`; the callback protocol below supports host-owned runtime drops.
 - `lax_parsing` - Supports `error_mode: lax`
 
-For a minimal JSON-RPC server, start with `features: []` and set the adapter's `config.missing_features` to skip unsupported capabilities such as `:runtime_drops`, `:lax_parsing`, `:ruby_types`, `:ruby_drops`, `:binary_data`, and Shopify-specific features.
+For a minimal JSON-RPC server, start with `features: []` and set the adapter's `config.missing_features` to skip unsupported capabilities such as `:drops`, `:lax_parsing`, `:ruby_types`, `:ruby_drops`, `:binary_data`, and Shopify-specific features.
 
 ### `compile`
 

docs/json-rpc-protocol.md

@@ -43,7 +43,7 @@ params. The `instantiate:ClassName.new(arg)` format passes a single argument.
 | `LoaderDrop` | Lazy-loading collection | `ruby_drops` |
 | `ArrayDrop` | Enumerable drop | `ruby_drops` |
 | `TestEnumerable` | Enumerable for loop tests | `ruby_drops` |
-| `ErrorDrop` | Raises errors during render | `runtime_drops` |
+| `ErrorDrop` | Raises errors during render | `drops` |
 | `StubTemplateFactory` | Template factory for partials | `template_factory` |
 | `SettingsDrop` | Shopify settings drop | `shopify_objects` |
 | `SecurityVictimDrop` | Security boundary tests | `ruby_drops` |
@@ -122,12 +122,12 @@ function unwrap_value(value):
     return value
 ```
 
-> **Note on `runtime_drops`:** The bidirectional RPC callback mechanism
-> (`drop_get`, `drop_call`, `drop_iterate`) is an alternative to boxed
-> objects. It's more flexible (the drop logic stays in Ruby) but slower
-> (every access is a round-trip) and more complex. For most implementations,
-> boxed objects are recommended. Only use `runtime_drops` if you need
-> drop behavior that can't be replicated with a static boxed implementation.
+> **Note on `drops`:** Portable standard test drops should normally be
+> implemented as native boxed objects as described in `docs/test_drops.md`.
+> The bidirectional RPC callback mechanism (`drop_get`, `drop_call`,
+> `drop_iterate`) is available for host-owned runtime drops whose behavior
+> cannot be reproduced statically. Both forms are part of drop support; there
+> is no separate feature for runtime-backed drops.
 
 **With `ruby_types`** (adapter handles Ruby-specific value formats):
 - You must handle `_ruby_type` markers (see below).
@@ -281,15 +281,15 @@ Do you need Shopify production compatibility?
 | (none) | Basic compile + render | ~4900 | Moderate |
 | `ruby_drops` | Drop callbacks + `_rpc_drop` handling | ~200 | Hard |
 | `ruby_types` | `_ruby_type` markers + Hash#inspect format | ~50 | Very hard (non-Ruby) |
-| `runtime_drops` | Bidirectional drop callbacks | ~20 | Hard |
+| `drops` | Standard test drops; callbacks when host-owned runtime objects are needed | ~20 | Hard |
 | `template_factory` | Template creation callbacks | ~10 | Moderate |
 | `lax_parsing` | Lax error mode (inline errors) | ~100 | Moderate |
 | `strict2_parsing` | Strict2 error mode | ~50 | Easy |
 
 **Recommendation for non-Ruby implementations:**
-1. Start with `missing_features = [:ruby_types, :ruby_drops, :binary_data, :runtime_drops, :template_factory, :lax_parsing, ...shopify_*]`
-2. Remove `:lax_parsing` first (easy, big gain).
-3. Remove `:ruby_drops` next (requires drop callbacks, big gain).
-4. Remove `:runtime_drops` (requires bidirectional callbacks).
+1. Start with `missing_features = [:drops, :ruby_types, :ruby_drops, :binary_data, :template_factory, :lax_parsing, ...shopify_*]`
+2. Remove `:lax_parsing` when legacy lenient parsing is part of your target.
+3. Remove `:drops` after implementing the portable standard test-drop library.
+4. Remove `:ruby_drops` only when Ruby-specific host objects are part of your target.
 5. Remove `:ruby_types` last (requires Ruby inspect emulation, small gain, hard).
 6. Only remove `:ruby_types` if you must be Shopify-production-compatible.

docs/json-rpc-type-transport.md

@@ -43,7 +43,7 @@
 end
 
 LiquidSpec.configure do |config|
-  # JSON-RPC adapters support core features including runtime_drops
+  # This JSON-RPC adapter supports core behavior including drops.
   # because they implement bidirectional callbacks
   config.missing_features = [:ruby_types, :ruby_drops, :binary_data, :lax_parsing, :template_factory, :shopify_filters, :shopify_includes, :shopify_blank, :shopify_error_handling, :shopify_error_format, :shopify_string_access]
 end

examples/json_rpc_ruby_liquid.rb

@@ -36,7 +36,7 @@ def parse_expression(markup, safe: false)
 end
 
 LiquidSpec.configure do |config|
-  config.missing_features = [:runtime_drops, :ruby_types, :ruby_drops, :binary_data, :template_factory, :shopify_filters, :shopify_includes, :shopify_blank, :shopify_error_handling, :shopify_error_format, :shopify_string_access]
+  config.missing_features = [:drops, :ruby_types, :ruby_drops, :binary_data, :template_factory, :shopify_filters, :shopify_includes, :shopify_blank, :shopify_error_handling, :shopify_error_format, :shopify_string_access]
 end
 
 LiquidSpec.compile do |ctx, source, parse_options|

examples/liquid_c.rb

@@ -24,7 +24,7 @@
 end
 
 LiquidSpec.configure do |config|
-  config.missing_features = [:runtime_drops, :ruby_types, :ruby_drops, :binary_data, :lax_parsing, :template_factory, :shopify_filters, :shopify_includes, :shopify_blank, :shopify_error_handling, :shopify_error_format, :shopify_string_access]
+  config.missing_features = [:drops, :ruby_types, :ruby_drops, :binary_data, :lax_parsing, :template_factory, :shopify_filters, :shopify_includes, :shopify_blank, :shopify_error_handling, :shopify_error_format, :shopify_string_access]
 end
 
 LiquidSpec.compile do |ctx, source, parse_options|

examples/liquid_c_strict.rb

@@ -61,7 +61,7 @@ module Init
           # @param ctx [Hash] Adapter context (from setup block)
           # @param source [String] The Liquid template source code
           # @param options [Hash] Parse options (e.g., :error_mode, :line_numbers)
-          # @return [Object] Your compiled template object (passed to render)
+          # Store the compiled template in ctx for the render block.
           #
           # ERROR MODES
           # -----------
@@ -90,18 +90,17 @@ module Init
             options[:error_mode] ||= :strict2
 
             # Example for Shopify/liquid:
-            #   Liquid::Template.parse(source, options)
+            #   ctx[:template] = Liquid::Template.parse(source, options)
             #
             # Example for a custom implementation:
-            #   MyLiquid::Template.new(source, error_mode: options[:error_mode])
+            #   ctx[:template] = MyLiquid::Template.new(source, error_mode: options[:error_mode])
             #
             raise NotImplementedError, "Implement LiquidSpec.compile to parse templates"
           end
 
-          # Called to render a compiled template with the given context.
+          # Called to render the template stored in ctx by the compile block.
           #
           # @param ctx [Hash] Adapter context (from setup block)
-          # @param template [Object] The compiled template (from compile block)
           # @param assigns [Hash] Variables available as {{ var }}
           # @param options [Hash] Render options (:registers, :strict_errors, :error_mode)
           # @return [String] The rendered output
@@ -113,17 +112,17 @@ module Init
           # to strict_errors: true (raise) — only specs that opt into render_errors
           # set it to false. Pass it through to your implementation so both modes work.
           #
-          LiquidSpec.render do |ctx, template, assigns, options|
+          LiquidSpec.render do |ctx, assigns, options|
             # Example for Shopify/liquid:
             #   context = Liquid::Context.build(
             #     static_environments: assigns,
             #     registers: Liquid::Registers.new(options[:registers] || {}),
             #     rethrow_errors: options[:strict_errors]
             #   )
-            #   template.render(context)
+            #   ctx[:template].render(context)
             #
             # Example for a custom implementation:
-            #   template.render(assigns, raise_errors: options[:strict_errors])
+            #   ctx[:template].render(assigns, raise_errors: options[:strict_errors])
             #
             raise NotImplementedError, "Implement LiquidSpec.render to render templates"
           end
@@ -348,24 +347,26 @@ module Init
           LiquidSpec.compile do |ctx, source, options|
             options[:error_mode] ||= :strict2
             ctx[:adapter].spec_context = ctx
-            ctx[:adapter].compile(source, options)
+            ctx[:template_id] = ctx[:adapter].compile(source, options)
           end
 
           # Render errors are raised by default (strict_errors: true). Only specs
           # that opt into render_errors set strict_errors to false.
-          LiquidSpec.render do |ctx, template_id, assigns, options|
+          LiquidSpec.render do |ctx, assigns, options|
             ctx[:adapter].spec_context = ctx
-            ctx[:adapter].render(template_id, assigns, options)
+            ctx[:adapter].render(ctx[:template_id], assigns, options)
           end
         RUBY
 
-        def self.agents_md_content(filename, json_rpc: false)
+        def self.agents_md_content(filename, json_rpc: false, both: false)
+          json_rpc_guide = json_rpc || both
+
           <<~MARKDOWN
             # Implementing a Liquid Template Engine
 
             You are building a production-grade [Liquid](https://shopify.github.io/liquid/)
             template engine. This directory is wired to **liquid-spec**, which defines what
-            "correct" means: 7,000+ executable specs, ordered by complexity from trivial
+            "correct" means: thousands of executable specs, ordered by complexity from trivial
             passthrough (score 0) to full production compatibility (score 1000). The suite
             is a curriculum for observable behavior, not a mandated internal architecture:
             tree-walking, bytecode, compiled templates, strict-first, and compatibility-first
@@ -379,7 +380,7 @@ def self.agents_md_content(filename, json_rpc: false)
             shims that exist only so liquid-spec can exercise your implementation. Build your
             library as a library; wire up the adapter afterward.
 
-            #{json_rpc ? non_ruby_notice : ""}
+            #{json_rpc_guide ? non_ruby_notice : ""}
             ## Which adapter file?
 
             - **Implementing in Ruby?** Use `liquid_adapter.rb`. It calls your code directly
@@ -517,7 +518,7 @@ def self.agents_md_content(filename, json_rpc: false)
 
             A common low-risk route is tokenizer → parser → node tree → tree-walking
             renderer with a scope stack. A compiler/VM is also fine if that fits your project,
-            but correctness across 7,000+ specs is the hard part, so keep the observable
+            but correctness across thousands of specs is the hard part, so keep the observable
             semantics easy to test. Two things ARE worth designing in from day one, because
             they weave through everything and are painful to retrofit:
 
@@ -541,7 +542,13 @@ def self.agents_md_content(filename, json_rpc: false)
             | 4 | 190-400 | Partials/filesystem, scope interactions, generated compatibility breadth |
             | 5 | 500-900 | Parser error matrices, error-model matrix, recursion/deep nesting, security/date/time/Ruby quirks |
             | 6 | 1000 | Production recordings and unscored mature-compatibility checks |
-            #{json_rpc ? json_rpc_section(filename) : ruby_adapter_section}
+            #{if both
+                "#{ruby_adapter_section}\n#{json_rpc_section(filename)}"
+              elsif json_rpc
+                json_rpc_section(filename)
+              else
+                ruby_adapter_section
+              end}
 
             ## Local specs for development
 
@@ -569,7 +576,6 @@ def self.agents_md_content(filename, json_rpc: false)
             liquid-spec run #{filename}                 # the loop
             liquid-spec run #{filename} -n case         # only specs matching a pattern
             liquid-spec run #{filename} -n /^case_b/    # regex form
-            liquid-spec run #{filename} -s basics       # one suite
             liquid-spec run #{filename} --list-suites   # what suites exist
             liquid-spec run #{filename} -l              # list specs without running
             liquid-spec run #{filename} --list-passed   # audit accidental passes
@@ -608,9 +614,10 @@ def self.ruby_adapter_section
             end
             ```
 
-            ### compile(ctx, source, options) → template
+            ### compile(ctx, source, options)
 
-            Parse the source string into your template representation. Called once per template.
+            Parse the source string and store your template representation in `ctx`.
+            Called once per template.
 
             ```ruby
             LiquidSpec.compile do |ctx, source, options|
@@ -619,21 +626,21 @@ def self.ruby_adapter_section
               #   :line_numbers - true/false
               #   :file_system - for include/render tags
               options[:error_mode] ||= :strict2
-              MyLiquid::Template.parse(source, environment: ctx[:environment])
+              ctx[:template] = MyLiquid::Template.parse(source, environment: ctx[:environment])
             end
             ```
 
-            ### render(ctx, template, assigns, options) → string
+            ### render(ctx, assigns, options) → string
 
-            Render a compiled template with variables. Called for each test.
+            Render the compiled template from `ctx` with variables. Called for each test.
 
             ```ruby
-            LiquidSpec.render do |ctx, template, assigns, options|
+            LiquidSpec.render do |ctx, assigns, options|
               # assigns: Hash of variables available as {{ var }}
               # options may include:
               #   :registers - internal state (file_system, etc.)
               #   :strict_errors - whether to raise or capture errors
-              template.render(assigns)
+              ctx[:template].render(assigns)
             end
             ```
           MARKDOWN
@@ -850,18 +857,18 @@ def self.json_rpc_section(filename)
           # for new implementations unless you need that compatibility.
           LiquidSpec.compile do |ctx, source, options|
             options[:error_mode] ||= :strict2
-            Liquid::Template.parse(source, **options)
+            ctx[:template] = Liquid::Template.parse(source, **options)
           end
 
           # Render errors are raised by default (strict_errors: true). Only specs
           # that opt into render_errors set strict_errors to false.
-          LiquidSpec.render do |ctx, template, assigns, options|
+          LiquidSpec.render do |ctx, assigns, options|
             context = Liquid::Context.build(
               static_environments: assigns,
               registers: Liquid::Registers.new(options[:registers] || {}),
               rethrow_errors: options[:strict_errors]
             )
-            template.render(context)
+            ctx[:template].render(context)
           end
         RUBY
 
@@ -898,8 +905,10 @@ def self.run(args)
             generate_adapter("liquid_adapter.rb", :basic)
             generate_adapter("liquid_adapter_jsonrpc.rb", :json_rpc)
 
-            # Create AGENTS.md once (covers both adapters)
-            create_agents_md("liquid_adapter.rb", json_rpc: false)
+            # Create AGENTS.md once. Lead with the cross-language adapter because
+            # agents building in TypeScript/Rust/Go/Python need the protocol guide;
+            # include the direct Ruby adapter section as well.
+            create_agents_md("liquid_adapter_jsonrpc.rb", json_rpc: true, both: true)
 
             puts ""
             puts "Next steps:"
@@ -938,12 +947,12 @@ def self.generate_adapter(filename, template_type)
           puts "Created #{filename} (executable)"
         end
 
-        def self.create_agents_md(filename, json_rpc:)
+        def self.create_agents_md(filename, json_rpc:, both: false)
           agents_filename = "AGENTS.md"
           if File.exist?(agents_filename)
             puts "AGENTS.md already exists, skipping"
           else
-            agents_md = agents_md_content(filename, json_rpc: json_rpc)
+            agents_md = agents_md_content(filename, json_rpc: json_rpc, both: both)
             File.write(agents_filename, agents_md)
             puts "Created AGENTS.md"
           end