feat(examples): add scenario templates with validation commands and claim notes

docs/explain/getting-started.md

@@ -38,7 +38,7 @@ RAES can currently support:
 - parsing and validating SDL through the Python implementation
 - instantiating variables and compiling runtime models in the reference stack
 - checking backend contract fixtures and conformance profiles
-- browsing validated, non-normative examples, templates, and reusable patterns
+- browsing non-normative examples, templates, and reusable patterns
   for scenarios, workflows, participant behavior, tasks, runs, and studies
 - reviewing the specifications, ADRs, and examples that define current claims
 
@@ -219,7 +219,7 @@ Do not use examples to claim:
 
 ## Template And Pattern Boundary
 
-The current library provides validated authoring aids, not new runtime
+The current library provides authoring aids, not new runtime
 authority.
 
 Current status:

docs/explain/reference/canonical-reference-map.md

@@ -94,7 +94,7 @@ page is an index, not a replacement for the linked artifacts.
 ## Current Materialization Notes
 
 - SDL authoring, parsing, validation, instantiation, compilation, planning,
-  runtime manager/control-plane APIs, published JSON schemas, and a validated
+  runtime manager/control-plane APIs, published JSON schemas, and a
   non-normative template/pattern library are present in the repository.
 - Participant-implementation manifests, evidence-capture contracts, and
   provenance contract surfaces are described at the architecture level and are

examples/README.md

@@ -73,19 +73,69 @@ The AUT-806 library is indexed by
 [`library/catalog.yaml`](library/catalog.yaml). It is a versioned,
 machine-readable catalog for the current non-normative authoring library.
 
-| Surface | Template | Pattern |
-|---------|----------|---------|
-| Scenario | [`library/templates/scenario/minimal-validated-scenario.yaml`](library/templates/scenario/minimal-validated-scenario.yaml) | [`library/patterns/scenario-reference-integrity.yaml`](library/patterns/scenario-reference-integrity.yaml) |
+| Surface | Templates | Pattern |
+|---------|-----------|---------|
+| Scenario | [`library/templates/scenario/minimal-validated-scenario.yaml`](library/templates/scenario/minimal-validated-scenario.yaml), [`library/templates/scenario/segmented-network-scenario.yaml`](library/templates/scenario/segmented-network-scenario.yaml), [`library/templates/scenario/parameterized-scenario.yaml`](library/templates/scenario/parameterized-scenario.yaml) | [`library/patterns/scenario-reference-integrity.yaml`](library/patterns/scenario-reference-integrity.yaml) |
 | Workflow | [`library/templates/workflow/parallel-objective-workflow.yaml`](library/templates/workflow/parallel-objective-workflow.yaml) | [`library/patterns/workflow-explicit-control-graph.yaml`](library/patterns/workflow-explicit-control-graph.yaml) |
 | Participant behavior | [`library/templates/participant_behavior/action-contract-observation-boundary.yaml`](library/templates/participant_behavior/action-contract-observation-boundary.yaml) | [`library/patterns/participant-behavior-contract-binding.yaml`](library/patterns/participant-behavior-contract-binding.yaml) |
 | Task | [`library/templates/task/single-objective-task.yaml`](library/templates/task/single-objective-task.yaml) | [`library/patterns/task-as-objective-contract.yaml`](library/patterns/task-as-objective-contract.yaml) |
 | Run | [`library/templates/run/timed-run-control.yaml`](library/templates/run/timed-run-control.yaml) | [`library/patterns/run-window-with-evidence.yaml`](library/patterns/run-window-with-evidence.yaml) |
 | Study | [`library/templates/study/observational-study-protocol.yaml`](library/templates/study/observational-study-protocol.yaml) | [`library/patterns/observable-study-conditions.yaml`](library/patterns/observable-study-conditions.yaml) |
 
-Each template has metadata plus a complete current-SDL `body`. The
+Each template has metadata, a `validation` list of commands with their
+expected results, and a complete current-SDL `body`. The
 `tools/check_example_library.py` policy gate validates catalog shape, stable
-IDs, referenced paths, AUT-806 requirement references, and every template body
-through the SDL parser and semantic validator.
+IDs, referenced paths, AUT-806 requirement references, entry metadata, and
+every template body and validated worked example through the SDL parser and
+semantic validator. It also checks that each template has a non-empty
+`validation` list whose entries have non-empty `command` and `expected`
+strings. The gate does not run those commands.
+
+### Catalog entry metadata
+
+Every `worked_examples`, `templates`, and `patterns` entry in the catalog
+records four fields. The policy gate rejects an entry that omits a field or
+breaks these rules.
+
+| Field | Allowed values | What the gate checks |
+|-------|----------------|----------------------|
+| `validation_status` | `validated` or `guidance` | For `validated`, the gate runs the SDL parser and semantic validator on the worked-example file, or on the template body as the `sdl-yaml/v1` loader reads it from the template file, and fails on any error or advisory they report. That loader rejects duplicate keys, merge keys, and explicit tags in the template file. A `guidance` file is not parsed as SDL. Templates must be `validated`; patterns must be `guidance`. |
+| `sdl_sections` | Top-level section names from [`../specs/sdl/sections.md`](../specs/sdl/sections.md), such as `nodes` or `workflows` | Each name is a current SDL section, not a metadata or composition field such as `name` or `imports`. For a `validated` entry, each listed section is present in the validated SDL. |
+| `intended_user` | `sdl-author` | The value is in the allowed list. |
+| `limits` | One or more short statements of what the entry does not show | The list is present and not empty. Reviewers check the wording. |
+
+`sdl_sections` names the sections that an entry shows for its surface, so a
+large worked example lists only some of the sections it uses. `validated`
+means that current SDL validation accepts the file or template body. It does
+not mean that a backend can realize the scenario or that anything has run. A
+`guidance` entry is reading material, such as a prose pattern or a test
+module, and the gate does not parse it as SDL.
+
+### Scenario templates
+
+Each scenario template claims only that current SDL validation accepts its
+body with no advisories.
+
+| Template | Shows | Does not claim |
+|----------|-------|----------------|
+| [`minimal-validated-scenario`](library/templates/scenario/minimal-validated-scenario.yaml) | One host service, one participant, an objective whose success is an assertion over an observed proposition, and a workflow with one objective step | That a backend can realize the scenario |
+| [`segmented-network-scenario`](library/templates/scenario/segmented-network-scenario.yaml) | Two switched segments, a linked host with a fixed address on each, access rules that admit only HTTPS from the user segment into the server segment, and a service feature | That a backend enforces the access rules or installs the feature |
+| [`parameterized-scenario`](library/templates/scenario/parameterized-scenario.yaml) | Host operating system, size, instance count, and service port taken from declared variables with defaults and an allowed-values list | That the scenario instantiates with every supplied value; the gate does not instantiate it |
+
+To check a template as shipped, run the catalog command in
+[Validate The Examples](#validate-the-examples). To check an adapted copy, save
+its `body` as `my-scenario.sdl.yaml` in the repository root and run this
+command from there:
+
+```shell
+uv run --project implementations/python --frozen raes semantic validate my-scenario.sdl.yaml
+```
+
+The command prints `validate: success` and exits `0` when the SDL parser and
+semantic validator accept the file. It does not report semantic-validator
+advisories, such as a compute node without `resources`. The `parse_sdl_file`
+check in [Validate The Examples](#validate-the-examples) asserts that there
+are none.
 
 ## Validate The Examples
 
@@ -137,11 +187,18 @@ Check the section reference and limitations before adapting a file:
 
 ## Template Boundary
 
-There are no placeholder templates in this directory. Files under
+No template in this directory contains incomplete SDL. Files under
 `examples/scenarios/` are positive SDL examples and must load successfully from
 disk. Files under `examples/library/templates/` are reusable authoring
 templates with complete SDL bodies; they are validated by the example-library
-policy gate.
+policy gate. A template body may use `${name}` variable placeholders, as
+`parameterized-scenario` does. A placeholder's `name` follows the variable-name
+grammar in
+[`../specs/sdl/variables-and-instantiation.md`](../specs/sdl/variables-and-instantiation.md)
+(lowercase letters, digits, `-`, and `_`), and the gate rejects a body whose
+placeholder names a variable that the body does not declare under `variables`.
+Text such as `${Web OS}` or `${CUSTOMER_NAME}` is not a placeholder: it stays
+literal text, and the gate does not report it as an undeclared variable.
 
 Do not add invalid or incomplete SDL files under `examples/scenarios/`.
 Negative-path examples belong in focused parser, model, validator, contract, or

examples/library/catalog.yaml

@@ -6,8 +6,8 @@ source_refs:
   - docs/public/quickstart.md
   - docs/explain/reference/canonical-reference-map.md
 description: >
-  Domain-neutral RAES agentic-environment authoring library for non-normative,
-  validated examples, templates, and reusable patterns. Current examples are
+  Domain-neutral RAES agentic-environment authoring library for non-normative
+  examples, templates, and reusable patterns. Current examples are
   strongest in cyber; additional domains extend through their own profiles,
   assets, backends, and evidence requirements. Template bodies use current SDL
   so they can be parsed and semantically validated by the Python reference
@@ -19,72 +19,181 @@ surfaces:
       - id: hospital-ransomware-surgery-day
         path: examples/scenarios/hospital-ransomware-surgery-day.sdl.yaml
         source_refs: [examples/README.md]
+        validation_status: validated
+        sdl_sections: [nodes, infrastructure, features, entities, agents, relationships, content, conditions, objectives]
+        intended_user: sdl-author
+        limits:
+          - Does not deploy a hospital range or prove clinical exercise adequacy.
       - id: cross-backend-minimal
         path: examples/scenarios/cross-backend-minimal.sdl.yaml
         source_refs: [examples/README.md]
+        validation_status: validated
+        sdl_sections: [nodes, infrastructure]
+        intended_user: sdl-author
+        limits:
+          - Does not exercise an OCI runtime or live libvirt/QEMU daemon and makes no infrastructure-equivalence or fidelity claim.
     templates:
       - id: minimal-validated-scenario
         path: examples/library/templates/scenario/minimal-validated-scenario.yaml
+        validation_status: validated
+        sdl_sections: [nodes, conditions, entities, agents, propositions, assertions, evidence_requirements, objectives, workflows]
+        intended_user: sdl-author
+        limits:
+          - Validation covers SDL structure and references; it does not show that a backend can realize the scenario.
+      - id: segmented-network-scenario
+        path: examples/library/templates/scenario/segmented-network-scenario.yaml
+        validation_status: validated
+        sdl_sections: [nodes, features, infrastructure]
+        intended_user: sdl-author
+        limits:
+          - Validation covers topology structure, addresses, and references; it does not show that a backend enforces the access rules or installs the feature.
+      - id: parameterized-scenario
+        path: examples/library/templates/scenario/parameterized-scenario.yaml
+        validation_status: validated
+        sdl_sections: [variables, nodes, infrastructure]
+        intended_user: sdl-author
+        limits:
+          - The gate validates the authored body and does not instantiate it with any variable values.
     patterns:
       - id: scenario-reference-integrity
         path: examples/library/patterns/scenario-reference-integrity.yaml
+        validation_status: guidance
+        sdl_sections: [nodes, entities, agents, objectives, workflows]
+        intended_user: sdl-author
+        limits:
+          - Covers reference resolution only, not backend realization.
   workflow:
     summary: Declarative workflow authoring over objectives and branch state.
     worked_examples:
       - id: satcom-release-poisoning-workflows
         path: examples/scenarios/satcom-release-poisoning.sdl.yaml
         source_refs: [examples/README.md]
+        validation_status: validated
+        sdl_sections: [objectives, workflows, variables]
+        intended_user: sdl-author
+        limits:
+          - Does not implement a CI/CD backend or production release system.
     templates:
       - id: parallel-objective-workflow
         path: examples/library/templates/workflow/parallel-objective-workflow.yaml
+        validation_status: validated
+        sdl_sections: [nodes, conditions, entities, agents, propositions, assertions, evidence_requirements, objectives, workflows]
+        intended_user: sdl-author
+        limits:
+          - Validation covers the workflow graph and its references; no workflow is executed.
     patterns:
       - id: workflow-explicit-control-graph
         path: examples/library/patterns/workflow-explicit-control-graph.yaml
+        validation_status: guidance
+        sdl_sections: [objectives, workflows]
+        intended_user: sdl-author
+        limits:
+          - Covers workflow graph authoring only; it does not execute workflows.
   participant_behavior:
     summary: Participant action contracts, observation boundaries, behavior specifications, and agent bindings.
     worked_examples:
       - id: sem-208-participant-behavior
         path: implementations/python/tests/test_sem_208_participant_behavior.py
         source_refs: [docs/explain/sdl/validation.md]
+        validation_status: guidance
+        sdl_sections: [agents, action_contracts, observation_boundaries, behavior_specifications]
+        intended_user: sdl-author
+        limits:
+          - A pytest module rather than an SDL file; the test suite parses and validates its inline SDL, and this gate does not.
     templates:
       - id: action-contract-observation-boundary
         path: examples/library/templates/participant_behavior/action-contract-observation-boundary.yaml
+        validation_status: validated
+        sdl_sections: [nodes, entities, action_contracts, observation_boundaries, agents, behavior_specifications]
+        intended_user: sdl-author
+        limits:
+          - Validation covers the participant declarations and their references; it does not run a participant or show backend support.
     patterns:
       - id: participant-behavior-contract-binding
         path: examples/library/patterns/participant-behavior-contract-binding.yaml
+        validation_status: guidance
+        sdl_sections: [agents, action_contracts, observation_boundaries]
+        intended_user: sdl-author
+        limits:
+          - Covers declaring and binding contracts only; it does not show participant runtime behavior.
   task:
     summary: Task-oriented authoring using current objectives, conditions, and target refs.
     worked_examples:
       - id: port-authority-objective-tasks
         path: examples/scenarios/port-authority-surge-response.sdl.yaml
         source_refs: [examples/README.md]
+        validation_status: validated
+        sdl_sections: [agents, conditions, propositions, assertions, objectives, workflows]
+        intended_user: sdl-author
+        limits:
+          - Does not implement OT control, safety validation, or port operations.
     templates:
       - id: single-objective-task
         path: examples/library/templates/task/single-objective-task.yaml
+        validation_status: validated
+        sdl_sections: [nodes, conditions, entities, agents, propositions, assertions, evidence_requirements, objectives, workflows]
+        intended_user: sdl-author
+        limits:
+          - SDL has no first-class tasks section, and this objective is not an experiment-task-v1 record.
     patterns:
       - id: task-as-objective-contract
         path: examples/library/patterns/task-as-objective-contract.yaml
+        validation_status: guidance
+        sdl_sections: [agents, conditions, propositions, assertions, objectives, workflows]
+        intended_user: sdl-author
+        limits:
+          - SDL has no first-class tasks section, and an objective written this way is not an experiment-task-v1 record.
   run:
     summary: Run-oriented authoring with story, script, event, workflow, and objective windows.
     worked_examples:
       - id: hospital-run-story
         path: examples/scenarios/hospital-ransomware-surgery-day.sdl.yaml
         source_refs: [examples/README.md]
+        validation_status: validated
+        sdl_sections: [injects, events, scripts, stories, objectives]
+        intended_user: sdl-author
+        limits:
+          - Story, script, and event timing is authored SDL; nothing is scheduled or run.
     templates:
       - id: timed-run-control
         path: examples/library/templates/run/timed-run-control.yaml
+        validation_status: validated
+        sdl_sections: [nodes, conditions, injects, events, scripts, stories, entities, agents, propositions, assertions, evidence_requirements, objectives, workflows]
+        intended_user: sdl-author
+        limits:
+          - SDL has no first-class runs section; the template expresses a run with stories, scripts, and events, and nothing is scheduled or run.
     patterns:
       - id: run-window-with-evidence
         path: examples/library/patterns/run-window-with-evidence.yaml
+        validation_status: guidance
+        sdl_sections: [injects, events, scripts, stories, objectives, workflows]
+        intended_user: sdl-author
+        limits:
+          - SDL has no first-class runs section; the pattern maps a run onto stories, scripts, events, and objective windows.
   study:
     summary: Study-oriented authoring with observable conditions, objectives, and workflow protocol. Graded scoring is an experiment/evaluator-plane concern per ADR-073.
     worked_examples:
       - id: satcom-study-scenario
         path: examples/scenarios/satcom-release-poisoning.sdl.yaml
         source_refs: [examples/README.md]
+        validation_status: validated
+        sdl_sections: [conditions, propositions, assertions, evidence_requirements, objectives, workflows]
+        intended_user: sdl-author
+        limits:
+          - Declares observable conditions only; graded scoring and reward are outside the SDL per ADR-073.
     templates:
       - id: observational-study-protocol
         path: examples/library/templates/study/observational-study-protocol.yaml
+        validation_status: validated
+        sdl_sections: [nodes, conditions, entities, agents, propositions, assertions, evidence_requirements, objectives, workflows]
+        intended_user: sdl-author
+        limits:
+          - SDL has no first-class studies section; graded scoring stays in the experiment/evaluator plane per ADR-073.
     patterns:
       - id: observable-study-conditions
         path: examples/library/patterns/observable-study-conditions.yaml
+        validation_status: guidance
+        sdl_sections: [conditions, propositions, assertions, evidence_requirements, objectives, workflows]
+        intended_user: sdl-author
+        limits:
+          - SDL has no first-class studies section; graded scoring stays in the experiment/evaluator plane per ADR-073.

examples/library/patterns/task-as-objective-contract.yaml

@@ -16,7 +16,8 @@ use_when:
 authoring_steps:
   - Create or reuse the participant agent that owns the task.
   - Define the task target as a targetable SDL reference.
-  - Add a condition, metric, evaluation, TLO, or goal that proves completion.
+  - Reference a postcondition assertion over a completion proposition from objective success.
+  - Bind a condition probe to the proposition when an executable check is needed.
   - Place the objective in a workflow when task order matters.
 validation:
   - command: parse_sdl_file