mycelium-cmbse/hypha
Hypha is the AI agent of the Mycelium ecosystem: a connecting filament between engineers and the SysML v2 specification. Provides skills and an MCP server for KerML/SysML v2 metamodel lookup, standard model library lookup, Systems Modeling API lookup, normative spec citation, and SysML v2 textual-notation validation.
Changelog
All notable changes to mycelium-hypha are documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
[Unreleased]
Changed
- The solution is
mycelium-hypha.slnx(fixes #280): the XML solution format replaces the classicmycelium-hypha.sln, andhyphanow recognises a source checkout by the.slnxfile. A clone made before this change is no longer taken for a source checkout by a newerhyphauntil it is updated.
[3.0.0] - 2026-11-15
This release starts hypha tools 2.0.0 (tools-v2.0.0), the first with serve. Checked before it: Claude
Code and VS Code with Copilot on Windows, and the launcher's first start, an install and a query on Windows,
Linux and macOS. The clients that could not be checked yet are listed in #259.
Added
- A First start workflow checks a published tools release on every platform (
refs #201): started by hand with a tools version, it makes the launcher's first start against that release on Windows x64, Linux x64 and arm64 and macOS on Apple silicon and Intel, as a client does: the download, the checksum, the handover tohypha serve, thenhypha_release_status, an install and a query. On macOS and Linux it starts the extensionlessbin/hypha-launch, so the POSIX script is checked too. - The VS Code extension builds for Windows on Arm, and is tested on every platform it builds
for (
refs #163,refs #165):win32-arm64is a package target; CI packages and smoke-tests the extension on Windows on Arm and on macOS (Apple silicon and Intel), each against VS Code stable and 1.101.0; and the Publish VS Code extension workflow can publish to Open VSX, through its Trusted Publishing, as well as to the Marketplace. None of these targets is published yet. - Configuration for other MCP clients (
refs #199):docs/other-clients.mdgives the server configuration and the skills folder for JetBrains Junie, Devin Desktop (formerly Windsurf), Zed and Cline, all starting the plugin's launcher from a clone of its release tag. Roo Code, which was discontinued, is left out. - A bundle for Claude Desktop (
refs #199): a plugin release now carrieshypha-<version>.mcpb, an MCP Bundle that Claude Desktop installs. One bundle serves Windows, macOS and Linux: it holds the plugin's launchers and dispatch script, so it downloadshyphaon its first start, as the plugin does. The Claude Desktop bundle workflow packs it when a plugin tag is pushed and attaches it when the release is published. Not yet tried in Claude Desktop. - Linux on Arm (
refs #200): the release publishes a self-containedhyphaforlinux-arm64, the launcher is built for it, andbin/hypha-launchstarts it on anaarch64Linux, the platform the VS Code extension already shipped for. - Manifests for Agent Plugins clients and Gemini CLI (
refs #199): a rootplugin.jsonandmcp.jsonin the Agent Plugins 1.0 format (GitHub Copilot, Cursor, Codex, Kiro) and agemini-extension.json, each starting the samebin/hypha-launchand sharingskills/with the Claude plugin. Not yet checked in those clients. - One source for every manifest (
refs #199):manifest.source.jsonholds the package's name, description, server command and its two versions, the package version and thehyphaversion the launcher downloads. Every manifest is rendered from it, and the tests fail when one drifts. - API versions through the MCP release tools (
refs #228):hypha_install_release,hypha_use_releaseandhypha_remove_releasetakeaxis: "api"to install, switch or remove a Systems Modeling API version, under the same release-operation lock as a release; an install without a tag installs the newest API version offered, and a version asked to be the default becomes it only once its knowledge is generated (the first one installed is the default from the start, as for a release). An API version installed before any release brings the UML primitives its PIM needs, which only a release install provided before. The server still has 17 tools. Theversion-managementskill installs API versions through them, where it gave plugin usershypha apicommands to run before. - The worked examples through the MCP server and the CLI (
refs #228):hypha_lookupandhypha lookuptakeexamplesas a kind, by an example's page name or its model's name (a name several examples share lists their pages),hypha_searchfinds examples by name or upstream path, andhypha://<tag>/examples/<page name>reads one whole. Thesysml-validationskill reads the examples thathypha_syntaxcross-referencenames, where it could only name them before. The textual-notation generator writestextual-notation/examples/index.jsonfor this (withknowledge/examples.schema.json). A release generated before, including one the migration copies intoHYPHA_HOME, reports its textual notation as not generated (hypha_release_status,hypha list), and reading an example names the command that generates it; installing the release again (hypha_install_release) adds the index. - The REST schema properties of the Systems Modeling API (
refs #228):hypha_apiwithquestion: "schema", andhypha query api schema --name <schema>, answer a schema of the REST/HTTP API as its OpenAPI document states it: each property's name, type, whether it is required or nullable and what an identifier refers to, and a union's variants. Theapi-lookupskill answers them, where it said before that it could not. hypha_check_releases, the upstream check in the MCP server (refs #197): compares the installed releases and Systems Modeling API versions with those offered upstream, and names a newer one when there is, so a newer release still reaches the user once the SessionStart hook is gone. It is read-only and open-world, the one read tool that asks GitHub.hypha checknow runs through the sameIReleaseCheck, with its JSON unchanged.hypha-launch, the MCP server's launcher (refs #198): the one command every client package starts,bin/hypha-launch, which the Claude plugin now registers as itshyphaMCP server. It finds the package from its own location, downloads and verifies thehyphathatbin/hypha-launch.jsonnames intoHYPHA_HOME/bin/once, and runshypha serveon the same standard input and output;HYPHA_BINnames ahyphato start instead. When there is none to start, it serves a minimal MCP server whose one tool,hypha_status, says why and how to fix it. A first start answers the client at once, downloads meanwhile and then hands the session over tohypha serve, so the client neither waits for the download nor reconnects; each download is renamed into place once verified, so two clients starting at once cannot clash. On Windows the extensionless path findsbin/hypha-launch.exe; on macOS and Linux it is a script that execs the platform's binary. The download of the CLI moved from the SessionStart hook into the launcher.- A one-time move of existing installs into
HYPHA_HOME(refs #196): the first timehyphareads an emptyHYPHA_HOME, it copies every release and API version the Claude plugin and the VS Code extension installed in their own folders, with their sources, so nothing is fetched or generated again. It copies rather than moves, holds the release-operation lock (and each client folder's own, so a release a client is installing is never copied half built), renames each copied folder into place and writes the manifests last, and records with.migrated-from-clientsthat it ran.hypha servecopies beside answering;hypha migrate [--from <folder>]copies on request. - The hypha MCP server:
hypha serve(refs #196), with the officialModelContextProtocolC# SDK over standard input and output, in a newHypha.Mcplibrary. Twelve read-only tools answer from the knowledge base:hypha_release_status,hypha_metaclass,hypha_feature,hypha_typed_by,hypha_package,hypha_syntax,hypha_spec,hypha_search,hypha_resolve,hypha_lookup,hypha_diffandhypha_api. Each groups related questions behind aquestionargument whose values are thehypha queryverb names, and returns the same JSON, grounding included. A question that cannot be answered is a tool error naming the fix. The server'sinstructionsexplain the grounding tiers and which tool answers what, for clients that load no skills. Standard output carries only the protocol; the log goes to standard error. - Specification search, resources and prompts in the MCP server (
refs #196):hypha_search_spec, andhypha query search-specification, find the KerML and SysML clauses whose text says a word or phrase, ignoring case and line breaks, the clauses that say it most first, each with its address and an excerpt (IKnowledgeQuery.SearchSpecification).- Every
hypha://{tag}/{kind}/{name}address is a resource whose contents are the page as Markdown. Every address in a JSON answer now carries itsuri, the text a client opens. - Five prompts:
overview,explain_metaclass,cite_specification,validate_notationandapi_lookup, each naming the tools to use and starting from what is installed.
- Release tools in the MCP server (
refs #196):hypha_install_release(fetch and generate, the newest offered release when no tag is given),hypha_use_releaseandhypha_remove_release, run in the server's own process. An install sends MCP progress notifications, one per file fetched and per artifact generated, in order, and answers with what each artifact did. The release becomes the default only once its knowledge is generated with no generator refusing, so a failed or cancelled install leaves the previous default answering. Each tool takes the release-operation lock, waiting up to ten minutes for another client's change, through a newIReleaseOperationsinHypha.Knowledge; the switch of the default moved intoIReleaseSelector, whichhypha usenow runs through too. - A query API in
Hypha.Knowledge(refs #194), namespaceHypha.Knowledge.Query: the structural questions the skills and the metamodel-navigator agent answer today withjq, answered in C# from the same generated JSON, so the CLI and the coming MCP server share one implementation.IKnowledgeQuery, for a language release: the installed releases and API versions, with which artifacts each has generated, subclasses (concrete or not), metaclasses with a feature typed by a type, a metaclass's full feature set with where each inherited feature comes from, redefinitions, an index entry, an element's cross-references, which elements' syntax fills in a feature, and a model-library declaration. For validating and citing, also: a metaclass's ancestors, whether one metaclass specializes another and through which supertypes, the OCL constraints and the operations that apply to a metaclass (its own and inherited, each naming where it is declared), an enumeration's literals, subsettings, the elements a grammar production builds, and the elements a specification clause treats (optionally with its subclauses).- Specification text:
Clausereturns a KerML, SysML or API clause with its verbatim text, grounded asNORMATIVE. The text needs the OMG PDFs, so when it was never generated the result is not an error butUnavailable, saying which commands generate it. Searchlooks a text up across the metaclasses, the standard-library declarations and the clauses (by number or title), ranked as the lookup resolves names: exact, ignoring case, trailing part of a qualified name, then contains. A clause title counts as a name, so the clauses titledFeaturerank with the metaclassFeature.HyphaAddressnames a generated page ashypha://{tag}/{kind}/{name}(kindsmetamodel,model-library,kerml,sysml2), andResolveturns an address into its page through the release's indexes, never a path given by the caller.- Structural queries (
fixes #209), modelled on what uml4net's extensions and reports ask of a metamodel, all reading facts the generator wrote:Containers: the composite features through which an element can be owned, typed by it or by one of its ancestors ("where can aPartUsagebe nested?").FeaturesAccepting: every feature that can hold a value of a type. Both list a feature once, where it is declared; with aclassName, only that metaclass's effective features, so a feature it redefines is left out.Neighbours: the metaclasses its own features are typed by, and the features of other metaclasses typed by it.Package: a package by qualified name or name (Metadatais two packages), with its metaclasses, its nested packages and every metaclass below it.EffectiveFeatures: owned features and the inherited ones no feature of the metaclass redefines.Opposite: the other end of a feature's association, and the feature that redefines it in the metaclass, when one does.FeatureConstraints: the constraints that name a feature among what they constrain; none does in the releases so far, since their constraints name their metaclass.Contributors: the features that subset or redefine a feature, directly or through another contributor, each saying which, such as the 82 that contribute toNamespace::ownedMember(EnumerationDefinition::enumeratedValueby redefiningDefinition::variant).
Diff(fixes #206): what changed in the metamodel between two installed releases, for every element or for one, by its name in either release. Metaclasses, enumerations and primitive types added, removed, renamed or moved; per metaclassisAbstract,visibilityandextends; and the attributes, operations, parameters, constraints and literals they own, added, removed, renamed or changed field by field. An element or member is matched on its XMI id, so a rename is one change, not a removal and an addition; when the ids differ it is matched on its name. Upstream regenerated every id between2025-04and2025-06, so across that gap a rename reads as a removal plus an addition. A rewritten documentation text is onedocumentationchange, without the texts. Inherited members are not compared. Each change is a fact; whether it breaks a model is left to the caller. Two documents of different schema versions are refused. For the elements found in both releases it also comparescross-references.jsonedge by edge: the clauses, grammar productions, features the syntax populates and worked examples, each added, removed or changed in its provenance, method or productions, with a renamed element compared under both names. That part isnullwhen either release has not generated its cross-references or the two have different schema versions; the metamodel diff is still returned. The comparisons areIMetamodelDifferandICrossReferenceDiffer, whichAddHyphaKnowledgeregisters andKnowledgeQuerytakes in its constructor.Keyword(fixes #205): what a keyword or operator such asref,individualor:>>does, read fromkeywords.json. One use per grammar that lists it (optionally only one grammar), with its kind, the productions that write it and the metaclasses whose syntax includes it, each written directly or through a helper, grounded asDERIVED. In SysML, the expression keywords and operators (and,istype,true,+) come from the KerML expressions SysML calls, andSyntaxFromsays so; a KerML declaration keyword such asclassifieris not SysML syntax, so asking SysML about it finds nothing.hypha query(refs #195): one verb per question ofIKnowledgeQueryandIApiQuery(hypha query subclasses --of Usage,hypha query keyword --word ':>>',hypha query api type --name Commit), each with--tag/-t(a release, or forapian API version) and--json. With--jsonit prints the whole result: the answer, its grounding (tier, release, source file) and, when an optional artifact was never generated, why. The results are written throughQueryJsonContext, a source-generated contract in camel case that the MCP server will reuse.hypha listnow reads the release inventory through the query API, andhypha lookupreads the metamodel and model-library indexes through the query API's typed contracts and document cache, so both read an index once while it is unchanged and both refuse one the generators could not have written (hypha lookup --jsonoutput is unchanged).IApiQuery, for a Systems Modeling API version: a PIM class, the cross-references of a type or a service operation, and a clause of the API specification.- Every result carries its grounding: the tier (
NORMATIVE,MODELorDERIVED), the release and the generated file it was read from, relative to the folder holdingknowledge/. A name the release does not have is a normal result, not an exception. - Each document is read once, through its source-generated contract, and read again when its
file changes, so a release regenerated by another process is not answered from stale memory.
The cache (
IDocumentCache) and the specification text reader (ISpecificationReader) are injected;AddHyphaKnowledgeregisters one of each, shared by both queries. Every read failure is aKnowledgeLookupException: a missing, unreadable (being rewritten), empty or malformed file, and one of the wrong shape, which the query contracts refuse instead of reading with members leftnull. - The release lookup, the query API and the API query choose a version and word their messages in one place, so the verbs those messages name are written once.
KnowledgeQueryJqTestschecks every answer against the documentedjqquery on the committed golden metamodel and small fixtures; CI runs them withHYPHA_REQUIRE_JQ, so they cannot be skipped there.MetamodelJsonContextnow carries the camel-case naming policy of the file format, sometamodel.jsonandindex.jsonread back through its default instance.IKnowledgeLayout.MetamodelGraphnamesmetamodel.json, andModelLibraryFile.ReadIfPresentreads the model-library index.SpecificationIndexis the shape of theindex.jsonthattools/spec-extractwrites, so the specification text is read through a contract as well.
- The VS Code extension is on the Visual Studio Marketplace (
refs #155), as a preview pre-release under themycelium-cmbsepublisher: version0.1.0for Linux x64 and arm64.- The Publish VS Code extension workflow (
.github/workflows/publish-vscode.yml), started by hand, packages each target and publishes it through Marketplace Trusted Publishing (vsce publish --oidc), so no Marketplace token is stored. A run waits for approval in thevscode-marketplaceenvironment, and refuses to publish unlesstools/matches thetools-v<cli-version>tag the bundled CLI is labelled with. - The extension has an icon, the Preview flag and a changelog of its own;
package.mjstakes--pre-release, andlinux-arm64is a package target.@vscode/vsceis 4.1.0, the first version with--oidc.
- The Publish VS Code extension workflow (
- The VS Code extension for Windows x64 (
fixes #157), validated end to end on Windows 11 and published with extension version0.1.1beside Linux x64 and arm64. CI now packages and smoke-tests the Windows VSIX too, against VS Code stable and against 1.100.0. - A release-operation lock in
Hypha.Knowledge(fixes #166), compatible with the VS Code extension's: the same.release-operation.lockfile in the repository root, the same{"pid", "token"}content and the same recovery rules, so an operation that changes releases on its own (such as the coming MCP install) and an extension install never run at the same time. The CLI's own verbs do not take it, because the extension runs them while it holds the lock. - Safe concurrent writers (
refs #195), for several MCP servers, the CLI and the VS Code extension working on one knowledge base at once.HyphaKnowledgeOptions.ReleaseLockWaitmakesIReleaseOperationLock.AcquireAsyncwait for a held lock instead of refusing it at once, including one held by another operation of the same process. The default, zero, keeps refusing at once, as the extension does; the lock protocol is unchanged. Between tries a waiter only reads the lock, and runs the protocol again once the lock is free or its owner is gone, so it does not keep the recovery file in place while it waits.- A lock or recovery file removed by the other side in the instant after creating it failed is
now reported as a held lock, not as a raw
IOException. - Both
versions.jsonmanifests and every generated knowledge file are written throughReaderSafeFile: to a temporary file beside it, then renamed over it, so a reader in another process sees the old file or the new one, never half of one.
- Progress for fetching and generating (
refs #195): oneKnowledgeProgressrecord (Operation,Step,Done,Total,Message), replacingFetchProgress, that both the CLI and the coming MCP server consume through anIProgress<KnowledgeProgress>.IReleaseInstallerreports each file of the metamodel, textual and, now, specification inputs;IApiInstaller.InstallAsynctakes a reporter too and reports each of its three or four documents.- The loop that runs every generator in
Ordermoved from the CLI into the library, asIKnowledgeBuilder<TGenerator>(KnowledgeBuilder), registered byAddHyphaKnowledgefor the release generators and the API generators. It reports each artifact as it finishes, written or skipped, counting within its release, and stops at a generator that refuses, naming it.hypha generate,hypha api generateandmove-windowrun through it. hypha fetch,hypha api fetch,hypha generateandhypha api generateshow a live progress display, one bar per step, when their output is a terminal, and nothing more when it is redirected, as for the VS Code extension. On a terminal the log is written above the bars, and the HTTP request and retry logging is held to warnings, as under--json, unless--log-level Debugor lower is asked for.
knowledge/<tag>/textual-notation/keywords.json(refs #205), written by a newkeywordsgenerator (hypha generate keywords), withknowledge/keywords.schema.json. Per grammar (kerml,sysml), every keyword and operator the release's own BNF writes, asreserved,contextualoroperator(plain punctuation left out), with the productions that write it and the metaclasses whose syntax includes it:partintroducesPartUsageandPartDefinitiondirectly, andrefreaches the 41 usages throughBasicUsagePrefix. A metaclass's syntax follows only bare calls, a reference that is not the value of an assignment, into productions that build nothing, the same metaclass or a supertype, so a selector handing over to a subtype and an assigned owned element do not count. A literal that is only ever an assigned value, such asprivate, or+in KerML, lists its productions and no metaclass. The SysML grammar calls six KerML productions without defining them (OwnedExpressionand four more expressions, andMetadataFeature), so thesysmltable also lists what they write, such asand,istype,trueor+, with KerML's productions andsyntaxFrom: "kerml"(schema 1.1.0); a literal SysML writes itself keeps its own entry. Only the clauses that define the called productions are followed, so KerML's declarations, which its expression bodies lead on to, do not count:truecomes fromBooleanValue, notInvariant.
Changed
-
Fewer GitHub API requests, and a warning before the anonymous limit runs out (
refs #224):- Listing a repository's tags stops at a page with fewer than 100, instead of asking for an empty page after it, which halves what a check or an install of the newest release asks.
hypha servekeeps the tags it read for ten minutes and each tag's commit for as long as it runs, so a check followed by an install, or installing a release again, asks no more.- A check now makes about three requests, installing the newest release about five (it was six and seven).
- When 20 or fewer of GitHub's 60 requests an hour without a token are left,
hypha_check_releasesandhypha_install_releasecarry anoticesaying how many, until when, and to setGITHUB_TOKEN. - A request refused because the limit is used up says so, with when it resets, rather than as an upstream that cannot be reached.
-
The server's instructions stand on their own (
refs #199): for a client without the skills, they now say what to do when nothing is installed, that a closure or a comparison is one call, what the model library does not resolve, how to check textual notation, what to give when the specification text is missing, and to confirm a removal, which cannot be undone. -
The metamodel and model-library skills answer through the MCP server (
refs #197):metamodel-lookupandmodel-library-lookupcall the server's tools by their bare names (hypha_metaclass,hypha_feature,hypha_typed_by,hypha_package,hypha_syntax,hypha_lookup,hypha_search, ...), with no jq and no file paths, so they work in any client that starts the server. A question about a set, a closure or a comparison of metaclasses is one tool call. A test checks that every tool a skill, agent or command names is one the server has, and every question and argument it names one that tool accepts. -
The specification-citation and validation skills answer through the MCP server (
refs #197):spec-citationreads clauses withhypha_spec, finds them withhypha_search_spec,hypha_searchandhypha_syntax, and names the governing clause, with its provenance, when the specification text was never generated.sysml-validationchecks keywords, productions and feature assignments withhypha_syntaxand reachability and multiplicities withhypha_metaclass, and names the release's worked examples of an element without reading them. -
The version-management skill installs, switches and removes releases through the MCP server (
refs #197):hypha_check_releases,hypha_install_release,hypha_use_releaseandhypha_remove_releasereplace thehyphacommands it ran with--repository-rootin the plugin's folder, so a release installed in one client answers in every other. -
The API skill answers through the MCP server (
refs #197):api-lookupreads PIM classes, how a PIM type lines up with its PSM schemas and the specification, service operations with their endpoints, and API specification clauses throughhypha_api, with no jq and no file paths. -
Installing the Claude plugin needs nothing else (
refs #197): no Git for Windows, no new session for a hook to run, and nojq. The plugin starts the MCP server through its launcher, which downloadshyphathe first time. -
A relative
HYPHA_HOMEis refused (refs #196): it would be resolved against each process's working directory, so two clients started from different folders would not share one home or one lock. The error names the value and asks for an absolute path. -
One knowledge location per user,
HYPHA_HOME(refs #195). Run outside a source checkout without--repository-root,hyphanow keepssources/andknowledge/in theHYPHA_HOMEfolder, by defaulthyphain the per-user application data folder (%LOCALAPPDATA%on Windows,$XDG_DATA_HOMEor~/.local/shareon Linux,~/Library/Application Supporton macOS), instead of failing to find a repository. In a source checkout nothing changes: the checkout above the working directory is still used, and--repository-rootand--outputstill win. A setHYPHA_HOMEwins over a checkout found only above thehyphaprogram itself.- The managed toolchain (
uv, its package cache and its Python) now lives intoolchain/in that folder unless--toolchain-cache-rootsays otherwise, rather thanuvinmycelium-hyphaand its cache and Python in uv's own per-user locations. The first specification extraction after updating downloadsuvand Python once more. HyphaKnowledgeOptions.Homesets the folder in code;HyphaHome.Resolveis the default.UvProvisioner's constructor without a cache root, andUvProvisioner.ResolveCacheRoot, are removed.- The VS Code extension passes its own folder, as before. The Claude plugin reads
HYPHA_HOME, through the MCP server its launcher starts.
- The managed toolchain (
-
metamodel.json2.1.0: every owned attribute, operation, parameter, constraint and enumeration literal carries itsxmiId(refs #206), so a diff between two releases recognizes a renamed member. Regenerate every installed release (hypha generate --tag <release>, andhypha api generate --tag <version>for an API version): a 2.0.0 document is refused with that advice. -
metamodel.json2.0.0: the generator writes the UML semantics, the query API reads them (fixes #208). uml4net already computed them; the query API had been working some of them out a second time. Regenerate every installed release (hypha generate --tag <release>, andhypha api generate --tag <version>for an API version): a 1.0.0 document is refused with that advice.redefinesandsubsetsname the feature's owner,{ "class", "association", "feature" }, instead of a bare name, which several metaclasses share (66 of the 140 redefinitions in a release named such a feature). An end an association owns hasassociationset instead ofclass.- New per attribute:
opposite(the other association end;nullwhen that end, or its association, has no name, as in the Systems Modeling API PIM),isDerivedUnion,isUnique,isReadOnlyanddefaultValue; per inherited attribute,redefinedBy, the feature that redefines it in that metaclass. - New per class:
inheritedOperationsandinheritedConstraints, as references to the declaring class's entry, each inherited operation withredefinedBy. Owned operations list what theyredefines, and constraints theirconstrainedElements. The file grows from about 8 MB to about 16 MB; copying every inherited operation and constraint in full would have made it 26 MB. ConstraintsandOperationsread the inherited members from the document instead of walking the ancestors.Operationsleaves out an inherited operation that the metaclass's context redefines, so it no longer lists two OCL bodies for one operation (such asnamingFeaturefor aConstraintUsage).RedefinitionsandSubsettingstake an optionalowner, aftertagso a call written for the previous signature still means the release, and their results name the owner of the redefined or subsetted feature.Featuresreturns the new facts.Specializesanswers from the generatedallAncestors(a metaclass conforms to itself) and returnsSpecializesas a field; the chain of generalizations stays as an explanation.- The metaclass pages link a redefined or subsetted feature to the page of the metaclass that owns it. A feature that redefines an inherited one of the same name used to link to itself.
- The skills' and the metamodel-navigator agent's
jqrecipes follow the new shape.
-
Hypha.MetamodelGenis nowHypha.Knowledge.Metamodel(fixes #193), the first step of the MCP refactor. Its test project isHypha.Knowledge.Metamodel.Tests, andAddHyphaMetamodelGenis nowAddHyphaMetamodel. Thetools/metamodel-gen/folder keeps its name, andHypha.Knowledgestays one library: reading and writing the knowledge are kept apart by namespace, not by project.- Every generated JSON document (the version manifests, cross-references, model library, the
Systems Modeling API documents,
metamodel.jsonandindex.json) is written through a source-generatedJsonSerializerContextbeside its types, instead of reflection, and the documents the tools read back as typed objects are read through it too.metamodel.jsonandindex.jsonare not read back as typed objects yet; that comes with the query API (#194). - The types
metamodel.jsonandindex.jsonare written in moved from the metamodel generator intoHypha.Knowledge(namespaceHypha.Knowledge.Metamodel), so code that reads them needs neither the generator nor uml4net. knowledge/metamodel.schema.jsondescribesmetamodel.json, which until now was the one generated JSON document without a committed schema.MetamodelSchemaTestschecks the produced document against it.- The file formats are unchanged: every generated document is written byte for byte as before.
- Every generated JSON document (the version manifests, cross-references, model library, the
Systems Modeling API documents,
-
Hypha.Toolson nuget.org has a proper package page (fixes #160): a package readme, the Mycelium icon, project and repository URLs, copyright, release notes that link to thetools-v<version>GitHub release, and a description and tags that cover the Systems Modeling API,lookupand the JSON output. The repository README adds the command-line install from NuGet. -
CI and the publish workflow install the extension's dependencies with
npm ci --ignore-scripts, so no dependency install script runs in a job that can publish. -
CI runs once per pull-request commit (
fixes #173): Build & Test & SonarQube runs on pull requests and on pushes todevelopmentandmainonly (and by hand), instead of on every push as well, which ran everything twice. Every action the workflows use is updated to its current major version, pinned to a release at least two weeks old, and the .NET tools the workflows install (dotnet-sonarscanner,dotnet-coverage,nuget-license) are pinned. Dependabot now proposes weekly updates for the workflows' actions, the NuGet packages, the extension's npm packages andtools/spec-extract, grouped per ecosystem and only for versions two weeks old.
Removed
- The
Hypha.Tools.Hookproject (refs #200): the retiredSessionStarthook's source and tests, which only shared the launcher's download code. The workflow that builds the launcher binaries is nowlauncher-binaries.yml(Launcher binaries), renamed fromhook-binaries.yml. - The
metamodel-navigator,spec-citationandsysml-validatoragents (refs #197): their fan-out questions are single tool calls now.metamodel-lookupsays which, andspec-citationandsysml-validationtake over the other two, including a whole model to check. - The plugin's
SessionStarthook (refs #197):hooks/native/, the hook entry andhyphaCliVersionin.claude-plugin/plugin.json, and the hook's build in the binaries workflow, which now builds only the launcher. Asking about releases runshypha_check_releasesinstead, and installing one reports when the specification text was skipped. jq(refs #197): no skill runs it any more, and the README no longer recommends it.
Fixed
- The first specification search in a fresh release is fast (
refs #224):hypha_search_spectook 18 to 33 seconds on its first call after an install, because it opened the release's 1,500 or so clause pages one after the other, and the virus scanner checks each newly written file the first time it is opened. The search now reads eight pages at a time: on Windows the first search takes under two seconds and the next ones under one. - A release the migration left out is named, and why (
refs #224): a release or API version an earlier client had installed in an older format is not copied intoHYPHA_HOME, and was reported only as a warning on standard error, which a client may never show, sohypha_release_statussaid nothing was installed without saying why. The migration now records each one with its reason in.migration-left-out.json, andhypha_release_status(leftOut),hypha listandhypha migratename it until it is installed again. - A refusal is no longer logged as a failure (
refs #224): a tool that refuses, such as removing the default release or asking about a release that is not installed, sent the client a proper message but was logged as[ERR] "<tool>" threw an unhandled exception. The server now answers it as a tool error itself and logs it at information level. A failure, a knowledge file that cannot be read or an upstream that cannot be reached, is answered the same way but logged as a warning with its exception; a protocol error and any other exception are reported by the SDK as before. - A project folder no longer captures the hypha server (
refs #224):hypha serveused to answer from, and install releases into, any folder above its working directory that held bothsources/andknowledge/, and an AI client usually starts it in the user's project. It now ignores its working directory and usesHYPHA_HOME, the folder every client shares, unless given--repository-root. The other verbs still use a source checkout above the working directory, but only a real one: a folder that also holdsmycelium-hypha.sln. - An install through
hypha serveno longer hangs at the specification text (refs #237): the processeshyphastarts (uv, and the Python it runs) inherited its standard input, which underhypha serveis the pipe the MCP client writes to, and on Windows the extractor's build never started, holding the release lock. Each child now gets an input of its own, closed at once. - The specification text is generated in
HYPHA_HOMEtoo (refs #237): the specification generators ran the Python extractor fromtools/spec-extractunder the knowledge folder, which only a source checkout or a plugin's own folder has, so an install through the MCP server, or adotnet toolinstall, skipped the specification text.hyphanow carries the extractor and unpacks it intotoolchain/spec-extract/, next touv, keeping it in step with the copy it carries; a source checkout still runs its own. hypha servekeeps the MCP SDK's per-request log lines off standard error (refs #224): they are held to warnings and errors, as the HTTP request lines already were, so a client that never reads standard error cannot fill it.--log-level Debugstill shows them.- The model-library resource says how far it reaches (
refs #224): its description says a declaration's page is up to 160 lines of its package's source from the declaration on, and thathypha_lookupreads further, so a declaration longer than that is not taken for a whole one. - A prompt called without its argument names the argument (
refs #224), rather than the SDK's generic "An error occurred.". - The migration into
HYPHA_HOMEleaves out a release generated in an older format (refs #224): a release or API version whose generated documents state an older schema version than thishyphareads is not copied, with a warning, so it is installed again rather than read wrongly. - A relative
HYPHA_HOMEis refused before any work (refs #224), also with--repository-root, rather than once a generation first needs the toolchain kept there. Giving--toolchain-cache-rootas well leavesHYPHA_HOMEunused, and unchecked. - The launcher refuses a relative
HYPHA_BIN(refs #224): it would be resolved against the folder each client starts the server in. The model is told why, throughhypha_status. - Installing into a folder that is not a source checkout generates the metamodel
(
refs #196):sources/PrimitiveTypes.xmi, the OMG UML primitives every release's metamodel refers to, is committed in a checkout but was nowhere else, so an install intoHYPHA_HOMEfailed at the metamodel.Hypha.Knowledgenow carries the file and the installer writes it when it is missing. - The repository README no longer says spec citation needs a source checkout: since the uv-based
specification generation,
hypha generatebuilds the text itself. - The extension's installed-VSIX smoke test finds VS Code's
cli.json Windows from 1.145 on, which keeps it under a folder named after the build's commit; it now asks the installation's own launcher (bin/code.cmd) for the path, and looks in both known layouts when it cannot.
[2.3.0] - 2026-11-07
Added
- The Systems Modeling API & Services is part of the knowledge base (
fixes #146), as a body of knowledge with a version of its own beside the language releases:- the PIM: every type of the Platform Independent Model, in the shape of the metamodel pages
(attributes with multiplicity, derivation, subsetting and redefinition, the full effective
attribute set, and the six services with their operations). The
Datainterface and theUUID,IRIandISO8601DateTimedata types get pages too. - the REST/HTTP PSM: one page per API schema of the OpenAPI document, with required and nullable members and whether the endpoints use it as a request or a response model, plus every endpoint.
- the API specification text, clause by clause, quotable through spec citation on the same terms as the KerML and SysML texts (generated locally from the PDF, never committed).
cross-references.json: PIM type ↔ specification clause ↔ PSM schema, the PIM members a PSM model leaves out, the PSM-only members, and the endpoint each PIM service operation maps to. Every edge names the method that produced it.- a new
api-lookupskill, and thespec-citationandversion-managementskills now cover the API.
- the PIM: every type of the Platform Independent Model, in the shape of the metamodel pages
(attributes with multiplicity, derivation, subsetting and redefinition, the full effective
attribute set, and the six services with their operations). The
hypha api discover | fetch | generate | list | use | removeinstall and manage an API version independently of the language releases, insources/api/<version>/andknowledge/api/<version>/with a manifest of its own (knowledge/api/versions.json). An API version is a tag ofSystems-Modeling/SysML-v2-API-Servicesthat is also a language release,2025-02or later. The PIM model is the one input no repository carries; it is fetched from the OMG document server (ptc/25-02-29).hypha api list --jsonreports every installed API version, the default, and which of its artifacts (PIM, OpenAPI, cross-references, specification text) have been generated, in the same shape ashypha list --jsonwithversionsin place ofreleases.python -m spec_extract --api-version <version>extracts the API specification.hypha lookupresolves a metamodel or model-library name in an installed release and prints one page of its generated file (fixes #153). A name resolves exactly first, then ignoring case, then by a trailing part of its qualified name (RealforScalarValues::Real); names that only contain the request are offered as candidates, never picked. A model-library lookup starts at the declaration rather than at the top of its package page. Hosts such as an editor extension use it instead of reading the generated indexes themselves.hypha list --jsonreports every installed release, the default, and which of its artifacts (metamodel, textual notation, model library, cross-references, specification text) have been generated.--toolchain-cache-rootkeeps theuvexecutable, uv's package cache and the Python it installs under one folder.- A VS Code extension for GitHub Copilot (
extensions/vscode/,fixes #151), a preview that is not yet on the Marketplace. A platform-specific VSIX bundles a self-containedhyphaCLI, so nothing has to be installed by hand: on first use the CLI downloadsuv, which provides the Python that specification extraction needs.- Commands: Show Installed Releases, Check Available Releases, Install a SysML v2 Release, Change Default Release and Remove a Release. Installing asks for consent first, reports progress and can be cancelled; a release becomes the default only once it has been generated.
- Copilot tools:
#hyphaReleaseStatusreports the installed releases and which of their artifacts are present;#hyphaLookupresolves a metamodel or model-library name throughhypha lookupand answers with a release-qualified source link, the candidates when a name is ambiguous, and one page at a time. - Releases, generated knowledge and the toolchain live in the extension's global storage, shared by every workspace on the same host. A lock file in that storage keeps two VS Code windows from changing releases at the same time.
- Specification PDFs and extracted text are never packaged; they are downloaded and generated locally. End-to-end validation has been done on Linux/WSL; the Windows and macOS packages build but are not yet validated end to end.
HYPHA_CLI_VERSIONsets the version the bundled CLI reports, so a VSIX built for publication names the hypha tools release it carries; any other build reports0.0.0-dev.
Changed
- The
SessionStarthook now provisions hypha tools1.5.0(hyphaCliVersion), which carries the CLI changes in this release. - Every
--jsondocument (check,list,lookup,api list) is one line on standard output with no banner; log lines go to standard error, and every failure (including one before the verb runs, such as cancellation or an unreachable upstream) is written as{"error": "..."}. - Bumped
uml4net(uml4net.xmi,uml4net.Extensions,uml4net.Reporting) to9.2.0, which providesQueryConstraintBodyandQueryBodyConditionTextitself. The generators now use those and hypha's own copies inModelQueryExtensionsare gone (fixes #145); the generated knowledge is byte-identical.
Fixed
uvis found in a wrapped archive. The Linux and macOSuvarchives keep the executable in auv-<target>/folder, which the provisioner did not look in, so specification generation could not start there. Both the flat and the wrapped layout are now found, and an archive without the executable is no longer marked as verified.hypha removerefuses a tag that is not a release, whateverknowledge/versions.jsonlists. The tag names a folder that is deleted recursively, andknowledge/api/now sits beside the release folders, so a hand-edited manifest listingapicould otherwise remove every installed API version.- The metamodel knowledge base now carries each operation's body OCL (
fixes #143). An operation'sbodyConditionis a constraint the operation owns, not one of its class's rules, so the class-level constraint walk never reached it and every derivation body was dropped. Eachmetamodel.jsonoperation now has abody(the OCL of itsbodyCondition, empty when it has none) and itsdocumentation, and element pages gain an Operations section with each operation's signature, documentation and body. On release2026-05all 99 body conditions come through, on the 39 metaclasses that own operations.
[2.2.0] - 2026-10-05
Changed
- The
SessionStarthook now provisions hypha tools1.4.0(hyphaCliVersion), which carries the uml4net upgrade below. - Bumped
uml4net(uml4net.xmi,uml4net.Extensions,uml4net.Reporting) to9.1.0(tools1.4.0). Optional[0..1]enumeration properties are now nullable, so an unsetvisibilityreads aspublic, the UML 2.5.1 default for aPackageableElement, and the generated metamodel keeps its exact shape. The only change to generated knowledge is in documentation text: every owned comment of an element is now used (8.x dropped all but one), and words on adjacent source lines are kept apart (e.g.Elements. Noteinstead ofElements.Note), which also changes threeindexsummaries. Grammar references, textual notation, model library and cross-references are byte-identical. ModelInspectornow selects interesting classifiers; the metaclass golden fixtures take its classes, so that set moved (8 metaclasses added, 6 orphaned golden files removed).
[2.1.2] - 2026-09-07
Fixed
- The
SessionStarthook no longer throws a raw PowerShell parse error on Windows without Git Bash (fixes #139). Its dispatch shim is POSIX-shell-only (case/esac,uname), and Claude Code falls back to PowerShell for shell-form hooks when Git Bash isn't found, which can't parse it. The hook now pins"shell": "bash", so Claude Code either runs it under Git Bash or reports a clear, dedicated "shell not found" error instead. That makes the project's existing Git Bash dependency explicit rather than reimplementing the OS/arch dispatch in a second language. No behavior change on Linux/macOS/Windows-with-Git-Bash, where bash was already the default.
[2.1.1] - 2026-09-06
Fixed
/overviewno longer tells users to manually download the OMG spec PDFs or manually runtools/spec-extract(fixes #135). Both are automatic now (hypha fetch/hypha generate'sspecartifact, #129); the command's own instructions had gone stale.
[2.1.0] - 2026-09-06
Added
hypha generate's newspecartifact quotes verbatim OMG spec text without a maintainer source checkout (fixes #129, tools1.3.0).SpecGeneratorfetches and cachesuv, which resolves or fetches a matching Python itself and runstools/spec-extract(Python/pdfplumber) through it, with no pre-existing Python or provisioned.venvneeded. A C# port of the pipeline was evaluated first (the PdfPig comparison spike, #128) and rejected: even after fixing a real bug, it still fell short of the mature Python pipeline's quality, and a port can at best tie Python, never beat it.tools/spec-extractalso gained a real CLI entry point (python -m spec_extract) alongside its existing pytest-driven maintainer flow.
[2.0.0] - 2026-09-04
Removed
- The committed knowledge floor (
fixes #106).knowledge/2026-04/,knowledge/2026-05/,sources/2026-04/,sources/2026-05/andknowledge/versions.jsonare no longer committed to git (2,120 files). Part 1 (hypha use/remove/check, below) landed the interactive mechanics while this floor still existed, so they could be verified before anything was deleted; this closes #106 by deleting it. A plugin install now fetches and generates every release identically, entirely on the user's own machine, on request, rather than two privileged releases pre-installed and everything else second-class.
Changed
.gitignore,CLAUDE.md,README.md,sources/README.mdandknowledge/README.mdrewritten for the no-committed-floor model (fixes #106):/sources/*/and/knowledge/*/are now root-anchored git-ignore patterns covering everything per-release, not just the OMG PDFs and their extracted text.Hypha.MetamodelGen.Testsreads a committed test fixture instead ofsources/<tag>/xmi/(fixes #106): one real release's XMI is committed undertools/metamodel-gen/Hypha.MetamodelGen.Tests/Fixtures/xmi/, a fixture for this test project alone (tools/is never shipped with the plugin), so the generators still have real regression coverage without a network fetch or a reintroduced distributed knowledge floor. The accepted consequence: only that one fixture release is exercised, not every installed release, since nothing per-release is committed to loop over any more.KnowledgeRegenerationTests,MetamodelJsonGoldenTests,MetamodelJsonInvariantTestsandPackageDiagramGoldenTestsredesigned (fixes #106): with no committedknowledge/<tag>/left to diff against,KnowledgeRegenerationTestsnow fetches one release fresh and asserts two independent regenerations are byte-identical to each other (self-consistency, not a match against a human-reviewed baseline; a real reduction in rigor, named as such in its own doc comment); the metamodel-gen golden tests moved to the same committed-Expected/-fixture patternMetaclassFileGoldenTestsalready used.hypha move-window(refs #106) is now documented and commented as the maintainer-only, source-checkout-only convenience it always functionally was, not a way to move a committed rolling window: its--keepcount only ever governed which releases stay installed locally.
Added
hypha use,hypha removeandhypha check(refs #106) replacehypha sync: switching the default release, removing one no longer wanted, and comparing installed releases against what is offerable upstream are now separate, always-safe-to-run verbs instead of one verb that silently fetched and generated the newest release automatically.- The
version-managementskill gives Claude the vocabulary to list local vs. online releases, fetch a chosen tag with visible progress, switch the default, or remove one, always confirming with the user first, since fetching costs real time and removing is destructive. hypha fetchdownloads the OMG specification PDFs by default now (--no-specsto opt out): a fully local install needs everything a plain HTTP call can get it.
- The
Changed
- The plugin's
SessionStarthook only ever compares now; it never fetches or generates anything itself (refs #106).Hypha.Tools.Hookrunshypha check --jsonsynchronously (a couple of GitHub API calls, cheap enough that no background process is needed) and reports what it finds: nothing installed yet, a newer release available, or nothing to report, leaving the decision to fetch entirely to the user. The same hook also folds in whathooks/check-spec-pdfs.pyused to do separately (naming missing OMG PDFs for the default release), so the plugin needs oneSessionStarthook instead of two, and no longer depends on Python being present just to run it. - The
SessionStarthook now also runs onresume, not onlystartup(refs #117). A resumed session (claude --resume/--continue) used to skip the check entirely;plugin.json's matcher is nowstartup|resume, so a long-running or resumed session still gets a fresh comparison against what's offerable upstream.
Removed
hypha syncand the background/lock/status-file machinery it needed (refs #106). Detached launching, a file lock, and a polled status file existed only because a hook-triggered fetch had to return immediately and report progress later; once fetching is something the user asks for and Claude runs in the foreground, none of that indirection is needed.hooks/check-spec-pdfs.pyis retired, folded intoHypha.Tools.Hook.
Added
hypha, a distributable command-line tool, is now what generates the knowledge base (fixes #81). It ships as adotnet toolfor anyone with the .NET 10 SDK and as a self-contained executable per platform (win-x64,linux-x64,osx-x64,osx-arm64) for anyone with no toolchain at all, which is the answer #77 needed to the question of what happens when the toolchains are absent. NativeAOT is deliberately out of scope: Handlebars.Net compiles templates at runtime through expression trees, and uml4net is reflection-heavy over XMI.- Four verbs:
discover(what the upstreams offer),fetch(download a release intosources/and record it),generate(the knowledge base) andlist(what this checkout carries). generatetakes an optional artifact name, and the names are not a list it holds: they are theArtifactof whateverIKnowledgeGeneratorimplementations are registered, so adding a generator adds its verb andgenerate nonsensereports the ones that exist.ReleaseInstallergives fetching the orchestration generation already had: it downloads a release's inputs, resolves both upstream commits and merges the result intoversions.json. The manifest is written only once the downloads finish, so an interrupted fetch leaves a release unrecorded rather than recorded and half-present.- A Release workflow packs the tool, publishes the four self-contained builds, generates
THIRD-PARTY-NOTICES.txtfor the bundled closure and drafts atools-vX.Y.Zrelease. The tool and the plugin version independently.
- Four verbs:
Changed
- The tests no longer write the knowledge base; they verify it (
fixes #81). Runningdotnet testused to rewriteknowledge/, which made every test run a write to the repository and made "is the working tree clean afterwards?" a check you had to remember to perform. Generation ishypha generate's job now, and a test run leaves the working tree clean.KnowledgeRegenerationTestsregenerates the whole knowledge base into a scratch folder and compares it byte for byte against the committed files: the same determinism proof, without touching a tracked file. All 1,090 files match.- The seam is
HyphaKnowledgeOptions.OutputRoot(the CLI's--output): inputs are still read from the repository, only the output moves.knowledge/<tag>/spec/stays on the input side, because the Python PDF chain writes it and the cross-references read it. Hypha.Knowledge.Testswent from 30s to 3s, having stopped doing the generation work twice.
- Generation orchestration moved out of the test fixtures and into the library (
refs #92). Each artifact is now anIKnowledgeGenerator(Artifact,Order,GenerateAsync(tag)), registered as a collection, so regenerating a release is a loop overOrderrather than a list of calls each caller had to keep in step. The knowledge base comes out byte-identical.KnowledgeLayoutreplaced three separate copies of the repository layout that had grown up in the test projects, one per project plus a private one inside a fixture.- Two fixtures now write the committed knowledge base instead of seven; the rest assert on scratch output, so changing one of them can no longer rewrite what ships.
- Three invariants moved from assertions in tests into the generators, where they hold for every caller: a clause title must never reach the cross-references, two models must never slugify to the same example page, and the textual notation refuses to run before the metamodel index exists.
HyphaKnowledgeOptionsreplaces the optional parameters that were accumulating onAddHyphaKnowledge(token, API host, raw-content host, repository root, download concurrency), and is validated at registration rather than at first use. It is where the CLI's flags will land.- Every generator takes an
ILoggerand reports the same three messages, so a host can show progress without knowing which generator it is watching. That is the seam #77 needs. ReleaseDiscovery,CommitResolverandReleaseFetcherare resolved by interface like everything else.
Fixed
- The cross-references no longer degrade silently on a new release tag (
fixes #96). The PDF-free rebuild added in #88 carries title-matched clause edges forward from the committed document, which is lossless, except for a tag that has neither a clause catalog nor a previous document, where it wrote a file with roughly a third of its clause edges missing and nothing failing.Buildnow refuses that combination and names both ways out;AllowGrammarOnlystates that a grammar-only document is intended.
Changed
- The cross-references moved to .NET, and no longer need the OMG PDFs (
fixes #88).Hypha.Knowledge.CrossReferenceswritesknowledge/<tag>/cross-references.jsonbyte-identically to the Python it replaces, and this completes the port (fixes #82): .NET now produces every committed artifact.cross-references.jsoncan be rebuilt from committed sources alone. 351 of its 546 clause edges are stated outright by the grammar's own// Clausecomments in the committed.kebnf; the remaining title-matched ones are carried forward from the committed document, which already holds them. A contributor without the specifications regenerates the file and gets the same bytes back; previously they could not regenerate it at all.- The licensing guarantee is unchanged and still tested: edges record clause identifiers,
never clause text, which is what lets this file be committed while
knowledge/<tag>/spec/cannot be. tools/spec-extractis now the PDF chain and nothing else, and its README says so.
- The textual-notation knowledge base moved to .NET (
fixes #87).Hypha.Knowledge.TextualNotationnow writesknowledge/<tag>/textual-notation/: 309 example pages per release plus the index. All 618 committed example pages come out byte-identical; the only change is the line naming the generator inindex.md.- Surface forms are still derived from the metamodel's own naming convention rather than curated
(
PartDefinition→part def,PartUsage→part), and still bounded by that release's metamodel index, so the mapping cannot invent an element. - The declaration match still refuses to fire inside an identifier or a quoted name:
counterpartis not apart. Unlike the grammar patterns this one is deliberately left Unicode-aware, matching the Python it replaces: model text is user-written. - Example pages are ordered segment by segment and case-insensitively, which is what the committed index was generated with; an ordinal sort of the whole path would interleave folders with files.
- Surface forms are still derived from the metamodel's own naming convention rather than curated
(
- BNF parsing and the grammar references moved to .NET (
fixes #86).Hypha.Knowledge.Grammarnow parses both the textual.kebnfand the graphical.kgbnfand writesknowledge/<tag>/textual-notation/grammar-{kerml,sysml,graphical}.md. The generated files are byte-identical to what the Python emitted, apart from the line naming the generator.- The porting hazards are guarded by tests rather than left to be rediscovered:
\dand\ware written out as explicit ASCII classes, because Python compiled these patterns withre.ASCIIwhile .NET's shorthands are Unicode-aware; and the possessive quantifier on the clause number becomes an atomic group, which .NET does have. - The exclusivity guard is unchanged and still the point: a helper production shared by two elements contributes to neither. 96 of the 190 referenced helpers are shared, so relaxing it would report more feature assignments and mean less.
- The porting hazards are guarded by tests rather than left to be rediscovered:
- Release handling moved from Python to .NET (
fixes #83,fixes #84,fixes #85), into the newtools/knowledge-gen/Hypha.Knowledgelibrary.spec_extract.versionsandspec_extract.fetchare gone;spec-extractnow does what it is best at (PDF extraction) and nothing else.ReleaseTag,ReleaseCatalog,GitHubTokenandReleaseDiscoveryoffer the same 56 releases in the same order as the Python they replace;VersionManifestrewrites the committedknowledge/versions.jsonbyte for byte.ReleaseInputsdecides what a release consists of as a pure function of a repository listing, so the selection rules are testable without the network;ReleaseFetcherdownloads it.- Fetching is concurrent (6 at a time) over a pooled
HttpClient. The Python fetcher opened a connection per file and was reset by the host after roughly 190 of a release's 314 files; a release now fetches whole in about 15 seconds.
- Well-established NuGet packages are now welcome rather than avoided, and services are composed
through
Microsoft.Extensions.DependencyInjection.AddHyphaKnowledge()registers one resilient named client (Microsoft.Extensions.Http.Resilience, so retries are jittered, which matters once downloads run concurrently) and the services that share it. This is groundwork for the CLI (#81).
Added
- Version awareness (
fixes #67,fixes #74). The knowledge base is now generated per upstream release tag (YYYY-MM) instead of from a single snapshot, with a committed rolling window of the two most recent releases, currently2026-05(the default) and2026-04.knowledge/versions.jsonrecords the installed tags, the default, and the upstream commit each tag resolved to (traceability only; the tag is the identifier).- Release discovery offers a version only when the tag resolves in both upstreams: they are not
in lockstep (
2023-07.1is Release-only;2024-08,2023-01,2026-05-preare Pilot-only). Tags areYYYY-MMwith an optional point release; pre-releases, internal drops and letter revisions are excluded. 56 releases are currently offerable. - Fetching pulls a release's inputs from both upstreams, retrying transient connection resets with backoff and resuming a partial run.
- Skills and subagents resolve the release from the manifest, answer from the default unless a tag is named, and state which release an answer came from.
hooks/check-spec-pdfs.pychecks the default release and gives tagged download URLs.
Fixed
- The previous inputs were not a coherent version: the PDFs resolved to Release tag
2026-03, the textual sources to2026-04, and the metamodel XMI to an untaggedmastercommit. Each release now comes from a single upstream point. XmiModelReaderTestswas silently skipping on a stalesources/xmipath; it runs again..gitignoregained a global*.pdfbackstop. Moving the specs rule to the per-tag form stopped it matching a stale copy of the old layout, and three copyrighted OMG PDFs were very nearly committed.
Changed
sources/andknowledge/are laid out per tag:sources/<tag>/{xmi,textual,specs}andknowledge/<tag>/{metamodel,spec,cross-references.json}.knowledge/textual-notation/stays shared (hand-curated), andsources/PrimitiveTypes.xmiis shared: it is the OMG UML primitives library, published by neither upstream and identical for every release.- The model URI inside the XMI (
…/SysML/20250201) is no longer used anywhere as a version identifier. It tracks neither release nor content: the 2026-05 metamodel still declares a 2025 URI. The same model may appear under several tags, which is accepted rather than deduplicated.
Added
knowledge/cross-references.json(+ schema): edges from every metamodel element to the specification clauses that treat it, its BNF grammar production and any worked example. It records clause identifiers only, never clause text, so it ships even thoughknowledge/spec/cannot; 185 of 187 elements resolve to at least one clause. Generated by the newspec_extract.crossrefslayer (fixes #68).- Provenance tiers (
NORMATIVE/MODEL/DERIVED) documented in the skills and the README, and carried in the data itself via theprovenanceTiersblock, so every cross-reference edge says how it was obtained. knowledge/metamodel/diagrams/<Package>.md: a Mermaid class diagram per package (41 files), generated from the XMI by the newPackageDiagramGeneratorand linked from each package section ofknowledge/metamodel/index.md. Each diagram carries the package's metaclasses (abstract ones marked), their generalizations, one-hop boundary nodes for supertypes owned elsewhere, and the structural owned features (fixes #69).- Two rules keep those diagrams legible: derived features are omitted (computed views rather than
structure, and they outnumber the structural features roughly three to one), and only
metaclass-typed features become edges; primitive- and enumeration-typed ones are drawn inside the
class box, so
StringandBooleannever become hub nodes.
Fixed
- Packages that share a name across the two metamodels (
KerML::Kernel::MetadataandSysML::Systems::Metadata) are merged into one diagram. Treating them separately wrote two files to the same path, silently discarding one of them.
Changed
metamodel-lookupand themetamodel-navigatorsubagent now queryknowledge/metamodel/metamodel.jsonfor set, closure and fan-out questions instead of grepping the per-element markdown, which stays the citable surface for single-element answers. Matching a JSON field is also exact, where grepping markdown matches documentation prose too.spec-citationdegrades gracefully: without the OMG PDFs it now names the governing clause from the cross-references instead of refusing to answer, and says the reference isDERIVED.sysml-validationgrounds its reachability and multiplicity-bound checks inmetamodel.json(inheritedAttributes/inheritedFrom, and the typedlower/upperintegers) rather than reasoning from prose; thebad-multiplicityandredefines-nonexistentfixtures record how each is decided.jqis now described as recommended rather than merely an accelerator, and the recommendation moved into the plugin-facing README; the previous note lived intools/metamodel-gen/README.md, which is not shipped with the plugin.
[1.1.0] - 2026-07-01
Changed
- Bumped
uml4net(uml4net.xmi,uml4net.Extensions,uml4net.Reporting)8.1.2→8.2.1, which reads the previously-missing subsetting information from the XMI. Regenerated the metamodel knowledge base accordingly (knowledge/metamodel/): several element files andmetamodel.jsonnow carry the completeSubsetssets (fixes #62). - Interesting-metaclass selection (used for the generator golden fixtures) now folds in operation
argument/return-type variations, broadening test coverage (
fixes #63).
[1.0.0] - 2026-06-29
Added
- Initial Claude plugin scaffolding (
.claude-plugin/plugin.json, marketplace manifest). - Skills:
metamodel-lookup,spec-citation,sysml-validation. - Subagents:
metamodel-navigator,spec-citation,sysml-validator. - Knowledge-base layout (
knowledge/) for KerML/SysML v2 metamodel elements, normative spec excerpts, and textual-notation examples. - Source-document layout (
sources/) for OMG XMI and PDF specifications. - Generation pipelines layout (
tools/): C#/uml4net metamodel generator and Python PDF spec extractor.
Changed
- Renamed the metamodel knowledge folder
knowledge/sysml2/→knowledge/metamodel/(consistent content-type naming alongsidespec/andtextual-notation/, and no longer overloaded with theknowledge/spec/sysml2/clause folder).