lattice-cli 0.1.0__py3-none-any.whl

lattice/parser.py

@@ -0,0 +1,404 @@
+from __future__ import annotations
+
+import json
+import sys
+from collections import OrderedDict
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from lattice.model import (
+    Assignment,
+    BidirectionalConstraint,
+    ConditionalConstraint,
+    ForcedConstraint,
+    ForwardDependencyConstraint,
+    HigherOrderConstraint,
+    InvalidPairConstraint,
+    Model,
+    Parameter,
+    normalize_scalar,
+    NA_VALUE,
+)
+
+
+class ModelIOError(Exception):
+    """Raised when reading or deserializing a model fails."""
+
+
+class ValidationError(Exception):
+    """Raised when a model is structurally invalid."""
+
+    def __init__(self, errors: list[str]):
+        super().__init__("\n".join(errors))
+        self.errors = errors
+
+
+def load_model(path: str | None, strength_override: int | None = None) -> Model:
+    text, source_name, extension = _read_model_input(path)
+    data = _deserialize_model(text, source_name, extension)
+    return parse_model_data(data, strength_override=strength_override)
+
+
+def parse_model_data(data: Any, strength_override: int | None = None) -> Model:
+    if not isinstance(data, dict):
+        raise ValidationError(["Model root must be a JSON/YAML object."])
+
+    errors: list[str] = []
+    parameters = _parse_parameters(data.get("parameters"), errors)
+    raw_constraints = data.get("constraints", [])
+    if raw_constraints is None:
+        raw_constraints = []
+    if not isinstance(raw_constraints, list):
+        errors.append("`constraints` must be a list.")
+        raw_constraints = []
+
+    _apply_conditional_parameters(parameters, raw_constraints, errors)
+    constraints = _parse_constraints(raw_constraints, parameters, errors)
+    strength = _parse_strength(strength_override if strength_override is not None else data.get("strength"), len(parameters), errors)
+    model_name = normalize_scalar(data.get("model_name", "unnamed_model"))
+
+    if errors:
+        raise ValidationError(errors)
+
+    return Model(
+        model_name=model_name,
+        parameters=tuple(parameters.values()),
+        constraints=tuple(constraints),
+        strength=strength,
+    )
+
+
+def _read_model_input(path: str | None) -> tuple[str, str, str | None]:
+    if path in (None, "-"):
+        text = sys.stdin.read()
+        if not text.strip():
+            raise ModelIOError("No model content found on stdin.")
+        return text, "stdin", None
+
+    file_path = Path(path)
+    try:
+        text = file_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ModelIOError(f"Unable to read model file `{path}`: {exc}") from exc
+    return text, str(file_path), file_path.suffix.lower()
+
+
+def _deserialize_model(text: str, source_name: str, extension: str | None) -> Any:
+    loaders = []
+    if extension == ".json":
+        loaders = [json.loads]
+    elif extension in {".yaml", ".yml"}:
+        loaders = [yaml.safe_load]
+    else:
+        loaders = [json.loads, yaml.safe_load]
+
+    errors: list[str] = []
+    for loader in loaders:
+        try:
+            return loader(text)
+        except Exception as exc:  # pragma: no cover - exact parser error text varies
+            errors.append(str(exc))
+
+    joined = "; ".join(errors)
+    raise ModelIOError(f"Unable to parse model from `{source_name}`: {joined}")
+
+
+def _parse_parameters(raw_parameters: Any, errors: list[str]) -> "OrderedDict[str, Parameter]":
+    parameters: "OrderedDict[str, Parameter]" = OrderedDict()
+    if raw_parameters is None:
+        errors.append("`parameters` is required.")
+        return parameters
+
+    if isinstance(raw_parameters, dict):
+        items = raw_parameters.items()
+        for name, spec in items:
+            _add_parameter(parameters, name, spec, errors)
+        return parameters
+
+    if isinstance(raw_parameters, list):
+        for index, raw_parameter in enumerate(raw_parameters):
+            if not isinstance(raw_parameter, dict):
+                errors.append(f"`parameters[{index}]` must be an object.")
+                continue
+            name = raw_parameter.get("name")
+            if name is None:
+                errors.append(f"`parameters[{index}]` is missing `name`.")
+                continue
+            _add_parameter(parameters, name, raw_parameter, errors)
+        return parameters
+
+    errors.append("`parameters` must be a mapping or list.")
+    return parameters
+
+
+def _add_parameter(parameters: "OrderedDict[str, Parameter]", name: Any, spec: Any, errors: list[str]) -> None:
+    normalized_name = normalize_scalar(name)
+    if normalized_name in parameters:
+        errors.append(f"Duplicate parameter `{normalized_name}`.")
+        return
+
+    values: Any
+    weights: Any = None
+    if isinstance(spec, dict):
+        values = spec.get("values")
+        weights = spec.get("weights")
+    else:
+        values = spec
+
+    parsed_values = _parse_values(values, f"parameter `{normalized_name}`", errors)
+    parsed_weights = _parse_weights(weights, parsed_values, normalized_name, errors)
+    if not parsed_values:
+        return
+
+    parameters[normalized_name] = Parameter(
+        name=normalized_name,
+        values=parsed_values,
+        weights=parsed_weights,
+    )
+
+
+def _apply_conditional_parameters(parameters: "OrderedDict[str, Parameter]", raw_constraints: list[Any], errors: list[str]) -> None:
+    for index, raw_constraint in enumerate(raw_constraints):
+        if not isinstance(raw_constraint, dict):
+            continue
+        if raw_constraint.get("type") != "conditional":
+            continue
+
+        parameter_name = normalize_scalar(raw_constraint.get("parameter"))
+        values = _parse_values(raw_constraint.get("values"), f"`constraints[{index}]` conditional values", errors)
+        if not values:
+            continue
+
+        conditional_values = values
+        if NA_VALUE not in conditional_values:
+            conditional_values = conditional_values + (NA_VALUE,)
+
+        existing = parameters.get(parameter_name)
+        if existing is None:
+            parameters[parameter_name] = Parameter(name=parameter_name, values=conditional_values)
+            continue
+
+        expected = set(conditional_values)
+        actual = set(existing.values)
+        if actual != expected:
+            errors.append(
+                f"Conditional parameter `{parameter_name}` conflicts with an existing parameter definition. "
+                "Use `conditional` only to define a child parameter that applies under parent values. "
+                "For exclusions or requirements between existing parameters, use `invalid_pair`, "
+                "`higher_order`, `forward_dep`, or `bidirectional`; run `lattice agent instructions` "
+                "for the full schema reference."
+            )
+
+
+def _parse_constraints(
+    raw_constraints: list[Any],
+    parameters: "OrderedDict[str, Parameter]",
+    errors: list[str],
+) -> list[Any]:
+    parsed: list[Any] = []
+    for index, raw_constraint in enumerate(raw_constraints):
+        if not isinstance(raw_constraint, dict):
+            errors.append(f"`constraints[{index}]` must be an object.")
+            continue
+
+        constraint_type = raw_constraint.get("type")
+        if constraint_type == "invalid_pair":
+            if_assignment = _parse_assignment(raw_constraint.get("if"), parameters, f"`constraints[{index}].if`", errors)
+            then_not = _parse_assignment(raw_constraint.get("then_not"), parameters, f"`constraints[{index}].then_not`", errors)
+            if if_assignment and then_not:
+                parsed.append(InvalidPairConstraint(if_assignment=if_assignment, then_not=then_not))
+            continue
+
+        if constraint_type == "bidirectional":
+            pair = raw_constraint.get("pair")
+            if not isinstance(pair, list) or len(pair) != 2:
+                errors.append(f"`constraints[{index}].pair` must contain exactly two assignments.")
+                continue
+            left = _parse_assignment(pair[0], parameters, f"`constraints[{index}].pair[0]`", errors)
+            right = _parse_assignment(pair[1], parameters, f"`constraints[{index}].pair[1]`", errors)
+            if left and right:
+                parsed.append(BidirectionalConstraint(pair=(left, right)))
+            continue
+
+        if constraint_type == "forward_dep":
+            source = _parse_assignment(raw_constraint.get("source"), parameters, f"`constraints[{index}].source`", errors)
+            target = _parse_assignment(raw_constraint.get("target"), parameters, f"`constraints[{index}].target`", errors)
+            if source and target:
+                parsed.append(ForwardDependencyConstraint(source=source, target=target))
+            continue
+
+        if constraint_type == "conditional":
+            parent = normalize_scalar(raw_constraint.get("parent"))
+            parameter_name = normalize_scalar(raw_constraint.get("parameter"))
+            values = _parse_values(raw_constraint.get("values"), f"`constraints[{index}].values`", errors)
+            applies_when = _parse_values(raw_constraint.get("applies_when"), f"`constraints[{index}].applies_when`", errors)
+
+            if parent not in parameters:
+                errors.append(f"`constraints[{index}]` references unknown parent parameter `{parent}`.")
+                continue
+            if parameter_name not in parameters:
+                errors.append(
+                    f"`constraints[{index}]` references unknown conditional parameter `{parameter_name}`. "
+                    "`conditional` must define a child parameter with `values` and a parent gate. "
+                    "For exclusions or requirements between existing parameters, use `invalid_pair`, "
+                    "`higher_order`, `forward_dep`, or `bidirectional`; run `lattice agent instructions` "
+                    "for the full schema reference."
+                )
+                continue
+
+            parent_parameter = parameters[parent]
+            missing = [value for value in applies_when if value not in parent_parameter.value_set]
+            if missing:
+                errors.append(
+                    f"`constraints[{index}]` applies_when contains unknown values for `{parent}`: {', '.join(missing)}."
+                )
+                continue
+
+            if not values:
+                continue
+            parsed.append(
+                ConditionalConstraint(
+                    parameter=parameter_name,
+                    values=tuple(value for value in values if value != NA_VALUE),
+                    parent=parent,
+                    applies_when=applies_when,
+                )
+            )
+            continue
+
+        if constraint_type == "forced":
+            assignments = raw_constraint.get("assignments")
+            if not isinstance(assignments, list) or not assignments:
+                errors.append(f"`constraints[{index}].assignments` must contain at least one assignment.")
+                continue
+            seen_parameters: set[str] = set()
+            parsed_assignments: list[Assignment] = []
+            for assignment_index, raw_assignment in enumerate(assignments):
+                assignment = _parse_assignment(
+                    raw_assignment,
+                    parameters,
+                    f"`constraints[{index}].assignments[{assignment_index}]`",
+                    errors,
+                )
+                if assignment is None:
+                    continue
+                if assignment.parameter in seen_parameters:
+                    errors.append(
+                        f"`constraints[{index}]` repeats parameter `{assignment.parameter}` inside a forced interaction."
+                    )
+                    continue
+                seen_parameters.add(assignment.parameter)
+                parsed_assignments.append(assignment)
+            if parsed_assignments:
+                parsed.append(ForcedConstraint(assignments=tuple(parsed_assignments)))
+            continue
+
+        if constraint_type == "higher_order":
+            if_all = raw_constraint.get("if_all")
+            then_not = raw_constraint.get("then_not")
+            if not isinstance(if_all, list) or len(if_all) < 2:
+                errors.append(f"`constraints[{index}].if_all` must contain at least two assignments.")
+                continue
+            parsed_if_all: list[Assignment] = []
+            for assignment_index, raw_assignment in enumerate(if_all):
+                assignment = _parse_assignment(
+                    raw_assignment,
+                    parameters,
+                    f"`constraints[{index}].if_all[{assignment_index}]`",
+                    errors,
+                )
+                if assignment is not None:
+                    parsed_if_all.append(assignment)
+            parsed_then_not = _parse_assignment(then_not, parameters, f"`constraints[{index}].then_not`", errors)
+            if parsed_if_all and parsed_then_not:
+                parsed.append(HigherOrderConstraint(if_all=tuple(parsed_if_all), then_not=parsed_then_not))
+            continue
+
+        errors.append(f"`constraints[{index}]` has unknown type `{constraint_type}`.")
+
+    return parsed
+
+
+def _parse_assignment(
+    raw_assignment: Any,
+    parameters: "OrderedDict[str, Parameter]",
+    field_name: str,
+    errors: list[str],
+) -> Assignment | None:
+    if not isinstance(raw_assignment, dict):
+        errors.append(f"{field_name} must be an object.")
+        return None
+
+    parameter_name = normalize_scalar(raw_assignment.get("parameter"))
+    value = normalize_scalar(raw_assignment.get("value"))
+
+    parameter = parameters.get(parameter_name)
+    if parameter is None:
+        errors.append(f"{field_name} references unknown parameter `{parameter_name}`.")
+        return None
+
+    if value not in parameter.value_set:
+        errors.append(f"{field_name} references unknown value `{value}` for parameter `{parameter_name}`.")
+        return None
+
+    return Assignment(parameter=parameter_name, value=value)
+
+
+def _parse_values(raw_values: Any, field_name: str, errors: list[str]) -> tuple[str, ...]:
+    if not isinstance(raw_values, list) or not raw_values:
+        errors.append(f"{field_name} must be a non-empty list.")
+        return ()
+
+    values = tuple(normalize_scalar(value) for value in raw_values)
+    if len(set(values)) != len(values):
+        errors.append(f"{field_name} contains duplicate values.")
+        return ()
+    return values
+
+
+def _parse_weights(
+    raw_weights: Any,
+    values: tuple[str, ...],
+    parameter_name: str,
+    errors: list[str],
+) -> tuple[float, ...] | None:
+    if raw_weights is None:
+        return None
+    if not isinstance(raw_weights, list):
+        errors.append(f"`weights` for parameter `{parameter_name}` must be a list.")
+        return None
+    if len(raw_weights) != len(values):
+        errors.append(
+            f"`weights` for parameter `{parameter_name}` must have the same length as its values."
+        )
+        return None
+
+    parsed: list[float] = []
+    for weight in raw_weights:
+        if not isinstance(weight, (int, float)):
+            errors.append(f"`weights` for parameter `{parameter_name}` must be numeric.")
+            return None
+        if weight <= 0:
+            errors.append(f"`weights` for parameter `{parameter_name}` must be greater than zero.")
+            return None
+        parsed.append(float(weight))
+    return tuple(parsed)
+
+
+def _parse_strength(raw_strength: Any, parameter_count: int, errors: list[str]) -> int:
+    if raw_strength is None:
+        strength = 2
+    else:
+        try:
+            strength = int(raw_strength)
+        except (TypeError, ValueError):
+            errors.append("`strength` must be an integer.")
+            return 2
+
+    if strength < 1:
+        errors.append("`strength` must be at least 1.")
+    if parameter_count and strength > parameter_count:
+        errors.append("`strength` cannot exceed the number of parameters.")
+    return strength

lattice/resources/claude/lattice-workflow/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: lattice-workflow
+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.
+---
+
+# Lattice Workflow
+
+Use this skill to keep Claude on extraction and interpretation while Lattice handles combinatorial coverage.
+
+## When To Use It
+
+Use this skill when the task is any of:
+
+- derive a combinatorial model from a feature or PRD
+- derive a test matrix from existing code
+- derive a variant matrix from a component, partial, template, design-system story, or config surface
+- convert edge cases into explicit parameter/value constraints
+- generate pairwise or 3-way scenarios without hand-enumerating combinations
+- render a compact visual review matrix instead of every possible variant
+- review a plan involving roles, permissions, modes, providers, feature flags, optional fields, component props, rendering branches, template variants, config matrices, or lifecycle states
+- find coverage gaps where bugs are likely to hide in interactions rather than single branches
+
+Do not invent pairwise combinations manually. The schema is the contract. The generated rows are the source of truth. The schema file is optional transport.
+
+## Preflight
+
+Before using this skill, check whether `lattice` is already installed:
+
+```bash
+command -v lattice >/dev/null 2>&1 && lattice --help >/dev/null
+```
+
+If that succeeds, use the installed command.
+
+If it fails and you know the path to the Lattice source checkout, install it into the current Python environment:
+
+```bash
+python3 -m pip install -e /path/to/lattice
+```
+
+To install or refresh this skill from the installed package:
+
+```bash
+lattice agent install-claude-skill
+```
+
+## Workflow
+
+1. Extract the schema.
+   First choose the scope. A schema should usually describe one coherent interaction surface: one feature, one workflow, one service behavior, one endpoint family, one rendering surface, one component's variant space, one template family, one config matrix, or one data-model interaction surface. Then choose parameters that represent independent decisions or state partitions inside that scope. Choose values that are meaningful partitions, not every literal in the codebase.
+2. Encode constraints.
+   Prefer the smallest constraint type that matches the rule. Lattice supports exclusion-style constraints, not only conditional parameters: use `invalid_pair` when two assignments cannot coexist and `higher_order` when a combination only becomes invalid with multiple antecedents. Use `conditional` instead of hand-writing `N/A` values.
+3. Validate before generation.
+   Prefer the installed `lattice` command with JSON or YAML on stdin:
+
+   ```bash
+   cat schema.json | lattice validate
+   ```
+
+   If you are working inside this repository and the package is not installed yet, the fallback is:
+
+   ```bash
+   cat schema.json | PYTHONPATH=src python3 -m lattice validate
+   ```
+
+   Use a temp file only if the harness needs one for debugging or tool interop.
+4. Generate deterministic scenarios.
+
+   ```bash
+   cat schema.json | lattice generate
+   ```
+
+   The development fallback in this repo is:
+
+   ```bash
+   cat schema.json | PYTHONPATH=src python3 -m lattice generate
+   ```
+
+   Default to pairwise unless the user explicitly asks for a higher strength.
+5. Interpret the output.
+   In plan mode, turn rows into plan revisions, missing decisions, and review scenarios. In test mode, diff the rows against the existing tests and write the missing cases. In variant mode, turn rows into fixtures, rendered variants, screenshots, contact sheets, visual diff inputs, or review checklists.
+
+   In test mode, 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. 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.
+
+## Modeling Rules
+
+- Scope one schema to one interaction surface. Do not default to the whole app unless the app is genuinely small and the behavior or rendering surface is still coherent.
+- Keep parameter names stable and implementation-adjacent.
+- Use value partitions such as `present` and `absent`, not brittle prose.
+- Avoid derived duplicate parameters. If one field is determined by another, represent that as a constraint.
+- Add constraints only for true business or system rules. Do not use them to encode preferences.
+- Do not strip true constraints to make generation easier, and do not generate nonsensical rows just to mark them invalid later. Encoding constraints changes the coverage universe to valid interactions, which is the point of using Lattice.
+- If two assignments cannot coexist, use `invalid_pair`.
+- If a parameter only matters under a parent value, use `conditional`.
+- If a scenario must appear at least once, use `forced`.
+- If a rule only breaks under multiple antecedents, use `higher_order`.
+
+Read [references/modeling-rules.md](references/modeling-rules.md) when you need extraction heuristics or constraint selection guidance.
+
+## Output Discipline
+
+- Run `validate` before `generate`.
+- Prefer stdin and JSON because another agent step usually consumes the output.
+- Do not add or remove rows after generation.
+- If validation fails, fix the schema instead of weakening the generation step.
+- If generation emits rows that are impossible in the target system, stop and add the missing constraint rather than filtering or annotating those rows downstream.
+- In test mode, assertions must reflect intended behavior, not observed behavior. Read intent from the spec, PRD, ticket, or user — never from the code under test. If intent is ambiguous, stop and ask.
+
+Read [references/worked-examples.md](references/worked-examples.md) for concrete examples in this repo.

lattice/resources/claude/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.

lattice/resources/claude/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`