From c1399425eb64bccfd7acbbcdbc318f2e36a89305 Mon Sep 17 00:00:00 2001
From: Meta Vens <rwvens@hotmail.com>
Date: Thu, 22 Oct 2026 19:46:37 +0200
Subject: [PATCH] Pin CultLib 2.0.0 for builds

Directory.Build.props names CultLibRoot (CULTLIB_ROOT, else the sibling checkout) and pins CultLibRevision to cultlib-unity-v2.0.0 (42dce361). Directory.Build.targets fails the build unless that checkout is at the pin and clean, as Aetheria's guard does. Project references use CultLibRoot.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 Directory.Build.props                      | 10 ++++++++
 Directory.Build.targets                    | 30 ++++++++++++++++++++++
 README.md                                  | 11 ++++++++
 src/AquaSynth.Core/AquaSynth.Core.csproj   |  4 +--
 src/AquaSynth.Faust/AquaSynth.Faust.csproj |  2 +-
 5 files changed, 54 insertions(+), 3 deletions(-)
 create mode 100644 Directory.Build.props
 create mode 100644 Directory.Build.targets

diff --git a/Directory.Build.props b/Directory.Build.props
new file mode 100644
index 0000000..c8a3c67
--- /dev/null
+++ b/Directory.Build.props
@@ -0,0 +1,10 @@
+<Project>
+  <PropertyGroup>
+    <CultLibRoot Condition="'$(CultLibRoot)' == '' and '$(CULTLIB_ROOT)' != ''">$(CULTLIB_ROOT)</CultLibRoot>
+    <CultLibRoot Condition="'$(CultLibRoot)' == ''">$(MSBuildThisFileDirectory)..\CultLib</CultLibRoot>
+    <!-- CultLib 2.0.0: tag cultlib-unity-v2.0.0. -->
+    <CultLibRevision>42dce3611a81adc5c5fac54cadbaa5637d6022d3</CultLibRevision>
+    <GitExecutable Condition="'$(GitExecutable)' == '' and Exists('C:\Program Files\Git\cmd\git.exe')">C:\Program Files\Git\cmd\git.exe</GitExecutable>
+    <GitExecutable Condition="'$(GitExecutable)' == ''">git</GitExecutable>
+  </PropertyGroup>
+</Project>
diff --git a/Directory.Build.targets b/Directory.Build.targets
new file mode 100644
index 0000000..46d436a
--- /dev/null
+++ b/Directory.Build.targets
@@ -0,0 +1,30 @@
+<Project>
+  <!-- Builds consume CultLib at one admitted revision. Point CultLibRoot (or CULTLIB_ROOT) at a clean
+       worktree of that revision: git worktree add <path> cultlib-unity-v2.0.0 (detached) (in CultLib). -->
+  <Target Name="VerifyCultLibRevision"
+          BeforeTargets="ResolveProjectReferences"
+          Condition="'$(SkipCultLibRevisionCheck)' != 'true'">
+    <ItemGroup>
+      <_CultLibReference Include="@(ProjectReference)"
+                         Condition="$([System.String]::Copy('%(Filename)').StartsWith('GameCult.')) or '%(Filename)' == 'CultMath'" />
+    </ItemGroup>
+    <Error Condition="'@(_CultLibReference)' != '' and !Exists('$(CultLibRoot)\src\GameCult.Caching\GameCult.Caching.csproj')"
+           Text="CultLibRoot '$(CultLibRoot)' is not a CultLib checkout." />
+    <Exec Condition="'@(_CultLibReference)' != ''"
+          Command="&quot;$(GitExecutable)&quot; -C &quot;$(CultLibRoot)&quot; rev-parse HEAD"
+          ConsoleToMSBuild="true"
+          StandardOutputImportance="Low">
+      <Output TaskParameter="ConsoleOutput" PropertyName="ActualCultLibRevision" />
+    </Exec>
+    <Error Condition="'@(_CultLibReference)' != '' and '$([System.String]::Copy($(ActualCultLibRevision)).Trim())' != '$(CultLibRevision)'"
+           Text="CultLib must be revision $(CultLibRevision) (cultlib-unity-v2.0.0); found $([System.String]::Copy($(ActualCultLibRevision)).Trim()). Set CultLibRoot to a clean worktree of that tag." />
+    <Exec Condition="'@(_CultLibReference)' != ''"
+          Command="&quot;$(GitExecutable)&quot; -C &quot;$(CultLibRoot)&quot; status --porcelain --untracked-files=normal"
+          ConsoleToMSBuild="true"
+          StandardOutputImportance="Low">
+      <Output TaskParameter="ConsoleOutput" PropertyName="CultLibStatus" />
+    </Exec>
+    <Error Condition="'@(_CultLibReference)' != '' and '$([System.String]::Copy($(CultLibStatus)).Trim())' != ''"
+           Text="CultLibRoot '$(CultLibRoot)' must be clean before this repo consumes it." />
+  </Target>
+</Project>
diff --git a/README.md b/README.md
index 837d9ed..a6b1d7e 100644
--- a/README.md
+++ b/README.md
@@ -153,3 +153,14 @@ tract curriculum is tracked in
 prior-work notes in
 [`docs/utterance-parity-research.md`](docs/utterance-parity-research.md). Agent
 handoff state lives in [`state/spine.yaml`](state/spine.yaml).
+
+## Building against CultLib
+
+Builds are pinned to CultLib 2.0.0 (tag `cultlib-unity-v2.0.0`, revision `42dce3611a81adc5c5fac54cadbaa5637d6022d3`); the build fails if the CultLib checkout differs or is dirty. Create a pinned worktree and point the build at it:
+
+```powershell
+git -C <CultLib> worktree add --detach <path> cultlib-unity-v2.0.0
+dotnet build -p:CultLibRoot=<path>   # or set CULTLIB_ROOT=<path>
+```
+
+Without an override the sibling `..\CultLib` checkout is used and must itself be at that tag.
diff --git a/src/AquaSynth.Core/AquaSynth.Core.csproj b/src/AquaSynth.Core/AquaSynth.Core.csproj
index 4a1ae4d..38833f3 100644
--- a/src/AquaSynth.Core/AquaSynth.Core.csproj
+++ b/src/AquaSynth.Core/AquaSynth.Core.csproj
@@ -22,8 +22,8 @@
   </ItemGroup>
 
   <ItemGroup>
-    <ProjectReference Include="..\..\..\CultLib\src\GameCult.Caching.MessagePack\GameCult.Caching.MessagePack.csproj" />
-    <ProjectReference Include="..\..\..\CultLib\src\GameCult.Mesh\GameCult.Mesh.csproj" />
+    <ProjectReference Include="$(CultLibRoot)\src\GameCult.Caching.MessagePack\GameCult.Caching.MessagePack.csproj" />
+    <ProjectReference Include="$(CultLibRoot)\src\GameCult.Mesh\GameCult.Mesh.csproj" />
   </ItemGroup>
 
 </Project>
diff --git a/src/AquaSynth.Faust/AquaSynth.Faust.csproj b/src/AquaSynth.Faust/AquaSynth.Faust.csproj
index a9602cb..2f99a95 100644
--- a/src/AquaSynth.Faust/AquaSynth.Faust.csproj
+++ b/src/AquaSynth.Faust/AquaSynth.Faust.csproj
@@ -17,7 +17,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\AquaSynth.Core\AquaSynth.Core.csproj" />
-    <ProjectReference Include="..\..\..\CultLib\src\GameCult.Networking\GameCult.Networking.csproj" />
+    <ProjectReference Include="$(CultLibRoot)\src\GameCult.Networking\GameCult.Networking.csproj" />
   </ItemGroup>
 
   <ItemGroup>