Marpaia/flow and mother machine integration

.clang-format

@@ -3,3 +3,12 @@ ColumnLimit: 100
 DerivePointerAlignment: false
 PointerAlignment: Left
 SortIncludes: CaseSensitive
+AllowShortFunctionsOnASingleLine: Empty
+AllowShortBlocksOnASingleLine: Never
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+AllowShortLambdasOnASingleLine: None
+InsertBraces: true
+SeparateDefinitionBlocks: Always
+MaxEmptyLinesToKeep: 1
+KeepEmptyLinesAtTheStartOfBlocks: false

.clang-tidy

@@ -6,6 +6,6 @@ Checks: >-
   -portability-avoid-pragma-once,
   -readability-magic-numbers,
   -readability-identifier-length
-WarningsAsErrors: ''
-HeaderFilterRegex: 'cpp/(include|core|cpu)/.*'
+WarningsAsErrors: ""
+HeaderFilterRegex: "cpp/(include|core|cpu)/.*"
 FormatStyle: file

.cmake-format.yaml

@@ -0,0 +1,5 @@
+format:
+  line_width: 100
+  tab_size: 2
+markup:
+  enable_markup: false

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.{py,pyi}]
+indent_size = 4
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

.github/workflows/live-shutdown-windows.yml

@@ -0,0 +1,80 @@
+name: Windows CLI and live-session checks
+
+on:
+  pull_request:
+    paths:
+      - .github/workflows/live-shutdown-windows.yml
+      - CMakeLists.txt
+      - cpp/**
+      - python/**
+      - docs/tutorials/**
+      - docs/development/tutorial-command-validation.md
+      - environments/**/README.md
+      - viewer/README.md
+      - pyproject.toml
+      - uv.lock
+  push:
+    branches: [master, marpaia/17, marpaia/24]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: windows-live-shutdown-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  shutdown:
+    runs-on: windows-2025
+    timeout-minutes: 20
+    defaults:
+      run:
+        shell: pwsh
+    env:
+      CMAKE_BUILD_PARALLEL_LEVEL: "2"
+      # Exercise the host reference engine without requiring a GPU toolkit.
+      CMAKE_ARGS: -DCM_ENABLE_METAL=OFF -DCM_ENABLE_CUDA=OFF -DCM_BUILD_TESTS=OFF
+      MICROSIMULATOR_COMMAND_REPORT: build/shutdown-evidence/tutorial-commands
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Build CPU extension and install locked test dependencies
+        run: uv sync --locked --group dev
+
+      - name: Record platform, shell, interpreter, and backend
+        run: |
+          New-Item -ItemType Directory -Force build/shutdown-evidence | Out-Null
+          $PSVersionTable | Out-File build/shutdown-evidence/platform.txt
+          [System.Environment]::OSVersion | Out-File -Append build/shutdown-evidence/platform.txt
+          uv run --no-sync python --version 2>&1 | Tee-Object -Append build/shutdown-evidence/platform.txt
+          uv run --no-sync microsimulator devices --json | Tee-Object -Append build/shutdown-evidence/platform.txt
+
+      - name: Verify Stop, console Ctrl+C, worker draining, and same-port restart
+        run: >-
+          uv run --no-sync python -m pytest
+          python/tests/test_viewer_server.py python/tests/test_viewer_shutdown.py
+          -v --tb=short --junitxml=build/shutdown-evidence/tests.xml
+
+      - name: Execute the documented PowerShell CLI commands
+        run: >-
+          uv run --no-sync python -m pytest python/tests/test_tutorial_commands.py
+          -v --tb=short --junitxml=build/shutdown-evidence/tutorial-commands.xml
+
+      - name: Upload shutdown evidence
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: windows-live-shutdown-${{ github.sha }}
+          path: build/shutdown-evidence
+          if-no-files-found: warn
+          retention-days: 30

.github/workflows/quality.yml

@@ -0,0 +1,53 @@
+name: Code quality
+
+on:
+  pull_request:
+  push:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: quality-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+      - name: Install pinned pnpm
+        run: npm install --global pnpm@10.12.1
+      - run: pnpm --dir viewer install --frozen-lockfile
+      - name: Check all maintained files
+        run: uv run --isolated --locked --only-group quality python scripts/quality.py check
+      - name: Test quality tooling
+        run: uv run --isolated --locked --only-group quality python -m unittest discover -s tests/quality
+      - name: Type-check viewer
+        run: pnpm --dir viewer check
+
+  python-types:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    env:
+      CMAKE_ARGS: -DCM_ENABLE_METAL=OFF -DCM_ENABLE_CUDA=OFF -DCM_BUILD_TESTS=OFF
+      CMAKE_BUILD_PARALLEL_LEVEL: "2"
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+      - run: uv sync --locked --group dev
+      - run: uv run --locked --no-sync pyright

.gitignore

@@ -12,3 +12,4 @@ __pycache__/
 .mypy_cache/
 compile_commands.json
 results/
+feedback/

.pre-commit-config.yaml

@@ -20,27 +20,23 @@ repos:
       - id: trailing-whitespace
         exclude: ^docs/tutorials/devices/
 
-  # Pinned to the version the project depends on, so a hook run and a local
-  # `ruff check` enforce the same rule set. Formatting is deliberately absent:
-  # the linter's rules, including import order, are what this tree follows.
-  - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.16.3
-    hooks:
-      - id: ruff
-        args: [--fix]
-
-  - repo: https://github.com/pre-commit/mirrors-clang-format
-    rev: v19.1.7
-    hooks:
-      - id: clang-format
-        types_or: [c++, c, cuda, objective-c++, metal]
-        files: ^cpp/
-
   - repo: local
     hooks:
+      - id: format
+        name: Format maintained files
+        entry: uv run --isolated --locked --only-group quality python scripts/quality.py format
+        language: system
+        types: [text]
+        require_serial: true
+      - id: quality
+        name: Check formatting, lint, and complexity
+        entry: uv run --isolated --locked --only-group quality python scripts/quality.py check
+        language: system
+        types: [text]
+        require_serial: true
       - id: pyright
         name: pyright
-        entry: uv run pyright
+        entry: uv run --locked pyright
         language: system
         pass_filenames: false
         types: [python]

.prettierignore

@@ -0,0 +1,6 @@
+build/
+dist/
+node_modules/
+.venv/
+uv.lock
+**/pnpm-lock.yaml

.prettierrc.json

@@ -0,0 +1,4 @@
+{
+  "proseWrap": "preserve",
+  "embeddedLanguageFormatting": "off"
+}

.taplo.toml

@@ -0,0 +1,3 @@
+[formatting]
+column_width = 100
+reorder_keys = false

AGENTS.md

@@ -0,0 +1,3 @@
+# Repository conventions
+
+Follow [CONTRIBUTING.md](CONTRIBUTING.md) for formatting, logical grouping, function limits, and validation. Run the shared quality commands rather than system formatter versions. Preserve numerical operation order and backend ownership when extracting helpers. Keep existing user work intact.