[devin-ai-integration]

What and why

examples/self-model/ is OpenSysML's architecture written in SysML v2, and examples/self_model_test.go reads the facts back out of the analysed model and compares them with the implementation. The facts that test pins (pass registry, budgets, rendering kinds, export formats, RPCs, LSP capabilities, analysis engines, identity and sync) were current at origin/develop = 76c98694c; the surfaces it does not pin had drifted. The tree carries nine commands (cmd/), an MCP server, a Jupyter kernel with its Python package and JupyterLab extension, four JSON-RPC commands a WebAssembly host runs, Markdown and AsciiDoc parsers behind a prose body, a CLI with four report formats and an FMI gate over the Modelica Reference-FMUs — and the model had none of them (grep -ci of the model at 76c98694c: mcp 0, jupyter 0, asciidoc 0, wasm 1).

This PR audits the model against cmd/, internal/, client/, editors/, Makefile and docs/internals/architecture.md at that commit, models every gap in the file it belongs to, pins every new fact in a second test file (examples/self_model_surfaces_test.go, so self_model_test.go stays under the 2,000-line cap of tests/hygiene/size_test.go), exposes the new parts in two new views, extends the architecture document's queries and prose, and brings the README's file table and figures back in line with real runs.

Audit

Status: ok = modelled and pinned before this PR; wrong = modelled, corrected here; missing = added here; out of scope = not modelled, with the reason.

Area	Implementation at 76c98694c	Model before	Now
Commands	COMMANDS := sysml sysml-lsp sysml-grpc sysml-jupyter-kernel sysml-mcp (5 released), WASM_COMMANDS adds sysml-engine sysml-syntax sysml-core sysml-wasm (9)	sysml, sysml-lsp, sysml-grpc only; comment said "the three commands build for WebAssembly"	missing → Toolchain.releasedCommandCount = 5, wasmCommandCount = 9, one part per command; pinned against the two Makefile variables (TestSelfModelCommandsMatchMakefile)
REPL, LSP, gRPC/Connect, stdio, CLI	internal/frontend/{repl,lsp,grpc,stdio}, cmd/sysml	ok	ok
CLI report formats	-format text|json|sarif|junit, internal/frontend/report/{sarif,junit}	missing	CommandLine.reportSetting/reportFormats/reportPackages; pinned against cmd/sysml usage and the report packages
MCP server	cmd/sysml-mcp, internal/frontend/mcp (catalog groups lsp, runtime, session, -tools, -http, /mcp, OPENSYSML_MCP_TOKEN), packaging/mcp/server.json, make conformance-mcp	missing	McpServer part; pinned against the catalog groups, flags, path and token constants, the manifest and the Make target
Jupyter kernel	cmd/sysml-jupyter-kernel, internal/frontend/jupyter (kernel sysml, display name SysML v2 (OpenSysML), nine MIME types), wraps the REPL	missing	JupyterKernel part wired to repl; pinned against the kernelspec constants, flags and MIME constants
JSON-RPC / WebAssembly commands	cmd/sysml-syntax (Parse, Format, Tokens), cmd/sysml-engine, cmd/sysml-core, cmd/sysml-wasm (internal/frontend/{syntax,engine,core,combined} over internal/frontend/jsonrpc); release ships sysml-wasm.wasm	missing (one wasm mention)	JsonCommand with SyntaxCommand, EngineCommand, CoreCommand, CombinedCommand; serves pinned against each package's switch method dispatch, released/buildsForWasm against the Makefile, releaseAsset against build-release-wasm, stateless against whether the package imports the library
Generated clients (Go, Python, Java, Node, C++), Julia, MATLAB	client/	ok	ok
Jupyter kernel package	client/jupyter-kernel (jupyter-opensysml-kernel, make jupyter-kernel-install/-test)	missing	JupyterKernelPackage; pinned against pyproject.toml and the Make targets
JupyterLab extension	editors/jupyterlab (jupyterlab-opensysml, src/syntax.json, make jupyterlab-build/-test)	missing	JupyterLabExtension; pinned against package.json, the syntax table and the Make targets
VS Code extension	editors/vscode — six opensysml.* commands, sysml/kerml languages, diagram webview, landing page, tools/gengrammar, make vscode-grammar	partly: part existed, no commands/diagram panel/grammar generator	wrong → commands, languages, webview and landing sources, grammar generator and target added; pinned against package.json, the source directories and the Makefile
Cameo, SysON integrations	client/java-based	ok	ok
Editor pipeline (highlight, quick fixes, suggestions, edits, format, provenance)	internal/semantic/highlight, internal/check/edit, …	ok	ok
View engine, rendering kinds	internal/ir/view	ok	ok
Document path (query → plan → tree → Markdown/HTML/PDF)	internal/doc/*	ok	ok
Markup parsers	internal/ir/docplan/markup: Languages() = markdown, asciidoc; AsciiDoc leaves the process through OPENSYSML_ASCIIDOCTOR / scripts/asciidoc/asciidoctor-json.js	missing	MarkupParser with MarkdownParser, AsciiDocParser feeding DocumentPlanner (ProseBlocks item); pinned against markup.Languages(), For(), the exec.Command call and the converter script
Exporter, migrator, code generator	internal/translate/*	ok	ok
Conformance oracles	twelve modelled; tests/fmi gates the FMI integration over OPENSYSML_REQUIRE_REFERENCE_FMUS and scripts/download-reference-fmus.sh, CI sets the variable	missing (FMI gate)	ReferenceFmuGate — the thirteenth oracle; pinned against the test suite's constant, the script and the PR workflow
MCP conformance	make conformance-mcp is one of the conformance protocols	wrong — ConformanceSuite.protocols lacked mcp	corrected; pinned against the suite's knownProtocols
Pipeline stages, pass registry, tiers	internal/syntax, internal/semantic, internal/check/passes	ok (#1484 withdraws part-usage-part-definition; not modelled here)	ok
Engines (evaluator, compiled calcs, action/state executors, sweep/Monte Carlo, solver, analysis engines)	internal/exec/*	ok (SweepEngine covers internal/exec/sweep, pinned by analysis.Default())	ok
Identity, sync	internal/semantic/identity, reposync	ok	ok
FMI runtime	internal/exec/fmi	the gate is modelled (above); the engine is reached through analysis.Default()	ok
Airflow provider	not in this tree (grep -ri airflow finds nothing under cmd/, internal/, client/, editors/)	—	out of scope: nothing to model
Source tree allocations	tests/ directory held no allocation	wrong	tests directory added; every new part allocated

Model changes

• surfaces.sysml: McpServer, JupyterKernel, JsonCommand + SyntaxCommand/EngineCommand/CoreCommand/CombinedCommand, JupyterKernelPackage, JupyterLabExtension, VS Code extension attributes, MarkupParser + MarkdownParser/AsciiDocParser, DocumentPlanner.markupLanguages, ReferenceFmuGate, CommandLine report attributes, ConformanceSuite.protocols, and Toolchain counts, parts and connections.
• pipeline.sysml: item def ProseBlocks (what a markup parser hands the planner).
• quality.sysml: tests source directory; allocations of every new part.
• views.sysml: surfaceTable and markupParsers (forty views rendered, up from thirty-eight).
• document.sysml: SurfacesWithProtocols and MarkupLanguages queries, a documentPipeline root, the surfaces section's prose and a table of every surface with its command and protocol, a table of the markup languages.
• README.md: file table (eleven interfaces, thirteen oracles, forty views, the parsers and notebook packages), the "Keeping it honest" section names both test files.

Overlaps

Dry-merged this branch (head 0aa997f48, which merges origin/develop at 1c8e9e92f, 15ac97cff and 11c4699a9) against every open PR that touches examples/self-model/, the self-model tests, or a baseline / count line this PR re-recorded (gh pr list --json files + git ls-remote --heads origin):

• feat(docplan): headings in markup bodies open sections #1477 (feat/document-whole-bodies, head 2672d357c): conflicted in document.sysml at its earlier head d8223dcb2 (both add to the Documents and views section). Resolved by merging that head as a merge commit (c39b4b368); its current head, with its two review fixes (703e4ccaa, 2672d357c), is merged in as 4200838ed. Nothing of it was re-done.
• fix(check): withdraw part-usage-part-definition; a part usage's derived partDefinition is never empty #1484 (fix/part-usage-part-definition-reading) is merged (11c4699a9), and origin/develop at that commit is merged into this branch as 0aa997f48. The ten conflicts were resolved by regeneration, not by hand: develop's README.md, docs/internals/architecture.md, docs/project/{pilot,api-json}-differential{,-baseline}.* and the four .agents/skills/testing-pilot-*/SKILL.md were taken, then make docs-counts, pilot-diff -update, pilot-apijson-diff -update and pilot-reject -update ran on the merged tree; the skill headlines keep develop's wording with the merged figures. Movement against develop's files: pilot-diff — only examples/self-model/document.sysml, the same two pilot-only kind-mismatch rows as before (examples 61 → 63; 2448 → 2450 only-pilot, 3557 → 3559 pilot diagnostics; develop's own 521 agreeing / 359 only-ours / 1468 our diagnostics from fix(check): withdraw part-usage-part-definition; a part usage's derived partDefinition is never empty #1484 are untouched); pilot-apijson-diff — examples (26219 → 26974 matched, 5956 → 6046 ours-only, 14768 → 15056 pilot-only: the self-model's parts) and manual-examples (10 → 11 files, 7150 → 7191 matched: feat(docplan): headings in markup bodies open sections #1477's whole-document.sysml); pilot-reject — none (349 cases: 337 both reject, 12 only we reject). Against this branch's previous head ec1212375, the only other movement is develop's own (fix(check): withdraw part-usage-part-definition; a part usage's derived partDefinition is never empty #1484's −7 only-ours / +4 agreeing files; examples 26982 → 26974 matched, 15058 → 15056 pilot-only).
• feat(doc): read model values into Markdown and AsciiDoc prose (sysml:value) #1476 (feat/document-inline-values), fix(parser,runtime): satisfy by takes a feature chain; a satisfy stating no by reads its owner as the subject #1466 (fix/satisfy-by-expression), refactor: replace hand-rolled membership and index helpers with slices.* #1497 (refactor/slices-contains-helpers) and fix(export): check sysx:conjugatedTyping against the typing element only #1485 (fix/rdf-conjugated-port-subsetting) are merged; origin/develop at 1c8e9e92f (22 PRs past 76c98694c) is merged into this branch as 084410b4a. origin/develop at 15ac97cff is merged as ec1212375 for test(runtime): record the Box subitems a resolvable binding end lets the walk reach #1515 (7451b58e0), which re-recorded the Probe::box.subitems sweep row and instance_library_geometry_box.expected.json that fix(runtime): read a binding linking some value of each end as a constraint #1508's merge had left develop red on — the two shards the previous head's full tier failed; it touches no baseline or count file, so nothing was regenerated. Of its seven conflicts, README.md, docs/internals/architecture.md and docs/project/api-json-differential{,-baseline}.* were taken from develop and regenerated (make docs-counts, pilot-apijson-diff -update, below); docs/manual/authoring.md, docs/reference/diagnostics.md and mkdocs.yml keep both sides (feat(doc): read model values into Markdown and AsciiDoc prose (sysml:value) #1476's sysml:value prose, row and nav entry beside feat(docplan): headings in markup bodies open sections #1477's headings section, rows, markup-heading-level code and nav entry).
• feat(docplan): AsciiDoc-bodied prose in generated documents (rep language "asciidoc") #1454 is merged.

How it was verified

All from the repo root after make build, at head 0aa997f48:

Command	Result
./bin/sysml examples/self-model/*.sysml -validate	every package ✓, no errors
go test -count=1 ./examples/	ok (7.5s)
go test -race -count=1 ./examples/	ok (44.4s)
make self-model	40 views and the document rendered into build/self-model/ (38 views before this PR)
./bin/sysml examples/self-model/*.sysml -render-document OpenSysMLDocument::ArchitectureDocument -doc-form html -doc-toc -o build/self-model/architecture.html	written; the surface table (eleven rows), the markup-language table (two rows) and every table that was there before are filled
./scripts/download-doc-pdf-toolchain.sh then the README's PDF command (-doc-title-page -doc-toc -doc-number-sections)	36 pages (pdfinfo). The README said thirteen; the same command over origin/develop gives 34, so the figure was already stale — the README now says thirty-six
gofmt -l .	empty
go vet ./...	clean
go test -count=1 ./tests/hygiene/	ok — both self-model test files are under the 2,000-line cap
OPENSYSML_REQUIRE_TRAINING_CORPUS=1 OPENSYSML_REQUIRE_PILOT_CORPORA=1 OPENSYSML_REQUIRE_SPEC_EXAMPLES=1 go test -count=1 ./tests/corpus -run 'TestCorpusRoundTrip$|TestCorpusAPIJSONRoundTrip'	ok (51.5s) — no movement in the eight self-model rows of either expectation file
go run -C tools ./cmd/pilot-diff -check (examples/ is one of its roots, the self-model included)	before the develop merge it did not reproduce the committed baseline: the only movement was examples/self-model/document.sysml, two more pilot-only kind-mismatch warnings (examples 61 → 63, totals 2448 → 2450 only-pilot, 3557 → 3559 pilot diagnostics) on the two new tables' in redefines root = … lines — the same shape and warning as every table already there. Adjudicated as expected and re-recorded with -update; after the develop merge -check reproduces the baseline unchanged
go run -C tools ./cmd/pilot-apijson-diff -check	its provenance digest over examples/ covers the self-model, so it refused the committed baseline; re-recorded with -update after the develop merge. Against develop's baseline (168c882e4, #1476) the roots that move are examples (26227 → 26982 matched, 5956 → 6046 ours-only, 14770 → 15058 pilot-only — the new parts, attributes and ports of the self-model), manual-examples (10 → 11 files: docs/manual/examples/whole-document.sysml, merged in with #1477's head) and spec-examples by three property counts (76417 → 76419 present-equal, 1553 → 1552 present-different, 74026 → 74025 ours-missing) that develop's own changes since 168c882e4 left behind its baseline. The record's headline, launch-ready gap rows and per-root table follow the baseline (the per-root rows were stale on develop too — e.g. tests/testdata said 36 files / 1414 matched where develop's own baseline had 40 / 1460)
make docs-counts	the count lines it derives from those two baselines (README.md, docs/internals/architecture.md, docs/project/{pilot,api-json}-differential.md, four .agents/skills/*/SKILL.md headlines) were brought to the new figures; -check passes: "Documentation counts and refereed figures are current"

Baselines that read the self-model: tests/corpus/testdata/{api_json_roundtrip,corpus_roundtrip}_expected.txt list the eight files — TestCorpusRoundTrip and the API-JSON round trip re-run above with no movement. docs/project/api-json-differential-baseline.json and pilot-differential-baseline.json do not take examples/self-model as a root (tools/referee/diff/main.go, tools/referee/apijson), so nothing there moves.
The two edits to docs/internals/architecture.md are the generated corpus-agreement count line make docs-counts rewrites (2448 → 2450); its prose was not touched, see Follow-ups.

Follow-ups

The audit at 76c98694c found docs/internals/architecture.md stale on five points (three of nine cmd/ binaries, internal/frontend/ without mcp/jupyter/syntax/engine/core/combined, client/ with two of eight directories, no editors/ entry, no mention of the MCP server, Jupyter kernel, WebAssembly builds or the Markdown/AsciiDoc prose parsers). All five were fixed on develop by #1505 (f0733bae8, "docs(internals): list every binary, frontend, client and editor the tree has"), which this branch now carries; the only edits to that file here are the generated count lines make docs-counts rewrites.

Two automated review findings on #1477's planner code (nested heading paths as reference targets; punctuated explicit AsciiDoc ids) are addressed on this head: the first by 845e20e5c (markupOutline.sectionAt, TestCompileWholeDocumentNestedSectionPaths, a paragraph in docs/manual/authoring.md), the second by merging #1477's head 2672d357c, which fixes it.

Checklist

• make test and make lint pass locally (gates above)
• Tests added or updated for the change
• Documentation extended where it already covers the surface (examples/self-model/README.md)
• Changelog entry — none: the self-model is an example and the change is to it, its README and its tests
• baselines regenerated and make docs-counts run if a gate count moved — none moved
• No internal work-item labels in the body, docs, or changelog

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring