Consume Harmony via NuGet instead of submodule (#2354)

* Remove backend/harmony git submodule.

* Consume Harmony via NuGet with optional local source mode.

* remove commitId from IChange ts interface

* Add migration adding new Commits index

---------

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: hahn-kev

.claude/agents/harmony-sentinel.md

@@ -1,72 +1,61 @@
 ---
 name: harmony-sentinel
-description: Review changes to the backend/harmony submodule — submodule-pointer bumps or in-place edits. Thin shim that cites harmony's own AGENTS.md as the authoritative source; the substrate-author standards (change-application semantics, snapshot equivalence, commit ordering, backward compatibility) live in the harmony repo where they belong.
+description: Review Harmony package version bumps and MSBuild reference changes in LexBox. Thin shim that cites the harmony repo's AGENTS.md as the authoritative source for substrate-author standards (change-application semantics, snapshot equivalence, commit ordering, backward compatibility).
 tools: Bash, Read, Grep, Glob
 model: opus
 ---
 
-You review changes to the Harmony CRDT library — the substrate every
-FwLite component depends on. Stakes are higher than any other domain:
-a bug here ripples to all consumers.
+You review changes to how LexBox depends on the Harmony CRDT library — the
+substrate every FwLite component depends on. Stakes are higher than any other
+domain: a bug here ripples to all consumers.
 
-You are a **thin shim**. The standards live in
-`backend/harmony/AGENTS.md` (canonical) — read that file before
-reviewing and walk its standards against the diff.
+You are a **thin shim**. The standards live in the
+[sillsdev/harmony](https://github.com/sillsdev/harmony) repo's `AGENTS.md`
+(canonical) — read that file before reviewing and walk its standards against
+the release notes / changelog for the version being adopted.
 
 ## How the diff arrives
 
-**Submodule pointer bump** — lexbox PR moves the submodule SHA forward.
+**Package version bump** — lexbox PR updates `SIL.Harmony*` versions in
+`backend/Directory.Packages.props` (and possibly `backend/Harmony*.props`).
 
 ```bash
-git diff origin/develop...HEAD -- backend/harmony | grep '^[-+]Subproject'
-cd backend/harmony && git log OLD..NEW --oneline
-cd backend/harmony && git diff OLD..NEW
+git diff origin/develop...HEAD -- backend/Directory.Packages.props backend/Harmony*.props
 ```
 
-**In-place edits** — lexbox PR contains uncommitted work inside
-`backend/harmony/`. Diff those files directly.
+Cross-check the new version against the harmony repo release tag / commit range
+on GitHub. If the PR body links a harmony release, verify the pinned versions
+match.
 
-## If harmony isn't initialized
+**Local source mode changes** — edits to `backend/Harmony.props` or
+`backend/Harmony.*.References.props` that affect `UseHarmonySource` /
+`HarmonySourcePath` behavior.
 
-The `.claude/hooks/session-start.sh` SessionStart hook initializes the
-submodule on session start. If for some reason it's empty:
+## If you cannot read the harmony release
 
-> ⚠️ important — Can't review harmony content; submodule not fetched.
-> Recommend running `git submodule update --init --recursive backend/harmony`,
-> or opening a PR in `sillsdev/harmony` directly.
+> ⚠️ important — Can't review substrate changes without the harmony release
+> diff. Open the tagged commit on GitHub (`sillsdev/harmony`) for the pinned
+> version, or ask the author to link the release notes.
 
 Don't fabricate findings against unread code.
 
-## If harmony has no AGENTS.md yet
-
-The thin-shim design assumes `backend/harmony/AGENTS.md` exists. If
-absent at this submodule SHA:
-
-> ⚠️ important — `backend/harmony/AGENTS.md` not present at this SHA.
-> Falling back to a reduced check: serialization-shape changes
-> (`[JsonConstructor]`, property renames in `Change<T>` subclasses),
-> public API of `IChangeContext` / `DataModel.QueryLatest<T>`,
-> projected-table generators. Recommend bumping the submodule to a SHA
-> that includes
-> AGENTS.md so the full review can run.
-
 ## Standard review
 
-1. **Read `backend/harmony/AGENTS.md` in full.** It owns the
+1. **Read harmony's `AGENTS.md` at the release tag** (on GitHub). It owns the
    substrate-author standards (change-application semantics, snapshot
    equivalence, commit ordering, backward compatibility of serialized
    formats, performance, test coverage expectations).
-2. **Walk those standards against the diff window**
-   (`git log OLD..NEW` commits for a pointer bump, or in-place edits).
-3. **Frame data-loss / consumer-break findings bluntly.** Cite specific
-   commits within the harmony range. Reference harmony files by path.
+2. **Walk those standards against the harmony changelog** between the old and
+   new pinned versions.
+3. **Flag LexBox consumer breaks** — serialization shape changes, public API
+   changes to `DataModel`, `IChangeContext`, projected-table behavior.
+4. **Frame data-loss / consumer-break findings bluntly.** Cite harmony files
+   by path in the upstream repo.
 
 ## Out of scope
 
 - LexBox / FwLite *usage* of harmony — `fwlite-sentinel`'s job.
-- Submodule pointer mechanics (gitlink correctness, .gitmodules) —
-  flag only if the pointer change looks accidental (e.g. moves
-  backward without justification).
+- Whether to use NuGet vs source mode — a developer workflow choice.
 
 ## Voice
 

.claude/hooks/session-start.sh

@@ -1,34 +1,6 @@
 #!/bin/bash
 # SessionStart hook for claude/amazing-franklin-BXNI5 and beyond.
 #
-# Ensures `backend/harmony/` (the CRDT substrate submodule) is checked out so
-# that subagents — particularly `harmony-sentinel` — can read its content.
-# Without this, plain `git clone` leaves the submodule as a bare gitlink
-# pointer and any agent that tries to read inside it gets an empty directory.
-#
-# Idempotent: `git submodule update --init --recursive` is a no-op when the
-# submodule is already at the pinned SHA.
-#
-# Non-fatal on network failure: a transient github.com outage shouldn't block
-# the whole session. We log and continue.
-
-set -uo pipefail
-
-# Only act in the remote (Claude Code on the web) environment. Local devs
-# manage their own submodules.
-if [ "${CLAUDE_CODE_REMOTE:-}" != "true" ]; then
-  exit 0
-fi
-
-cd "${CLAUDE_PROJECT_DIR:-$(pwd)}"
-
-echo "[session-start] initializing backend/harmony submodule…"
-if git submodule update --init --recursive backend/harmony 2>&1; then
-  echo "[session-start] harmony submodule ready at $(cd backend/harmony && git rev-parse --short HEAD 2>/dev/null || echo 'unknown')"
-else
-  rc=$?
-  echo "[session-start] WARN: submodule init failed (exit $rc); harmony-sentinel reviews will report 'submodule not fetched' until resolved." >&2
-fi
+# Harmony is consumed via NuGet; no submodule initialization required.
 
-# Always exit 0 so a failed submodule init doesn't block the session.
 exit 0

.claude/skills/_shared/apply-rules.md

@@ -65,7 +65,7 @@ otherwise. One decision at a time.
 
 - Commit, push, open a PR.
 - Run integration tests (root `AGENTS.md`).
-- Touch `backend/harmony` submodule contents.
+- Bump `SIL.Harmony*` package versions without `harmony-sentinel` review.
 - Modify `.git/`, `deployment/` PVCs, or any infrastructure state.
 
 ## Re-validate after fixes (loop, hard cap 2)

.claude/skills/_shared/dispatch-matrix.md

@@ -22,7 +22,7 @@ Dispatch via `Agent` with `subagent_type=<name>` (the value in the
 
 | Touched | Agent |
 |---|---|
-| `backend/harmony/**` (submodule pointer bump or in-place edits) | `harmony-sentinel` |
+| `backend/Directory.Packages.props` or `backend/Harmony*.props` (SIL.Harmony* version or reference changes) | `harmony-sentinel` |
 | `backend/FwLite/**` | `fwlite-sentinel` |
 | `backend/FwHeadless/**` | `fwheadless-sentinel` |
 | `backend/LexBoxApi/GraphQL/**` or any `.cs` with `[GraphQLType]` / `[QueryType]` / `[MutationType]` / `[ObjectType]` | `graphql` (additive — `dotnet-stylist` still runs on these too) |

.github/workflows/codeql.yml

@@ -44,8 +44,6 @@ jobs:
     steps:
     - name: Checkout repository
       uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
-      with:
-        submodules: true
 
 
     # Initializes the CodeQL tools for scanning.

.github/workflows/fw-lite.yaml

@@ -4,7 +4,8 @@ on:
   push:
     paths:
       - 'backend/FwLite/**'
-      - 'backend/harmony/**'
+      - 'backend/Directory.Packages.props'
+      - 'backend/Harmony*.props'
       - 'frontend/viewer/**'
       - '.github/workflows/fw-lite.yaml'
       - 'FwLiteOnly.slnf'
@@ -14,7 +15,8 @@ on:
   pull_request:
     paths:
       - 'backend/FwLite/**'
-      - 'backend/harmony/**'
+      - 'backend/Directory.Packages.props'
+      - 'backend/Harmony*.props'
       - 'frontend/viewer/**'
       - '.github/workflows/fw-lite.yaml'
       - 'FwLiteOnly.slnf'
@@ -35,8 +37,6 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
-        with:
-          submodules: true
       - uses: actions/setup-dotnet@9a946fdbd5fb07b82b2f5a4466058b876ab72bb2 # v5.3.0
         with:
           dotnet-version: '10.x'
@@ -171,8 +171,6 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
-        with:
-          submodules: true
       - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
         with:
           name: fw-lite-viewer-js
@@ -208,8 +206,6 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
-        with:
-          submodules: true
       - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
         with:
           name: fw-lite-viewer-js
@@ -254,8 +250,6 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
-        with:
-          submodules: true
       - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
         with:
           name: fw-lite-viewer-js
@@ -308,8 +302,6 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
-        with:
-          submodules: true
       - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5.0.0
         with:
           name: fw-lite-viewer-js

.github/workflows/integration-test-gha.yaml

@@ -20,8 +20,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
-        with:
-          submodules: true
       - uses: actions/setup-dotnet@9a946fdbd5fb07b82b2f5a4466058b876ab72bb2 # v5.3.0
         with:
           dotnet-version: '10.x'

.github/workflows/integration-test.yaml

@@ -69,8 +69,6 @@ jobs:
     runs-on: ${{ inputs.runs-on }}
     steps:
       - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
-        with:
-          submodules: true
       - uses: actions/setup-dotnet@9a946fdbd5fb07b82b2f5a4466058b876ab72bb2 # v5.3.0
         with:
           dotnet-version: '10.x'

.github/workflows/lexbox-api.yaml

@@ -45,8 +45,6 @@ jobs:
 
     steps:
       - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
-        with:
-          submodules: true
       - uses: actions/setup-dotnet@9a946fdbd5fb07b82b2f5a4466058b876ab72bb2 # v5.3.0
         with:
           dotnet-version: '10.x'

.github/workflows/lexbox-fw-headless.yaml

@@ -45,8 +45,6 @@ jobs:
 
     steps:
       - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1
-        with:
-          submodules: true
       - uses: actions/setup-dotnet@9a946fdbd5fb07b82b2f5a4466058b876ab72bb2 # v5.3.0
         with:
           dotnet-version: '10.x'