latticerb 0.1.0

data/lib/lattice/resources/generic/lattice-workflow/references/modeling-rules.md

@@ -0,0 +1,52 @@
+# Modeling Rules
+
+Use this file when you are extracting a schema from code or prose and need tighter guardrails than the main skill body provides.
+
+## Parameter Selection
+
+- Scope one schema to one coherent behavior or rendering surface.
+  Good scopes: one feature, one service behavior, one workflow, one endpoint family, one state-machine slice, one component's variant space, one template family.
+  Bad default scope: the whole app.
+- Model the decisions that change behavior, not every field in a payload.
+- Prefer parameters that are visible in tests, UI branches, rendering branches, validation logic, template variants, component props, or feature flags.
+- Split large raw domains into behavioral partitions.
+  Good: `pay_range = present|absent`
+  Bad: every exact salary string
+- Avoid separate parameters for values that are already implied by another parameter unless the implication is partial and needs a constraint.
+
+## Value Selection
+
+- Values should be mutually exclusive and collectively useful for testing.
+- Keep domains small and meaningful. Most parameters should land in the 2-5 value range.
+- Normalize booleans as `true` and `false`.
+- For optional subordinate parameters, let `conditional` introduce `N/A`. Do not hand-add `N/A` unless the schema genuinely needs it as a first-class value.
+
+## Constraint Choice
+
+- `invalid_pair`: two assignments cannot coexist
+- `bidirectional`: one-to-one pairing; if A then B and if B then A
+- `forward_dep`: A requires B, but B may appear elsewhere
+- `conditional`: a child parameter only applies for some parent values
+- `forced`: this assignment set must appear in at least one generated row
+- `higher_order`: the invalid rule only appears when two or more antecedents are true
+
+Choose the smallest expressive type. If a rule can be represented as `invalid_pair`, do not use `higher_order`.
+
+Do not strip true constraints to get a smaller or easier unconstrained run. Do not generate nonsensical rows and mark them invalid downstream. Lattice's coverage accounting should run over valid interactions, so impossible combinations belong in the schema as `invalid_pair`, `forward_dep`, `bidirectional`, `conditional`, or `higher_order` constraints.
+
+## Extraction Process
+
+1. Choose the behavior or rendering surface you are modeling.
+2. Start from branches, validations, and business rules inside that scope.
+3. Convert prose like "only when", "must", "cannot", and "except" into candidate constraints.
+4. Remove cosmetic parameters that do not affect behavior.
+5. Check whether a missing value is really a separate partition or just noise.
+6. Validate the schema.
+7. Only after validation, generate scenarios.
+
+## Interpretation
+
+- Plan mode: each row becomes a review scenario or a missing decision in the plan.
+- Test mode: each row becomes a candidate setup matrix. Source the expected behavior from intent — user request, spec, PRD, or ticket — not from the code under test. If you cannot determine intent for a row, stop and surface the ambiguity to the user. Do not encode the current behavior and label it `bug_signal:` to hedge: characterization tests pass for the wrong reasons and hide the asymmetries Lattice is designed to expose. Example: if a mailbox accepts a spoofed `From:` header today, the assertion is still "rejects spoofed sender" — let the test fail and fix the code, do not invert the assertion to match the bug.
+- Variant mode: each row becomes a rendered variant, fixture, screenshot, visual diff input, contact-sheet item, or review checklist item.
+- Generated rows are not test names by themselves. The agent still needs to map them to application-specific assertions.

data/lib/lattice/resources/generic/lattice-workflow/references/worked-examples.md

@@ -0,0 +1,59 @@
+# Worked Examples
+
+These examples live in the repo-level `examples/` directory.
+
+## `examples/plan-mode-saved-search`
+
+Use when the agent starts from a feature discussion or PRD and needs a review checklist.
+
+- Input: `feature.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`
+
+## `examples/test-mode-checkout`
+
+Use when the agent starts from code and an existing test surface and needs missing cases.
+
+- Input: `code-notes.md`
+- Schema transport: `model.json`
+- Output: `scenarios.json`
+
+## `examples/three-way-notifications`
+
+Use when pairwise is not enough and the user explicitly wants 3-way coverage.
+
+- Input: `brief.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`
+
+## `examples/component-variant-matrix`
+
+Use when the agent starts from a visual component, rendering surface, template, or design-system story and needs compact review variants instead of every possible combination.
+
+- Input: `brief.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`
+
+## `examples/lattice-self-test`
+
+Use when you want a meta example of the harness extracting a schema for Lattice's own CLI surface and then using generated rows to drive CLI smoke tests.
+
+- Input: `brief.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`
+
+## `examples/agent-bootstrap-matrix`
+
+Use when you want a meta example of Lattice testing its own agent skill bootstrap behavior across harness detection, force/skip directives, target modes, and output formats.
+
+- Input: `brief.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`
+
+## `examples/schema-guidance-matrix`
+
+Use when you want a meta example of Lattice testing its own schema-discoverability guidance across help text, agent instructions, installed skill files, and validation errors.
+
+- Input: `brief.md`
+- Schema transport: `model.yaml`
+- Output: `scenarios.json`

data/lib/lattice/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Lattice
+  VERSION = "0.1.0"
+end

data/lib/lattice.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "lattice/version"
+require_relative "lattice/model"
+require_relative "lattice/parser"
+require_relative "lattice/constraints"
+require_relative "lattice/ipog"
+require_relative "lattice/formatters"
+
+module Lattice
+  # A generation run: the parsed model plus its covering array, with
+  # ready-to-use named scenarios for tests, fixtures, and factories.
+  class Run
+    attr_reader :model, :result, :seed
+
+    def initialize(model:, result:, seed:)
+      @model = model
+      @result = result
+      @seed = seed
+    end
+
+    # Scenarios as an array of `{ "parameter" => "value" }` hashes.
+    def scenarios
+      @scenarios ||= Formatters.named_rows(model, result).each(&:freeze).freeze
+    end
+
+    def each_scenario(&) = scenarios.each(&)
+
+    def coverage_curve = result.coverage_curve
+
+    def to_table = Formatters.render_output(model, result, output_format: "table", seed:)
+    def to_json_output = Formatters.render_output(model, result, output_format: "json", seed:)
+    def to_csv = Formatters.render_output(model, result, output_format: "csv", seed:)
+    def to_summary = Formatters.render_output(model, result, output_format: "summary", seed:)
+  end
+
+  class << self
+    # Parse a schema from a Hash (already-decoded JSON/YAML), a JSON or YAML
+    # String, or a file path via `file:`.
+    def parse_model(source = nil, file: nil, strength: nil)
+      if file
+        Parser.load_model(file, strength_override: strength)
+      elsif source.is_a?(Hash)
+        Parser.parse_model_data(source, strength_override: strength)
+      elsif source.is_a?(String)
+        data = Parser.deserialize_model(source, "string", nil)
+        Parser.parse_model_data(data, strength_override: strength)
+      elsif source.is_a?(Model)
+        strength ? source.with(strength:) : source
+      else
+        raise ArgumentError, "Pass a schema Hash, a JSON/YAML String, a Lattice::Model, or file: <path>."
+      end
+    end
+
+    # Generate a covering array for a schema and return a Run.
+    #
+    #   run = Lattice.generate(file: "spec/fixtures/checkout.yaml")
+    #   run.scenarios.each { |row| ... }
+    def generate(source = nil, file: nil, strength: nil, seed: 42, pool_size: 50,
+                 max_rows: nil, stop_after_coverage: nil, progress: nil)
+      model = parse_model(source, file:, strength:)
+      result = IPOG.generate_covering_array(
+        model,
+        strength: model.strength,
+        seed:,
+        pool_size:,
+        progress:,
+        max_rows:,
+        stop_after_coverage:
+      )
+      Run.new(model:, result:, seed:)
+    end
+
+    # Convenience: generate and return just the named scenario hashes.
+    def scenarios(...) = generate(...).scenarios
+
+    # Parse and constraint-check a schema, raising Lattice::ValidationError or
+    # Lattice::ConstraintError when invalid. Returns the Model.
+    def validate!(source = nil, file: nil, strength: nil)
+      model = parse_model(source, file:, strength:)
+      engine = ConstraintEngine.new(model)
+      raise ValidationError, ["Model has no valid complete assignments."] unless engine.can_complete?({})
+
+      model
+    end
+  end
+end

data/lib/latticerb.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Gem entry point: Bundler auto-requires `gem "latticerb"` as "latticerb".
+require_relative "lattice"

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: latticerb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tyler Klose
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Lattice generates deterministic pairwise/t-way covering arrays from a
+  constrained schema of parameters and values. Use it as a library in test suites
+  (RSpec, Minitest, Rails fixtures) or via the bundled `lattice` CLI. Output is row-for-row
+  identical to the Python lattice-cli package for the same schema and seed.
+email:
+- tylerklose@gmail.com
+executables:
+- lattice
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/lattice
+- lib/lattice.rb
+- lib/lattice/agent.rb
+- lib/lattice/cli.rb
+- lib/lattice/constraints.rb
+- lib/lattice/formatters.rb
+- lib/lattice/ipog.rb
+- lib/lattice/mersenne_twister.rb
+- lib/lattice/model.rb
+- lib/lattice/parser.rb
+- lib/lattice/resources/claude/lattice-workflow/SKILL.md
+- lib/lattice/resources/claude/lattice-workflow/references/modeling-rules.md
+- lib/lattice/resources/claude/lattice-workflow/references/worked-examples.md
+- lib/lattice/resources/codex/lattice-workflow/SKILL.md
+- lib/lattice/resources/codex/lattice-workflow/agents/openai.yaml
+- lib/lattice/resources/codex/lattice-workflow/references/modeling-rules.md
+- lib/lattice/resources/codex/lattice-workflow/references/worked-examples.md
+- lib/lattice/resources/generic/lattice-workflow/SKILL.md
+- lib/lattice/resources/generic/lattice-workflow/references/modeling-rules.md
+- lib/lattice/resources/generic/lattice-workflow/references/worked-examples.md
+- lib/lattice/version.rb
+- lib/latticerb.rb
+homepage: https://github.com/tylerklose/lattice-ruby
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/tylerklose/lattice-ruby
+  source_code_uri: https://github.com/tylerklose/lattice-ruby
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Deterministic combinatorial coverage for agent workflows and constrained
+  variant surfaces.
+test_files: []