latticerb 0.4.0-aarch64-linux

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. checksums.yaml +7 -0
  2. data/LICENSE +176 -0
  3. data/README.md +163 -0
  4. data/exe/lattice +7 -0
  5. data/ext/lattice_native/rustfmt.toml +1 -0
  6. data/lib/lattice/3.2/lattice_native.so +0 -0
  7. data/lib/lattice/3.3/lattice_native.so +0 -0
  8. data/lib/lattice/3.4/lattice_native.so +0 -0
  9. data/lib/lattice/4.0/lattice_native.so +0 -0
  10. data/lib/lattice/agent.rb +204 -0
  11. data/lib/lattice/cli.rb +469 -0
  12. data/lib/lattice/constraints.rb +265 -0
  13. data/lib/lattice/formatters.rb +193 -0
  14. data/lib/lattice/ipog.rb +103 -0
  15. data/lib/lattice/model.rb +83 -0
  16. data/lib/lattice/native.rb +10 -0
  17. data/lib/lattice/parser.rb +427 -0
  18. data/lib/lattice/resources/claude/lattice-workflow/SKILL.md +144 -0
  19. data/lib/lattice/resources/claude/lattice-workflow/references/modeling-rules.md +52 -0
  20. data/lib/lattice/resources/claude/lattice-workflow/references/worked-examples.md +59 -0
  21. data/lib/lattice/resources/codex/lattice-workflow/SKILL.md +144 -0
  22. data/lib/lattice/resources/codex/lattice-workflow/agents/openai.yaml +7 -0
  23. data/lib/lattice/resources/codex/lattice-workflow/references/modeling-rules.md +52 -0
  24. data/lib/lattice/resources/codex/lattice-workflow/references/worked-examples.md +59 -0
  25. data/lib/lattice/resources/generic/lattice-workflow/SKILL.md +152 -0
  26. data/lib/lattice/resources/generic/lattice-workflow/references/modeling-rules.md +52 -0
  27. data/lib/lattice/resources/generic/lattice-workflow/references/worked-examples.md +59 -0
  28. data/lib/lattice/schema_text.rb +153 -0
  29. data/lib/lattice/version.rb +5 -0
  30. data/lib/lattice.rb +88 -0
  31. data/lib/latticerb.rb +4 -0
  32. metadata +99 -0
@@ -0,0 +1,427 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "model"
4
+ require_relative "schema_text"
5
+
6
+ module Lattice
7
+ class ModelIOError < StandardError; end
8
+
9
+ class ValidationError < StandardError
10
+ attr_reader :errors
11
+
12
+ def initialize(errors)
13
+ @errors = errors
14
+ super(errors.join("\n"))
15
+ end
16
+ end
17
+
18
+ module Parser
19
+ extend self
20
+
21
+ # Each constraint type and the keys written beside `type`.
22
+ CONSTRAINT_FIELDS = {
23
+ "invalid_pair" => "`if` and `then_not`",
24
+ "bidirectional" => "`pair`",
25
+ "forward_dep" => "`source` and `target`",
26
+ "conditional" => "`parameter`, `values`, `parent` and `applies_when`",
27
+ "forced" => "`assignments`",
28
+ "higher_order" => "`if_all` and `then_not`"
29
+ }.freeze
30
+ CONSTRAINT_TYPE_LIST = CONSTRAINT_FIELDS.keys.map { |name| "`#{name}`" }.join(", ").freeze
31
+
32
+ def load_model(path, strength_override: nil)
33
+ text, source_name, extension = read_model_input(path)
34
+ data = deserialize_model(text, source_name, extension)
35
+ parse_model_data(data, strength_override:)
36
+ end
37
+
38
+ def parse_model_data(data, strength_override: nil)
39
+ raise ValidationError, ["Model root must be a JSON/YAML object."] unless data.is_a?(Hash)
40
+
41
+ errors = []
42
+ parameters = parse_parameters(data["parameters"], errors)
43
+ raw_constraints = data.fetch("constraints", []) || []
44
+ unless raw_constraints.is_a?(Array)
45
+ errors << "`constraints` must be a list."
46
+ raw_constraints = []
47
+ end
48
+
49
+ apply_conditional_parameters(parameters, raw_constraints, errors)
50
+ constraints = parse_constraints(raw_constraints, parameters, errors)
51
+ strength = parse_strength(strength_override.nil? ? data["strength"] : strength_override, parameters.length, errors)
52
+ model_name = Lattice.normalize_scalar(data.fetch("model_name", "unnamed_model"))
53
+
54
+ raise ValidationError, errors unless errors.empty?
55
+
56
+ Model.new(
57
+ model_name:,
58
+ parameters: parameters.values,
59
+ constraints:,
60
+ strength:
61
+ )
62
+ end
63
+
64
+ def read_model_input(path)
65
+ if path.nil? || path == "-"
66
+ text = $stdin.read
67
+ raise ModelIOError, "No model content found on stdin." if text.strip.empty?
68
+
69
+ return [text, "stdin", nil]
70
+ end
71
+
72
+ begin
73
+ text = File.read(path, encoding: "UTF-8")
74
+ rescue SystemCallError, IOError => e
75
+ raise ModelIOError, "Unable to read model file `#{path}`: #{e.message}"
76
+ end
77
+ [text, path, File.extname(path).downcase]
78
+ end
79
+
80
+ def deserialize_model(text, source_name, extension)
81
+ loaders =
82
+ case extension
83
+ when ".json" then [:json]
84
+ when ".yaml", ".yml" then [:yaml]
85
+ else [:json, :yaml]
86
+ end
87
+
88
+ errors = []
89
+ loaders.each do |loader|
90
+ return loader == :json ? SchemaText.load_json(text) : SchemaText.load_yaml(text)
91
+ rescue StandardError => e
92
+ errors << e.message
93
+ end
94
+
95
+ raise ModelIOError, "Unable to parse model from `#{source_name}`: #{errors.join('; ')}"
96
+ end
97
+
98
+ def parse_parameters(raw_parameters, errors)
99
+ parameters = {}
100
+ if raw_parameters.nil?
101
+ errors << "`parameters` is required."
102
+ return parameters
103
+ end
104
+
105
+ case raw_parameters
106
+ when Hash
107
+ raw_parameters.each { |name, spec| add_parameter(parameters, name, spec, errors) }
108
+ when Array
109
+ raw_parameters.each_with_index do |raw_parameter, index|
110
+ unless raw_parameter.is_a?(Hash)
111
+ errors << "`parameters[#{index}]` must be an object."
112
+ next
113
+ end
114
+ name = raw_parameter["name"]
115
+ if name.nil?
116
+ errors << "`parameters[#{index}]` is missing `name`."
117
+ next
118
+ end
119
+ add_parameter(parameters, name, raw_parameter, errors)
120
+ end
121
+ else
122
+ errors << "`parameters` must be a mapping or list."
123
+ end
124
+ parameters
125
+ end
126
+
127
+ def add_parameter(parameters, name, spec, errors)
128
+ normalized_name = Lattice.normalize_scalar(name)
129
+ if parameters.key?(normalized_name)
130
+ errors << "Duplicate parameter `#{normalized_name}`."
131
+ return
132
+ end
133
+
134
+ if spec.is_a?(Hash)
135
+ values = spec["values"]
136
+ weights = spec["weights"]
137
+ else
138
+ values = spec
139
+ weights = nil
140
+ end
141
+
142
+ parsed_values = parse_values(values, "parameter `#{normalized_name}`", errors)
143
+ parsed_weights = parse_weights(weights, parsed_values, normalized_name, errors)
144
+ return if parsed_values.empty?
145
+
146
+ parameters[normalized_name] = Parameter.new(
147
+ name: normalized_name,
148
+ values: parsed_values,
149
+ weights: parsed_weights
150
+ )
151
+ end
152
+
153
+ def apply_conditional_parameters(parameters, raw_constraints, errors)
154
+ raw_constraints.each_with_index do |raw_constraint, index|
155
+ next unless raw_constraint.is_a?(Hash)
156
+ next unless raw_constraint["type"] == "conditional"
157
+
158
+ parameter_name = Lattice.normalize_scalar(raw_constraint["parameter"])
159
+ values = parse_values(raw_constraint["values"], "`constraints[#{index}]` conditional values", errors)
160
+ next if values.empty?
161
+
162
+ conditional_values = values
163
+ conditional_values = conditional_values + [NA_VALUE] unless conditional_values.include?(NA_VALUE)
164
+
165
+ existing = parameters[parameter_name]
166
+ if existing.nil?
167
+ parameters[parameter_name] = Parameter.new(name: parameter_name, values: conditional_values)
168
+ next
169
+ end
170
+
171
+ next if Set.new(existing.values) == Set.new(conditional_values)
172
+
173
+ errors << (
174
+ "Conditional parameter `#{parameter_name}` conflicts with an existing parameter definition. " \
175
+ "Use `conditional` only to define a child parameter that applies under parent values. " \
176
+ "For exclusions or requirements between existing parameters, use `invalid_pair`, " \
177
+ "`higher_order`, `forward_dep`, or `bidirectional`; run `lattice agent instructions` " \
178
+ "for the full schema reference."
179
+ )
180
+ end
181
+ end
182
+
183
+ def parse_constraints(raw_constraints, parameters, errors)
184
+ parsed = []
185
+ raw_constraints.each_with_index do |raw_constraint, index|
186
+ unless raw_constraint.is_a?(Hash)
187
+ errors << "`constraints[#{index}]` must be an object."
188
+ next
189
+ end
190
+
191
+ constraint_type = raw_constraint["type"]
192
+ if constraint_type.nil?
193
+ errors << missing_type_message(index, raw_constraint)
194
+ next
195
+ end
196
+ unless constraint_type.is_a?(String)
197
+ errors << "`constraints[#{index}].type` must be a string, one of: #{CONSTRAINT_TYPE_LIST}."
198
+ next
199
+ end
200
+
201
+ case constraint_type
202
+ when "invalid_pair"
203
+ if_assignment = parse_assignment(raw_constraint["if"], parameters, "`constraints[#{index}].if`", errors)
204
+ then_not = parse_assignment(raw_constraint["then_not"], parameters, "`constraints[#{index}].then_not`", errors)
205
+ parsed << InvalidPairConstraint.new(if_assignment:, then_not:) if if_assignment && then_not
206
+ when "bidirectional"
207
+ pair = raw_constraint["pair"]
208
+ unless pair.is_a?(Array) && pair.length == 2
209
+ errors << "`constraints[#{index}].pair` must contain exactly two assignments."
210
+ next
211
+ end
212
+ left = parse_assignment(pair[0], parameters, "`constraints[#{index}].pair[0]`", errors)
213
+ right = parse_assignment(pair[1], parameters, "`constraints[#{index}].pair[1]`", errors)
214
+ parsed << BidirectionalConstraint.new(pair: [left, right]) if left && right
215
+ when "forward_dep"
216
+ source = parse_assignment(raw_constraint["source"], parameters, "`constraints[#{index}].source`", errors)
217
+ target = parse_assignment(raw_constraint["target"], parameters, "`constraints[#{index}].target`", errors)
218
+ parsed << ForwardDependencyConstraint.new(source:, target:) if source && target
219
+ when "conditional"
220
+ constraint = parse_conditional_constraint(raw_constraint, index, parameters, errors)
221
+ parsed << constraint if constraint
222
+ when "forced"
223
+ constraint = parse_forced_constraint(raw_constraint, index, parameters, errors)
224
+ parsed << constraint if constraint
225
+ when "higher_order"
226
+ constraint = parse_higher_order_constraint(raw_constraint, index, parameters, errors)
227
+ parsed << constraint if constraint
228
+ else
229
+ errors << "`constraints[#{index}]` has unknown type `#{constraint_type}`. Use one of: #{CONSTRAINT_TYPE_LIST}."
230
+ end
231
+ end
232
+ parsed
233
+ end
234
+
235
+ # Explains a constraint without `type`. A type name used as a key, as in
236
+ # `- invalid_pair: {...}`, gets the correct form spelled out.
237
+ def missing_type_message(index, raw_constraint)
238
+ shorthand = raw_constraint.keys.find { |key| CONSTRAINT_FIELDS.key?(key) }
239
+ return "`constraints[#{index}]` is missing `type`. Use one of: #{CONSTRAINT_TYPE_LIST}." if shorthand.nil?
240
+
241
+ "`constraints[#{index}]` is missing `type`. Write `type: #{shorthand}` as its own key, " \
242
+ "with #{CONSTRAINT_FIELDS.fetch(shorthand)} beside it. " \
243
+ "Run `lattice agent instructions` for an example of each type."
244
+ end
245
+
246
+ def parse_conditional_constraint(raw_constraint, index, parameters, errors)
247
+ parent = Lattice.normalize_scalar(raw_constraint["parent"])
248
+ parameter_name = Lattice.normalize_scalar(raw_constraint["parameter"])
249
+ values = parse_values(raw_constraint["values"], "`constraints[#{index}].values`", errors)
250
+ applies_when = parse_values(raw_constraint["applies_when"], "`constraints[#{index}].applies_when`", errors)
251
+
252
+ unless parameters.key?(parent)
253
+ errors << "`constraints[#{index}]` references unknown parent parameter `#{parent}`."
254
+ return nil
255
+ end
256
+ unless parameters.key?(parameter_name)
257
+ errors << (
258
+ "`constraints[#{index}]` references unknown conditional parameter `#{parameter_name}`. " \
259
+ "`conditional` must define a child parameter with `values` and a parent gate. " \
260
+ "For exclusions or requirements between existing parameters, use `invalid_pair`, " \
261
+ "`higher_order`, `forward_dep`, or `bidirectional`; run `lattice agent instructions` " \
262
+ "for the full schema reference."
263
+ )
264
+ return nil
265
+ end
266
+
267
+ parent_parameter = parameters[parent]
268
+ missing = applies_when.reject { |value| parent_parameter.value_set.include?(value) }
269
+ unless missing.empty?
270
+ errors << "`constraints[#{index}]` applies_when contains unknown values for `#{parent}`: #{missing.join(', ')}."
271
+ return nil
272
+ end
273
+
274
+ return nil if values.empty?
275
+
276
+ ConditionalConstraint.new(
277
+ parameter: parameter_name,
278
+ values: values.reject { |value| value == NA_VALUE },
279
+ parent:,
280
+ applies_when:
281
+ )
282
+ end
283
+
284
+ def parse_forced_constraint(raw_constraint, index, parameters, errors)
285
+ assignments = raw_constraint["assignments"]
286
+ unless assignments.is_a?(Array) && !assignments.empty?
287
+ errors << "`constraints[#{index}].assignments` must contain at least one assignment."
288
+ return nil
289
+ end
290
+
291
+ seen_parameters = Set.new
292
+ parsed_assignments = []
293
+ assignments.each_with_index do |raw_assignment, assignment_index|
294
+ assignment = parse_assignment(
295
+ raw_assignment,
296
+ parameters,
297
+ "`constraints[#{index}].assignments[#{assignment_index}]`",
298
+ errors
299
+ )
300
+ next if assignment.nil?
301
+
302
+ if seen_parameters.include?(assignment.parameter)
303
+ errors << "`constraints[#{index}]` repeats parameter `#{assignment.parameter}` inside a forced interaction."
304
+ next
305
+ end
306
+ seen_parameters.add(assignment.parameter)
307
+ parsed_assignments << assignment
308
+ end
309
+ return nil if parsed_assignments.empty?
310
+
311
+ ForcedConstraint.new(assignments: parsed_assignments)
312
+ end
313
+
314
+ def parse_higher_order_constraint(raw_constraint, index, parameters, errors)
315
+ if_all = raw_constraint["if_all"]
316
+ unless if_all.is_a?(Array) && if_all.length >= 2
317
+ errors << "`constraints[#{index}].if_all` must contain at least two assignments."
318
+ return nil
319
+ end
320
+
321
+ parsed_if_all = if_all.each_with_index.filter_map do |raw_assignment, assignment_index|
322
+ parse_assignment(raw_assignment, parameters, "`constraints[#{index}].if_all[#{assignment_index}]`", errors)
323
+ end
324
+ parsed_then_not = parse_assignment(raw_constraint["then_not"], parameters, "`constraints[#{index}].then_not`", errors)
325
+ return nil unless !parsed_if_all.empty? && parsed_then_not
326
+
327
+ HigherOrderConstraint.new(if_all: parsed_if_all, then_not: parsed_then_not)
328
+ end
329
+
330
+ def parse_assignment(raw_assignment, parameters, field_name, errors)
331
+ unless raw_assignment.is_a?(Hash)
332
+ errors << "#{field_name} must be an object."
333
+ return nil
334
+ end
335
+
336
+ parameter_name = Lattice.normalize_scalar(raw_assignment["parameter"])
337
+ value = Lattice.normalize_scalar(raw_assignment["value"])
338
+
339
+ parameter = parameters[parameter_name]
340
+ if parameter.nil?
341
+ errors << "#{field_name} references unknown parameter `#{parameter_name}`."
342
+ return nil
343
+ end
344
+
345
+ unless parameter.value_set.include?(value)
346
+ errors << "#{field_name} references unknown value `#{value}` for parameter `#{parameter_name}`."
347
+ return nil
348
+ end
349
+
350
+ Assignment.new(parameter: parameter_name, value:)
351
+ end
352
+
353
+ def parse_values(raw_values, field_name, errors)
354
+ unless raw_values.is_a?(Array) && !raw_values.empty?
355
+ errors << "#{field_name} must be a non-empty list."
356
+ return []
357
+ end
358
+
359
+ values = raw_values.map { |value| Lattice.normalize_scalar(value) }
360
+ if values.uniq.length != values.length
361
+ errors << "#{field_name} contains duplicate values."
362
+ return []
363
+ end
364
+ values
365
+ end
366
+
367
+ def parse_weights(raw_weights, values, parameter_name, errors)
368
+ return nil if raw_weights.nil?
369
+
370
+ unless raw_weights.is_a?(Array)
371
+ errors << "`weights` for parameter `#{parameter_name}` must be a list."
372
+ return nil
373
+ end
374
+ if raw_weights.length != values.length
375
+ errors << "`weights` for parameter `#{parameter_name}` must have the same length as its values."
376
+ return nil
377
+ end
378
+
379
+ parsed = []
380
+ raw_weights.each do |raw_weight|
381
+ weight = parse_number(raw_weight)
382
+ if weight.nil?
383
+ errors << "`weights` for parameter `#{parameter_name}` must be numeric."
384
+ return nil
385
+ end
386
+ unless weight.positive?
387
+ errors << "`weights` for parameter `#{parameter_name}` must be greater than zero."
388
+ return nil
389
+ end
390
+ parsed << weight
391
+ end
392
+ parsed
393
+ end
394
+
395
+ DECIMAL_TEXT = /\A[-+]?[0-9]+(\.[0-9]+)?([eE][-+]?[0-9]+)?\z/
396
+ INTEGER_TEXT = /\A[-+]?[0-9]+\z/
397
+
398
+ # A finite number, from a Ruby number or decimal text such as "0.7" or
399
+ # "1e-3" (schema files keep numbers as text). Booleans are not numbers.
400
+ def parse_number(raw)
401
+ number =
402
+ case raw
403
+ when Integer, Float then raw.to_f
404
+ when String then DECIMAL_TEXT.match?(raw) ? Float(raw) : nil
405
+ end
406
+ number&.finite? ? number : nil
407
+ end
408
+
409
+ def parse_strength(raw_strength, parameter_count, errors)
410
+ strength =
411
+ case raw_strength
412
+ when nil then 2
413
+ when Integer then raw_strength
414
+ when Float then raw_strength.finite? ? raw_strength.to_i : nil
415
+ when String then INTEGER_TEXT.match?(raw_strength) ? Integer(raw_strength, 10) : nil
416
+ end
417
+ if strength.nil?
418
+ errors << "`strength` must be an integer."
419
+ return 2
420
+ end
421
+
422
+ errors << "`strength` must be at least 1." if strength < 1
423
+ errors << "`strength` cannot exceed the number of parameters." if parameter_count.positive? && strength > parameter_count
424
+ strength
425
+ end
426
+ end
427
+ end
@@ -0,0 +1,144 @@
1
+ ---
2
+ name: lattice-workflow
3
+ description: Use when planning or testing behavior or variant surfaces with interacting states, roles, permissions, feature flags, modes, providers, optional fields, component props, rendering branches, template variants, config matrices, lifecycle states, combinatorial edge cases, pairwise coverage, or t-way coverage. Extract a Lattice schema, run the local Lattice CLI, and use generated rows to strengthen plans, tests, fixtures, rendered variants, or review matrices.
4
+ ---
5
+
6
+ # Lattice Workflow
7
+
8
+ Use this skill to keep Claude on extraction and interpretation while Lattice handles the combinatorics.
9
+
10
+ ## When To Use It
11
+
12
+ - derive a combinatorial model from a feature or PRD
13
+ - derive a test matrix from existing code
14
+ - derive a variant matrix from a component, partial, template, design-system story, or config surface
15
+ - convert edge cases into explicit parameter/value constraints
16
+ - generate pairwise or 3-way scenarios without hand-enumerating combinations
17
+ - render a compact visual review matrix instead of every possible variant
18
+ - review a plan involving roles, permissions, modes, providers, feature flags, optional fields, component props, rendering branches, template variants, config matrices, or lifecycle states
19
+ - find coverage gaps where bugs hide in interactions rather than single branches
20
+
21
+ ## When NOT To Use It
22
+
23
+ - **Small enumerable spaces.** Fewer than ~10 total combinations — enumerate by hand.
24
+ - **Independent dimensions.** No interactions can surface a bug; each parameter affects behavior independently.
25
+ - **Non-deterministic systems.** The same input row won't produce repeatable output (e.g., testing LLM responses).
26
+
27
+ ## Minimal Example
28
+
29
+ A schema (YAML on stdin):
30
+
31
+ ```yaml
32
+ model_name: checkout
33
+ parameters:
34
+ user: [signed_in, guest]
35
+ payment: [card, apple_pay, paypal]
36
+ cart: [empty, single, multi]
37
+ constraints:
38
+ - type: invalid_pair
39
+ if: { parameter: payment, value: apple_pay }
40
+ then_not: { parameter: cart, value: empty }
41
+ ```
42
+
43
+ One generated row (JSON):
44
+
45
+ ```json
46
+ {"user": "guest", "payment": "card", "cart": "multi"}
47
+ ```
48
+
49
+ The schema is the contract. The generated rows are the source of truth. The schema file is optional transport.
50
+
51
+ ## Preflight
52
+
53
+ ```bash
54
+ command -v lattice >/dev/null 2>&1 && lattice --help >/dev/null
55
+ ```
56
+
57
+ If it fails, install the Ruby gem from RubyGems (or add `gem "latticerb"` to the project Gemfile):
58
+
59
+ ```bash
60
+ gem install latticerb
61
+ ```
62
+
63
+ The Python implementation (`pipx install lattice-cli` from PyPI) is interchangeable — both produce byte-identical output for the same schema and seed.
64
+
65
+ ## Workflow
66
+
67
+ 1. **Extract the schema.** Choose one coherent interaction surface — one feature, one workflow, one service behavior, one endpoint family, one component's variant space, one template family, or one config matrix. Parameters represent independent decisions or state partitions. Values are meaningful partitions, not every literal in the codebase.
68
+
69
+ 2. **Encode constraints.** Use the smallest constraint type that matches the rule (see [Constraint Selection](#constraint-selection) below). Encode true impossibilities — do not strip them and mark invalid rows downstream.
70
+
71
+ 3. **Validate.**
72
+
73
+ ```bash
74
+ cat schema.json | lattice validate
75
+ ```
76
+
77
+ 4. **Generate.** Default to pairwise unless explicitly asked for higher strength.
78
+
79
+ ```bash
80
+ cat schema.json | lattice generate
81
+ ```
82
+
83
+ 5. **Interpret the output.** Plan mode: rows become plan revisions, missing decisions, review scenarios. Test mode: rows become assertions (see [Test Mode Discipline](#test-mode-discipline) below). Variant mode: rows become fixtures, rendered variants, screenshots, visual-diff inputs.
84
+
85
+ ## Constraint Selection
86
+
87
+ | Rule shape | Use |
88
+ |---|---|
89
+ | Two assignments cannot coexist | `invalid_pair` |
90
+ | One-to-one pairing (if A then B and if B then A) | `bidirectional` |
91
+ | A requires B, but B may appear elsewhere | `forward_dep` |
92
+ | Child parameter only applies for some parent values | `conditional` |
93
+ | This assignment set must appear in at least one row | `forced` |
94
+ | Rule only breaks under three or more antecedents | `higher_order` |
95
+
96
+ Prefer the smallest constraint type that matches. Use `conditional` instead of hand-writing `N/A` values.
97
+
98
+ ## Test Mode Discipline
99
+
100
+ Source expected behavior from intent — the user's request, a spec, a PRD, a ticket, or explicit reasoning about what the system *should* do. **The code under test is evidence, not truth.** If intent is ambiguous for a row, stop and ask the user.
101
+
102
+ Do not silently encode current behavior and hedge with `bug_signal:`-style annotations. That produces characterization tests, which lock in the implementation (bugs included) instead of catching divergence from intent. The asymmetries Lattice is designed to expose disappear when the test suite mirrors the same mental model as the code.
103
+
104
+ ## Common Pitfalls
105
+
106
+ ❌ Strip constraints to make generation easier, then mark impossible rows invalid after the fact.
107
+ ✅ Encode the constraint in the schema, regenerate. Encoding constraints changes the coverage universe to valid interactions — that's the point.
108
+
109
+ ❌ Write tests that assert what the code currently does.
110
+ ✅ Write tests that assert what the spec, PRD, or user requested. If intent is ambiguous, ask before writing.
111
+
112
+ ❌ Separate parameters for two fields where one determines the other (e.g., `currency` and `currency_symbol`).
113
+ ✅ One parameter plus a constraint expressing the dependency.
114
+
115
+ ❌ Brittle, prose-y value names (`payment_with_apple_pay_using_new_token_flow`).
116
+ ✅ Compact partitions: `apple_pay`, `apple_pay_new_token`.
117
+
118
+ ❌ Manually add or remove rows after `lattice generate`.
119
+ ✅ If the generated set is wrong, fix the schema. Hand-editing rows breaks the coverage guarantee.
120
+
121
+ ## References
122
+
123
+ - [references/modeling-rules.md](references/modeling-rules.md) — extraction heuristics, parameter selection, value partitioning, constraint guidance
124
+ - [references/worked-examples.md](references/worked-examples.md) — concrete examples in this repo
125
+
126
+ ## Development Fallback
127
+
128
+ In a checkout of the Lattice source where the package is not installed:
129
+
130
+ ```bash
131
+ # Ruby checkout
132
+ cat schema.json | ruby -Ilib exe/lattice validate
133
+ cat schema.json | ruby -Ilib exe/lattice generate
134
+
135
+ # Python checkout
136
+ cat schema.json | PYTHONPATH=src python3 -m lattice validate
137
+ cat schema.json | PYTHONPATH=src python3 -m lattice generate
138
+ ```
139
+
140
+ To install or refresh this skill from the installed package:
141
+
142
+ ```bash
143
+ lattice agent install-claude-skill
144
+ ```
@@ -0,0 +1,52 @@
1
+ # Modeling Rules
2
+
3
+ Use this file when you are extracting a schema from code or prose and need tighter guardrails than the main skill body provides.
4
+
5
+ ## Parameter Selection
6
+
7
+ - Scope one schema to one coherent behavior or rendering surface.
8
+ Good scopes: one feature, one service behavior, one workflow, one endpoint family, one state-machine slice, one component's variant space, one template family.
9
+ Bad default scope: the whole app.
10
+ - Model the decisions that change behavior, not every field in a payload.
11
+ - Prefer parameters that are visible in tests, UI branches, rendering branches, validation logic, template variants, component props, or feature flags.
12
+ - Split large raw domains into behavioral partitions.
13
+ Good: `pay_range = present|absent`
14
+ Bad: every exact salary string
15
+ - Avoid separate parameters for values that are already implied by another parameter unless the implication is partial and needs a constraint.
16
+
17
+ ## Value Selection
18
+
19
+ - Values should be mutually exclusive and collectively useful for testing.
20
+ - Keep domains small and meaningful. Most parameters should land in the 2-5 value range.
21
+ - Normalize booleans as `true` and `false`.
22
+ - 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.
23
+
24
+ ## Constraint Choice
25
+
26
+ - `invalid_pair`: two assignments cannot coexist
27
+ - `bidirectional`: one-to-one pairing; if A then B and if B then A
28
+ - `forward_dep`: A requires B, but B may appear elsewhere
29
+ - `conditional`: a child parameter only applies for some parent values
30
+ - `forced`: this assignment set must appear in at least one generated row
31
+ - `higher_order`: the invalid rule only appears when two or more antecedents are true
32
+
33
+ Choose the smallest expressive type. If a rule can be represented as `invalid_pair`, do not use `higher_order`.
34
+
35
+ 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.
36
+
37
+ ## Extraction Process
38
+
39
+ 1. Choose the behavior or rendering surface you are modeling.
40
+ 2. Start from branches, validations, and business rules inside that scope.
41
+ 3. Convert prose like "only when", "must", "cannot", and "except" into candidate constraints.
42
+ 4. Remove cosmetic parameters that do not affect behavior.
43
+ 5. Check whether a missing value is really a separate partition or just noise.
44
+ 6. Validate the schema.
45
+ 7. Only after validation, generate scenarios.
46
+
47
+ ## Interpretation
48
+
49
+ - Plan mode: each row becomes a review scenario or a missing decision in the plan.
50
+ - 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.
51
+ - Variant mode: each row becomes a rendered variant, fixture, screenshot, visual diff input, contact-sheet item, or review checklist item.
52
+ - Generated rows are not test names by themselves. The agent still needs to map them to application-specific assertions.
@@ -0,0 +1,59 @@
1
+ # Worked Examples
2
+
3
+ These examples live in the repo-level `examples/` directory.
4
+
5
+ ## `examples/plan-mode-saved-search`
6
+
7
+ Use when the agent starts from a feature discussion or PRD and needs a review checklist.
8
+
9
+ - Input: `feature.md`
10
+ - Schema transport: `model.yaml`
11
+ - Output: `scenarios.json`
12
+
13
+ ## `examples/test-mode-checkout`
14
+
15
+ Use when the agent starts from code and an existing test surface and needs missing cases.
16
+
17
+ - Input: `code-notes.md`
18
+ - Schema transport: `model.json`
19
+ - Output: `scenarios.json`
20
+
21
+ ## `examples/three-way-notifications`
22
+
23
+ Use when pairwise is not enough and the user explicitly wants 3-way coverage.
24
+
25
+ - Input: `brief.md`
26
+ - Schema transport: `model.yaml`
27
+ - Output: `scenarios.json`
28
+
29
+ ## `examples/component-variant-matrix`
30
+
31
+ 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.
32
+
33
+ - Input: `brief.md`
34
+ - Schema transport: `model.yaml`
35
+ - Output: `scenarios.json`
36
+
37
+ ## `examples/lattice-self-test`
38
+
39
+ 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.
40
+
41
+ - Input: `brief.md`
42
+ - Schema transport: `model.yaml`
43
+ - Output: `scenarios.json`
44
+
45
+ ## `examples/agent-bootstrap-matrix`
46
+
47
+ 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.
48
+
49
+ - Input: `brief.md`
50
+ - Schema transport: `model.yaml`
51
+ - Output: `scenarios.json`
52
+
53
+ ## `examples/schema-guidance-matrix`
54
+
55
+ 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.
56
+
57
+ - Input: `brief.md`
58
+ - Schema transport: `model.yaml`
59
+ - Output: `scenarios.json`