ktsu.Semantics 2.0.0 — Unified Vector Quantities [major]

.claude/skills/add-physics-quantity/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: add-physics-quantity
+description: Add a new physics quantity type with units, dimensions, operators, and tests to the source-generated system
+disable-model-invocation: true
+---
+
+# Add Physics Quantity
+
+Add a new physics quantity to the source-generated physics system. This is a fully metadata-driven process - no C# code needs to be written manually.
+
+## Required Information
+
+Before starting, gather from the user:
+1. **Quantity name** (e.g., "Viscosity", "MagneticFlux")
+2. **Physical dimension symbol** (e.g., "M L⁻¹ T⁻¹")
+3. **Dimensional formula** (exponents for mass, length, time, temperature, current, amount, luminosity)
+4. **SI unit name and symbol** (e.g., "Pascal" / "Pa")
+5. **Which vector forms** are needed (magnitude only, or 1D/2D/3D/4D)
+6. **Physics relationships** - what other quantities multiply/divide to produce this one
+7. **Any semantic overloads** (named aliases like Weight for ForceMagnitude)
+
+## Steps
+
+### Step 1: Add Dimension to dimensions.json
+
+**File**: `Semantics.SourceGenerators/Metadata/dimensions.json`
+
+Add a new entry to the `physicalDimensions` array following the existing pattern. Each dimension needs:
+- `name`: PascalCase dimension name
+- `symbol`: Unicode dimension symbol
+- `dimensionalFormula`: object with exponents for base dimensions
+- `availableUnits`: array of unit names (must match units.json entries)
+- `quantities`: object defining vector forms (vector0 = magnitude, vector1-4 = directional)
+- `integrals`: array of `{other, result}` pairs where `Self * Other = Result`
+- `derivatives`: array of `{other, result}` pairs where `Self / Other = Result`
+- `dotProducts`: array for dot product relationships (vector forms only)
+- `crossProducts`: array for cross product relationships (vector3 forms only)
+
+**Important**: The generator automatically creates inverse operators. If you define `Force * Length = Energy` on Force, the generator also creates `Energy / Length = Force` and `Energy / Force = Length` on Energy.
+
+### Step 2: Add Units to units.json (if new units needed)
+
+**File**: `Semantics.SourceGenerators/Metadata/units.json`
+
+Add unit entries to the appropriate `unitCategories` entry, or create a new category. Each unit needs:
+- `name`: PascalCase unit name
+- `symbol`: unit symbol string
+- `description`: brief description
+- `system`: one of "SIBase", "SIDerived", "Imperial", "USCustomary", "CGS", "Other"
+
+### Step 3: Add Conversions to conversions.json (if non-SI units exist)
+
+**File**: `Semantics.SourceGenerators/Metadata/conversions.json`
+
+Add conversion factor entries for converting between unit systems. Each factor needs:
+- `name`: descriptive PascalCase name (e.g., "CalorieToJoules")
+- `description`: includes the exact numeric value
+- `value`: string representation of the conversion factor
+
+### Step 4: Add Physical Constants to domains.json (if applicable)
+
+**File**: `Semantics.SourceGenerators/Metadata/domains.json`
+
+If the quantity involves physical constants, add them to the relevant domain entry.
+
+### Step 5: Build and Verify
+
+```bash
+cd Semantics.Quantities && dotnet build
+```
+
+The source generator will create:
+- Quantity classes for each vector form in `Generated/`
+- Updated `PhysicalDimensions.g.cs` with dimension metadata
+- Updated `Units.g.cs` with unit definitions
+- Operator overloads for all defined physics relationships
+
+### Step 6: Run Tests
+
+```bash
+dotnet test
+```
+
+Verify all existing tests still pass and the new quantity types are correctly generated.
+
+## Validation Checklist
+
+- [ ] Dimensional formula exponents sum correctly for the physical dimension
+- [ ] Physics relationships are dimensionally consistent (check both sides of equations)
+- [ ] Inverse operators are NOT manually added (generator handles them automatically)
+- [ ] Unit symbols follow standard conventions
+- [ ] `availableUnits` entries match `units.json` unit names exactly
+- [ ] No circular dependencies in physics relationships

.github/workflows/dotnet.yml

@@ -190,6 +190,7 @@ jobs:
           path: |
             ./coverage/*
           retention-days: 7
+          if-no-files-found: ignore
 
   winget:
     name: Update Winget Manifests

.github/workflows/verify-generated.yml

@@ -0,0 +1,55 @@
+name: Verify Generated Files
+
+# Two kinds of generated artifacts are committed to this repo:
+#   1. Source-generator output under Semantics.Quantities/Generated/ (EmitCompilerGeneratedFiles=true).
+#   2. The storage-type alias props under Semantics.Quantities.<T>/buildTransitive/, produced by
+#      scripts/Generate-AliasProps.ps1 from the quantity catalogue.
+# This job rebuilds and regenerates both, then fails if anything drifts from its source — so a
+# committed generated file or alias-props file can never go stale.
+#
+# NOTE: this is a standalone workflow on purpose — dotnet.yml is centrally synced from a
+# shared template across ktsu repos, so a step added there would be overwritten. If this
+# check belongs in the shared KtsuBuild pipeline long-term, move it there and delete this.
+
+on:
+  pull_request:
+    paths-ignore: ["**.md"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: verify-generated-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify-generated:
+    name: Generated files up to date
+    # windows-latest so git's autocrlf matches the committed CRLF line endings and the
+    # diff doesn't flag end-of-line differences.
+    runs-on: windows-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup .NET SDK
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: "10.0.x"
+
+      - name: Build (regenerates source-generator output into Generated/)
+        run: dotnet build Semantics.Quantities/Semantics.Quantities.csproj -c Release
+
+      - name: Regenerate storage-type alias props
+        shell: pwsh
+        run: ./scripts/Generate-AliasProps.ps1
+
+      - name: Fail if generated files or alias props are stale
+        shell: bash
+        run: |
+          if ! git diff --exit-code; then
+            echo "::error::Committed generated files or alias props are out of date. Run 'dotnet build Semantics.Quantities/Semantics.Quantities.csproj -c Release' then 'pwsh scripts/Generate-AliasProps.ps1', and commit the changes."
+            exit 1
+          fi

.serena/.gitignore

@@ -0,0 +1 @@
+/cache

.serena/project.yml

@@ -0,0 +1,113 @@
+# the name by which the project can be referenced within Serena
+project_name: "Semantics"
+
+
+# list of languages for which language servers are started; choose from:
+#   al                  bash                clojure             cpp                 csharp
+#   csharp_omnisharp    dart                elixir              elm                 erlang
+#   fortran             fsharp              go                  groovy              haskell
+#   java                julia               kotlin              lua                 markdown
+#   matlab              nix                 pascal              perl                php
+#   php_phpactor        powershell          python              python_jedi         r
+#   rego                ruby                ruby_solargraph     rust                scala
+#   swift               terraform           toml                typescript          typescript_vts
+#   vue                 yaml                zig
+#   (This list may be outdated. For the current list, see values of Language enum here:
+#   https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py
+#   For some languages, there are alternative language servers, e.g. csharp_omnisharp, ruby_solargraph.)
+# Note:
+#   - For C, use cpp
+#   - For JavaScript, use typescript
+#   - For Free Pascal/Lazarus, use pascal
+# Special requirements:
+#   Some languages require additional setup/installations.
+#   See here for details: https://oraios.github.io/serena/01-about/020_programming-languages.html#language-servers
+# When using multiple languages, the first language server that supports a given file will be used for that file.
+# The first language is the default language and the respective language server will be used as a fallback.
+# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
+languages:
+- csharp
+
+# the encoding used by text files in the project
+# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
+encoding: "utf-8"
+
+# whether to use project's .gitignore files to ignore files
+ignore_all_files_in_gitignore: true
+
+# list of additional paths to ignore in this project.
+# Same syntax as gitignore, so you can use * and **.
+# Note: global ignored_paths from serena_config.yml are also applied additively.
+ignored_paths: []
+
+# whether the project is in read-only mode
+# If set to true, all editing tools will be disabled and attempts to use them will result in an error
+# Added on 2025-04-18
+read_only: false
+
+# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
+# Below is the complete list of tools for convenience.
+# To make sure you have the latest list of tools, and to view their descriptions, 
+# execute `uv run scripts/print_tool_overview.py`.
+#
+#  * `activate_project`: Activates a project by name.
+#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
+#  * `create_text_file`: Creates/overwrites a file in the project directory.
+#  * `delete_lines`: Deletes a range of lines within a file.
+#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
+#  * `execute_shell_command`: Executes a shell command.
+#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
+#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
+#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
+#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
+#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
+#  * `initial_instructions`: Gets the initial instructions for the current project.
+#     Should only be used in settings where the system prompt cannot be set,
+#     e.g. in clients you have no control over, like Claude Desktop.
+#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
+#  * `insert_at_line`: Inserts content at a given line in a file.
+#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
+#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
+#  * `list_memories`: Lists memories in Serena's project-specific memory store.
+#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
+#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
+#  * `read_file`: Reads a file within the project directory.
+#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
+#  * `remove_project`: Removes a project from the Serena configuration.
+#  * `replace_lines`: Replaces a range of lines within a file with new content.
+#  * `replace_symbol_body`: Replaces the full definition of a symbol.
+#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
+#  * `search_for_pattern`: Performs a search for a pattern in the project.
+#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
+#  * `switch_modes`: Activates modes by providing a list of their names
+#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
+#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
+#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
+#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
+excluded_tools: []
+
+# list of tools to include that would otherwise be disabled (particularly optional tools that are disabled by default)
+included_optional_tools: []
+
+# fixed set of tools to use as the base tool set (if non-empty), replacing Serena's default set of tools.
+# This cannot be combined with non-empty excluded_tools or included_optional_tools.
+fixed_tools: []
+
+# list of mode names to that are always to be included in the set of active modes
+# The full set of modes to be activated is base_modes + default_modes.
+# If the setting is undefined, the base_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this setting overrides the global configuration.
+# Set this to [] to disable base modes for this project.
+# Set this to a list of mode names to always include the respective modes for this project.
+base_modes:
+
+# list of mode names that are to be activated by default.
+# The full set of modes to be activated is base_modes + default_modes.
+# If the setting is undefined, the default_modes from the global configuration (serena_config.yml) apply.
+# Otherwise, this overrides the setting from the global configuration (serena_config.yml).
+# This setting can, in turn, be overridden by CLI parameters (--mode).
+default_modes:
+
+# initial prompt for the project. It will always be given to the LLM upon activating the project
+# (contrary to the memories, which are loaded on demand).
+initial_prompt: ""