docs(examples): record analysis runs in the model and report them in a document

.agents/skills/testing-pilot-corpora-gate/SKILL.md

@@ -183,8 +183,8 @@ gate's own helpers are package-private but reusable (`pilotCorporaGate.files(t)`
 
 `actionlint`, `shellcheck`, `python3 scripts/check-doc-links.py`, `gofmt`, `go vet`,
 `go run -C tools ./cmd/pilot-diff` (validators pre-downloaded; ~4min, prints e.g.
-the headline the committed baseline holds — `378 file(s), 347 fully agreeing; 38 agreed
-diagnostic(s), 38 only ours, 1185 only the pilot's` after the Legend of the Red Dragon example left for its own repository at the `2026-08` pin, so read it from
+the headline the committed baseline holds — `379 file(s), 347 fully agreeing; 38 agreed
+diagnostic(s), 38 only ours, 1582 only the pilot's` at the `2026-08` pin, so read it from
 `docs/project/pilot-differential-baseline.json` rather than from this line)
 and `make lint` (staticcheck+gosec, ~2min) all work. There is **no** `yamllint` and **no**
 `circleci` CLI, so `.circleci/config.yml` can only be parsed as YAML, not schema-validated — say so

.agents/skills/testing-pilot-differential/SKILL.md

@@ -21,9 +21,9 @@ GNU-format diagnostics **relative to `--root`**. Consequences for testing:
 - The pin `tools/referee/diff` reports comes from `build/pilot-sysml-validator/pilot-pin.txt`
   (written by the new script), not from the DeciSym `pom.xml`.
 - `-validator /nonexistent` now says `run ./scripts/download-pilot-sysml-validator.sh`.
-- Measured after the Legend of the Red Dragon example left for its own repository at the `2026-08` pin, with a fresh library cache: `378 file(s), 347 fully agreeing; 38 agreed,
-  38 only ours, 1185 only the pilot's`, JSON totals `openSysMLDiagnostics 79 / pilotDiagnostics
-  1226 / severityMismatch 3`; ~2 min wall, byte-identical across runs *and* after a from-scratch
+- Measured at the `2026-08` pin, with a fresh library cache: `379 file(s), 347 fully agreeing; 38 agreed,
+  38 only ours, 1582 only the pilot's`, JSON totals `openSysMLDiagnostics 79 / pilotDiagnostics
+  1623 / severityMismatch 3`; ~2 min wall, byte-identical across runs *and* after a from-scratch
   rebuild of `build/pilot-validator`. The six `kerml-examples` pilot-only rows the `2026-07` run
   carried (`The opposite features 'owningType' … do not refer to each other`) are gone: the pilot
   fixed its `ownedDisjoining` delegate, and nothing on our side moved. `kerml-examples` carries no `syntax` diagnostic on either
@@ -137,7 +137,7 @@ The harness compares OpenSysML diagnostics against the OMG SysML v2 Pilot Implem
 `build/pilot-diff/pilot-diff.{txt,json}`. `docs/project/pilot-differential-baseline.json` is the
 committed result of the *last refreshed* run, so **the harness is testable by reproduction** —
 but only while the baseline is current. Check that first. As of the rebaseline that came when the Legend of the Red Dragon example left for its own repository it **is**
-current: a live run gives `378 file(s), 347 fully agreeing; 38 agreed, 38 only ours, 1185 only the
+current: a live run gives `379 file(s), 347 fully agreeing; 38 agreed, 38 only ours, 1582 only the
 pilot's`, byte-identical to the committed baseline, and `docs/project/pilot-differential.md`'s
 "Results" table matches. The rebaseline before it, at the architecture self-model's landing, covered two rounds, because the succession-shorthand
 removal before it landed without refreshing the baseline; a control run of its merge commit gives

.agents/skills/testing-pilot-execution-referee/SKILL.md

@@ -148,8 +148,8 @@ pilot answers the representation's own. See
   `pilot-exec-diff: <file>:<line>: model no/such/model.sysml: stat <abs>: no
   such file or directory`.
 - **Additivity.** `go run -C tools ./cmd/pilot-diff` must still print the headline the
-  committed baseline holds (`378 file(s), 347 fully agreeing; 38 agreed
-  diagnostic(s), 38 only ours, 1185 only the pilot's` after the Legend of the Red Dragon example left for its own repository at the `2026-08` pin — read it from the baseline JSON, not from this line, since each
+  committed baseline holds (`379 file(s), 347 fully agreeing; 38 agreed
+  diagnostic(s), 38 only ours, 1582 only the pilot's` at the `2026-08` pin — read it from the baseline JSON, not from this line, since each
   fix round moves it) and `jq -S` diff clean against
   `docs/project/pilot-differential-baseline.json`; `git status --porcelain`
   empty at the end.

.agents/skills/testing-pilot-xpect/SKILL.md

@@ -416,8 +416,8 @@ census in `w5c_census_test.go` is live two ways: perturb one pinned triple (e.g.
 ## Regression neighbour
 
 `go run -C tools ./cmd/pilot-diff` (~1m12s) must still print the headline the *committed* baseline holds —
-after the Legend of the Red Dragon example left for its own repository at the `2026-08` pin that is `378 file(s), 347 fully agreeing; 38 agreed diagnostic(s), 38
-only ours, 1185 only the pilot's`. Read the number out of
+at the `2026-08` pin that is `379 file(s), 347 fully agreeing; 38 agreed diagnostic(s), 38
+only ours, 1582 only the pilot's`. Read the number out of
 `docs/project/pilot-differential-baseline.json` rather than trusting this line, since a landing fix
 round moves it. When the baseline is itself stale (it was at `19a3ce03`, holding 273 / 281 / 317), a
 failing `cmp` against it is *not* evidence of an Xpect regression — compare the summary line, and see

README.md

@@ -313,11 +313,11 @@ The project is under active development, with the core infrastructure operationa
 <!-- doc-counts:begin refereed-figures -->
 **Measured against the pinned reference** (`PILOT_TAG=2026-08`, artifact `0.62.0`). Every number below is generated by `make docs-counts` from the committed baselines and gated; none of them is typed in by hand.
 
-- **Corpus agreement:** 347 of 378 files agree diagnostic-by-diagnostic; 38 diagnostics are ours alone and 1185 the reference's alone, and the first number must be read by root: our diagnostics against the reference's own corpora fell while our non-standard-notation warnings on our own example models rose ([differential](docs/project/pilot-differential.md), `go run -C tools ./cmd/pilot-diff`).
+- **Corpus agreement:** 347 of 379 files agree diagnostic-by-diagnostic; 38 diagnostics are ours alone and 1582 the reference's alone, and the first number must be read by root: our diagnostics against the reference's own corpora fell while our non-standard-notation warnings on our own example models rose ([differential](docs/project/pilot-differential.md), `go run -C tools ./cmd/pilot-diff`).
 - **Declared-diagnostic silence:** of the 512 declared `errors` rows in the reference's own Xpect suites, we report nothing for 0. 245 we report word-for-word; 248 wording-only and 7 location-only differences are agreement in substance and are not counted as gaps; 0 more we report as a warning and 2 elsewhere in the file ([Xpect oracle](docs/project/pilot-xpect.md), `go run -C tools ./cmd/pilot-xpect`).
 - **Scope agreement:** 230 of 230 declared scope assertions match exactly (same source).
 - **Permissiveness gaps:** of 306 invalid models we wrote ourselves, the reference rejects 4 that we accept by default, and 293 both reject; 4 further cases agree only when we are asked strictly. We authored every one of these cases ourselves, so the denominator measures the reach of our own corpus and not our conformance; agreement reached only under an opt-in strict mode is weaker evidence than agreement by default ([rejection oracle](docs/project/pilot-rejection.md), `go run -C tools ./cmd/pilot-reject`).
-- **Declared errata:** the registry declares 12 defect(s) in the published reference material — 4 with a specification-derived correction, 8 documented without one, since no intended reading can be inferred ([OMG issues](docs/project/omg-issues.md), `tools/oracle/errata`). Every figure above is as published and stays the conformance statement; running the same oracles over the corrected text instead reports 348 of 378 files agreeing, 37 diagnostics ours alone and 1185 the reference's alone, 0 declared rows we are silent on, and 0 of 306 authored cases the reference alone rejects. The corrected figures are diagnostic only: an erratum never reclassifies a divergence category, and the published corpus is never edited.
+- **Declared errata:** the registry declares 12 defect(s) in the published reference material — 4 with a specification-derived correction, 8 documented without one, since no intended reading can be inferred ([OMG issues](docs/project/omg-issues.md), `tools/oracle/errata`). Every figure above is as published and stays the conformance statement; running the same oracles over the corrected text instead reports 348 of 379 files agreeing, 37 diagnostics ours alone and 1582 the reference's alone, 0 declared rows we are silent on, and 0 of 306 authored cases the reference alone rejects. The corrected figures are diagnostic only: an erratum never reclassifies a divergence category, and the published corpus is never edited.
 - **Self-assessed surface:** the action, state-machine and classifier-behavior rows have no external referee at all — the four refereed figures above cannot see them, because the pinned artifact evaluates expressions but executes neither actions nor state machines. [Spec compliance](docs/project/spec-compliance.md) counts them.
 
 What these numbers cannot show: the OMG corpora are demonstrations rather than an official conformance suite; the differential is one-directional, comparing the diagnostics the two implementations report on the same files; the Xpect suites are the pilot authors' test intent rather than a certification oracle; and none of these is a percentage of the specification — no global compliance figure is claimed anywhere.
@@ -329,7 +329,7 @@ What these numbers cannot show: the OMG corpora are demonstrations rather than a
 **Test coverage:** top-level `Test` functions (counted from the `_test.go` files, as `go test ./...` runs them) covering parsers, semantics, runtime (actions, states, instances, operators, validation), behind golden ASTs, negatives, execution conformance cases, golden traces, runtime robustness cases and gRPC conformance and robustness cases. The figures are counted from the tree when the documentation site is built into the test inventory of [spec compliance](docs/project/spec-compliance.md), never committed, so a branch adding a test does not rewrite this page. A test skips only for want of something the run did not provide, and says what: the held-image round trip declines a conformance case that creates no instance, a few gate on a PDF or Mermaid toolchain, a pinned pilot artifact, the PSSM suite, a locale, a case-insensitive filesystem or a live Flexo stack, and the OMG corpus gates skip until the corpora are downloaded unless asked to fail.
 **Parser coverage:** 105/105 bundled library files parse cleanly — the 94 official SysML v2 standard library files and the non-normative `OpenSysML Libraries/OpenSysMLMathFunctions.kerml`, `OpenSysML Libraries/DocumentQueries.sysml`, `OpenSysML Libraries/IdentityMetadata.sysml`, `OpenSysML Libraries/DiagramLayout.sysml`, `OpenSysML Libraries/OOSEM.sysml`, `OpenSysML Libraries/MOSA.sysml`, `OpenSysML Libraries/StateSpaceIntegration.sysml`, `OpenSysML Libraries/Stochastic.sysml`, `OpenSysML Libraries/RandomFunctions.kerml`, `OpenSysML Libraries/Simulation.sysml` and `OpenSysML Libraries/MigrationMetadata.sysml` extensions. Conformance verified by [stdlib_conformance_test.go](internal/workspace/libs/stdlib_conformance_test.go). Grammar reference: [OMG Xtext grammar](https://github.com/Systems-Modeling/SysML-v2-Pilot-Implementation/tree/master/org.omg.kerml.xtext/src/org/omg/kerml/xtext).
 **Behavioral execution:** Calc/constraint/requirement/satisfy functional. Action/state executors handle nested invocation, control flow keywords, loop and conditional statements and the send statement (<!-- doc-counts:begin conformance-passing -->every conformance case passing<!-- doc-counts:end conformance-passing -->). Coverage is self-assessed against the specification text and the normative library: the pinned OMG pilot implementation evaluates expressions but does not execute actions or state machines headlessly, so no external implementation currently adjudicates these rows. See [spec compliance](docs/project/spec-compliance.md).
-**Reference differential:** 378 files compared diagnostic-by-diagnostic against the pinned OMG pilot implementation (`2026-08`), 347 in full agreement; every divergence is enumerated and adjudicated in [the differential](docs/project/pilot-differential.md), reproducible with `go run -C tools ./cmd/pilot-diff`.
+**Reference differential:** 379 files compared diagnostic-by-diagnostic against the pinned OMG pilot implementation (`2026-08`), 347 in full agreement; every divergence is enumerated and adjudicated in [the differential](docs/project/pilot-differential.md), reproducible with `go run -C tools ./cmd/pilot-diff`.
 **Rejection oracle:** the reverse direction — do we reject what the reference rejects? 306 hand-written invalid models validated by both implementations, 297 rejected by both, 0 the pinned pilot rejects and we accept; the remainder only we reject — the control-node succession rules the pinned pilot leaves unimplemented and a non-Boolean succession guard it accepts once the standard library types it — and every permissiveness gap is enumerated with a reproducer and likely root cause in [the rejection oracle](docs/project/pilot-rejection.md), reproducible with `go run -C tools ./cmd/pilot-reject`. We wrote every case, so the count measures our coverage of the rejection surface, not our conformance — a sample, not a proof.
 **Training examples:** 100/100 files clean, gated by `tests/corpus/testdata/training_examples_expected.txt`. Download with `./scripts/download-training-examples.sh` (from the [OMG training directory](https://github.com/Systems-Modeling/SysML-v2-Pilot-Implementation/tree/master/sysml/src/training)). See [training examples](docs/project/training-examples.md) for analysis.
 **Semantic layer:** a complete implementation of runtime operators, feature chains and validation rules. See [examples/semantic-layer/](examples/semantic-layer/) for a full demonstration.

changes/unreleased/analysis-results-demo.added.md

@@ -0,0 +1 @@
+- **Added `examples/analysis-results-demo/`, a worked example of saving analysis runs into the model and reporting them in a document.** The records are `part` usages on the bundled `AnalysisRecords` vocabulary — the same shape `-record-run`/`%record` emits, written by hand to keep pre-edit values — and a generated report groups, filters and lists them, flags the record a later model edit made stale through a derived `drift`/`stale` pair, and contrasts them with `Verdicts` recomputed live at render time.

cmd/sysml/examples_analysis_results_test.go

@@ -0,0 +1,91 @@
+package main
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// TestAnalysisResultsExample runs the analysis-results demo end to end: the
+// rendered report matches its committed output, the stale-records query
+// returns exactly the record the model moved away from, and the analysis
+// still prints the fuelLeft the scout record saved.
+func TestAnalysisResultsExample(t *testing.T) {
+	binary := buildCLI(t)
+	examples := filepath.Join("..", "..", "examples", "analysis-results-demo")
+	source := filepath.Join(examples, "lander-results.sysml")
+
+	committed, err := os.ReadFile(filepath.Join(examples, "report.md"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	out := filepath.Join(t.TempDir(), "report.md")
+	render := exec.Command(binary, source, "-render-document", "Reporting::AnalysisReport", "-o", out)
+	if output, err := render.CombinedOutput(); err != nil {
+		t.Fatalf("render: %v\n%s", err, output)
+	}
+	written, err := os.ReadFile(out)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(written) != string(committed) {
+		t.Errorf("rendered example differs from examples/analysis-results-demo/report.md:\n%s", written)
+	}
+
+	stale := exec.Command(binary, source, "-run-query", "Reporting::StaleRuns")
+	output, err := stale.CombinedOutput()
+	if err != nil {
+		t.Fatalf("stale query: %v\n%s", err, output)
+	}
+	for _, want := range []string{
+		"returned 1 row",
+		"Row 1: Records::relayRun",
+		"drift = 30.0",
+		"liveFuelLeft = 110.0",
+	} {
+		if !strings.Contains(string(output), want) {
+			t.Errorf("stale query output is missing %q:\n%s", want, output)
+		}
+	}
+
+	// The recorded baseline must match what the case still prints; if the
+	// model moves so the printed value differs from scoutRun's fuelLeft, this
+	// catches the record silently drifting.
+	run := exec.Command(binary, source, "-analysis", "Descent::scoutBudget")
+	output, err = run.CombinedOutput()
+	if err != nil {
+		t.Fatalf("analysis: %v\n%s", err, output)
+	}
+	if !strings.Contains(string(output), "fuelLeft = 130.0") {
+		t.Errorf("scoutBudget no longer prints the recorded fuelLeft = 130.0:\n%s", output)
+	}
+
+	// A run written back with -record-run lands in the same Records package
+	// the report's queries walk, so the document must show it alongside the
+	// hand-written records — and only it, in the run-table filters that name
+	// the hand-written defs.
+	t.Run("RecordedRunJoinsTheReport", func(t *testing.T) {
+		recorded := filepath.Join(t.TempDir(), "recorded-report.md")
+		render = exec.Command(binary, source, "-record-run", "Descent::scoutBudget",
+			"-render-document", "Reporting::AnalysisReport", "-o", recorded)
+		if output, err := render.CombinedOutput(); err != nil {
+			t.Fatalf("render with -record-run: %v\n%s", err, output)
+		}
+		written, err := os.ReadFile(recorded)
+		if err != nil {
+			t.Fatal(err)
+		}
+		text := string(written)
+		if !strings.Contains(text, "| scoutBudget\\_run1 | Descent::scoutBudget | run | Landers::scout | satisfied |") {
+			t.Errorf("recorded run missing from the every-recorded-run table:\n%s", text)
+		}
+		if !strings.Contains(text, "| scoutBudget\\_run1 | run | Descent::scoutBudget |") {
+			t.Errorf("recorded run missing from the provenance table:\n%s", text)
+		}
+		if strings.Count(text, "| relayRun | Landers::relay | 40 | 80 | 110 | 30 |") != 1 {
+			t.Errorf("stale table does not contain exactly the relay record:\n%s", text)
+		}
+	})
+}