Use FieldWorks.proj for main file

Add local mulit-agent capability

Author: johnml1135

.github/BUILD_REQUIREMENTS.md

@@ -32,7 +32,7 @@ If you only need to build C# projects and already have native artifacts from a p
 
 ```powershell
 # Build only managed projects (skips native C++)
-msbuild dirs.proj /p:Configuration=Debug /p:Platform=x64
+msbuild FieldWorks.proj /p:Configuration=Debug /p:Platform=x64
 ```
 
 ## CI Builds
@@ -76,7 +76,7 @@ Both `build.ps1` and `build.sh` now include:
 1. **Automatic FwBuildTasks bootstrap**: Builds build infrastructure before main build
 2. **Environment validation**: Warns if Developer environment is not detected
 3. **Package restoration**: Restores NuGet packages before build
-4. **Traversal build**: Uses MSBuild Traversal SDK (dirs.proj) for correct dependency ordering
+4. **Traversal build**: Uses MSBuild Traversal SDK (FieldWorks.proj) for correct dependency ordering
 
 ## Visual Studio Requirements
 

.github/copilot-instructions.md

@@ -173,6 +173,22 @@ Before submitting a PR:
 
 --------------------------------------------------------------------------------
 
+## Multi-agent worktree builds (containers)
+
+CRITICAL: When working in a worktree folder (path contains '\worktrees\agent-'), ALWAYS build inside the matching Docker container. Extract the agent number from the path and use: `docker exec fw-agent-N powershell -NoProfile -c "msbuild <solution> /m /p:Configuration=Debug"`
+
+To identify which container to use: if workspace path is '...\worktrees\agent-2\...', use container 'fw-agent-2'
+
+For agent worktrees, NEVER run msbuild directly on the host. COM/registry operations must happen in the isolated container.
+
+In agent worktrees, prefer using VS Code tasks ('Terminal > Run Task > Restore + Build Debug') which are pre-configured for the correct container.
+
+For the main repository (not in worktrees), build directly with: `.\build.ps1 -Configuration Debug` or `msbuild dirs.proj`
+
+Read-only operations (git, Get-Content, ls, dir) always run on the host, regardless of worktree.
+
+--------------------------------------------------------------------------------
+
 ## Where to make changes
 
 - Core source: Src/ contains the primary C# and C++ projects. Mirror existing patterns for new code.

.github/instructions/build.instructions.md

@@ -6,7 +6,7 @@ description: "FieldWorks build guidelines and inner-loop tips"
 
 ## Quick Start
 
-FieldWorks uses the **MSBuild Traversal SDK** for declarative build ordering. All builds use `dirs.proj`.
+FieldWorks uses the **MSBuild Traversal SDK** for declarative build ordering. All builds use `FieldWorks.proj`.
 
 ### Windows (PowerShell)
 ```powershell
@@ -36,13 +36,13 @@ FieldWorks uses the **MSBuild Traversal SDK** for declarative build ordering. Al
 - Declarative dependency ordering (110+ projects organized into 21 phases)
 - Automatic parallel builds where safe
 - Better incremental build performance
-- Works with `dotnet build dirs.proj`
+- Works with `dotnet build FieldWorks.proj`
 - Clear error messages when prerequisites missing
 
 ## Build Architecture
 
 ### Traversal Build Phases
-The `dirs.proj` file defines a declarative build order:
+The `FieldWorks.proj` file defines a declarative build order:
 
 1. **Phase 1**: FwBuildTasks (build infrastructure)
 2. **Phase 2**: Native C++ components (via `allCppNoTest` target)
@@ -78,9 +78,9 @@ Run: msbuild Build\Src\NativeBuild\NativeBuild.csproj
   - Generated code out of sync (delete `Src/Common/ViewsInterfaces/Views.cs`)
 
 ### Choose the right path
-- **Full system build**: `.\build.ps1` or `./build.sh` (uses dirs.proj traversal)
-- **Direct MSBuild**: `msbuild dirs.proj /p:Configuration=Debug /p:Platform=x64 /m`
-- **Dotnet CLI**: `dotnet build dirs.proj` (requires .NET SDK)
+- **Full system build**: `.\build.ps1` or `./build.sh` (uses FieldWorks.proj traversal)
+- **Direct MSBuild**: `msbuild FieldWorks.proj /p:Configuration=Debug /p:Platform=x64 /m`
+- **Dotnet CLI**: `dotnet build FieldWorks.proj` (requires .NET SDK)
 - **Single project**: `msbuild Src/<Path>/<Project>.csproj` (for quick iterations)
 - **Native only**: `msbuild Build\Src\NativeBuild\NativeBuild.csproj` (Phase 2 of traversal)
 - **Installer**: See `Build/Installer.targets` for installer build targets (requires WiX Toolset)
@@ -114,18 +114,18 @@ msbuild Build\Src\NativeBuild\NativeBuild.csproj /p:Configuration=Debug /p:Platf
 ### Build Order Issues
 **Symptom**: Project X fails because it can't find assembly from project Y
 
-**Solution**: The traversal build handles this automatically through `dirs.proj`:
+**Solution**: The traversal build handles this automatically through `FieldWorks.proj`:
 - Check that the dependency is listed in an earlier phase than the dependent
-- Verify both projects are included in `dirs.proj`
-- If you find a missing dependency, update `dirs.proj` phase ordering
+- Verify both projects are included in `FieldWorks.proj`
+- If you find a missing dependency, update `FieldWorks.proj` phase ordering
 
 ### Parallel Build Race Conditions
 **Symptom**: Random failures in parallel builds
 
 **Solution**:
 - Traversal SDK respects dependencies and avoids races
 - If you encounter race conditions, reduce parallelism: `.\build.ps1 -MsBuildArgs @('/m:1')`
-- Report race conditions so dependencies can be added to `dirs.proj`
+- Report race conditions so dependencies can be added to `FieldWorks.proj`
 
 ### Clean Build Required
 ```powershell
@@ -150,39 +150,39 @@ msbuild Build\Src\NativeBuild\NativeBuild.csproj /p:Configuration=Debug /p:Platf
 ### Direct MSBuild Invocation
 ```powershell
 # Traversal build with MSBuild
-msbuild dirs.proj /p:Configuration=Debug /p:Platform=x64 /m
+msbuild FieldWorks.proj /p:Configuration=Debug /p:Platform=x64 /m
 
 # With tests
-msbuild dirs.proj /p:Configuration=Debug /p:Platform=x64 /p:action=test /m
+msbuild FieldWorks.proj /p:Configuration=Debug /p:Platform=x64 /p:action=test /m
 ```
 
 ### Building Specific Project Groups
 ```powershell
 # Native C++ only (Phase 2 of traversal)
 msbuild Build\Src\NativeBuild\NativeBuild.csproj
 
-# Specific phase from dirs.proj (not typically needed)
+# Specific phase from FieldWorks.proj (not typically needed)
 # The traversal build handles ordering automatically
 ```
 
 ### Dotnet CLI (Traversal Only)
 ```powershell
-# Works with dirs.proj
-dotnet build dirs.proj
+# Works with FieldWorks.proj
+dotnet build FieldWorks.proj
 
 # Restore packages
-dotnet restore dirs.proj --packages packages/
+dotnet restore FieldWorks.proj --packages packages/
 ```
 
 ## Don't modify build files lightly
-- **`dirs.proj`**: Traversal build order; verify changes don't create circular dependencies
+- **`FieldWorks.proj`**: Traversal build order; verify changes don't create circular dependencies
 - **`Build/mkall.targets`**: Native C++ build orchestration; changes affect all developers
 - **`Build/SetupInclude.targets`**: Environment setup; touch only when absolutely needed
 - **`Directory.Build.props`**: Shared properties for all projects; changes affect everyone
 
 ## References
 - **CI/CD**: `.github/workflows/` for CI steps
 - **Build Infrastructure**: `Build/` for targets/props and build infrastructure
-- **Traversal Project**: `dirs.proj` for declarative build order
+- **Traversal Project**: `FieldWorks.proj` for declarative build order
 - **Shared Properties**: `Directory.Build.props` for all projects
 - **Native Build**: `Build/mkall.targets` for C++ build orchestration

.vscode/settings.json

@@ -7,8 +7,51 @@
     "speckit.implement": true
   },
   "chat.tools.terminal.autoApprove": {
+    // Specify scripts
     ".specify/scripts/bash/": true,
-    ".specify/scripts/powershell/": true
+    ".specify/scripts/powershell/": true,
+    // Read-only operations
+    "Get-Content": true,
+    "cat": true,
+    "type": true,
+    "Get-ChildItem": true,
+    "ls": true,
+    "dir": true,
+    "tree": true,
+    "Test-Path": true,
+    "Get-Location": true,
+    "pwd": true,
+    "Get-Item": true,
+    "Get-ItemProperty": true,
+    // Git operations (read-only)
+    "git status": true,
+    "git log": true,
+    "git diff": true,
+    "git show": true,
+    "git branch": true,
+    "git worktree list": true,
+    // Docker read-only operations
+    "docker ps": true,
+    "docker images": true,
+    "docker logs": true,
+    "docker info": true,
+    "docker inspect": true,
+    // Docker exec - ONLY for agent containers (safe, isolated)
+    "docker exec fw-agent-": true,
+    // Build operations (host-based for main repo)
+    "msbuild": true,
+    "dotnet build": true,
+    "dotnet restore": true,
+    ".\\build.ps1": true,
+    ".\\build.sh": true,
+    // Test operations
+    "dotnet test": true,
+    "vstest.console": true,
+    "nunit3-console": true,
+    // Agent workflow scripts
+    ".\\scripts\\spin-up-agents.ps1": true,
+    ".\\scripts\\tear-down-agents.ps1": true,
+    ".\\scripts\\check-agents.ps1": true
   },
   "cmake.ignoreCMakeListsMissing": true
 }

BUILD_CHALLENGES_ANALYSIS.md

@@ -19,16 +19,16 @@
 The SDK migration faced **~80 compilation errors** across multiple attempts to get the build working. The key success factor was **systematic error resolution** - fixing one category completely before moving to the next. However, analysis reveals **some inconsistencies** in approach across different project types and phases that should be reconciled.
 
 ### Key Success Patterns
-✅ **Automated bulk conversion** (convertToSDK.py) handled 115 projects consistently  
-✅ **Wildcard package versions** (e.g., `11.0.0-*`) for SIL packages prevented version conflicts  
-✅ **Explicit test exclusion** pattern established and applied consistently  
-✅ **x64 enforcement** via Directory.Build.props propagated to all projects  
+✅ **Automated bulk conversion** (convertToSDK.py) handled 115 projects consistently
+✅ **Wildcard package versions** (e.g., `11.0.0-*`) for SIL packages prevented version conflicts
+✅ **Explicit test exclusion** pattern established and applied consistently
+✅ **x64 enforcement** via Directory.Build.props propagated to all projects
 
 ### Divergent Approaches Found
-⚠️ **GenerateAssemblyInfo handling** - Mixed true/false across projects without clear rationale  
-⚠️ **SDK type selection** - Some WPF projects initially used wrong SDK (Microsoft.NET.Sdk vs. WindowsDesktop)  
-⚠️ **Package reference patterns** - Inconsistent use of PrivateAssets and Exclude attributes  
-⚠️ **Platform target** - Some projects have explicit x64, others rely on inherited property  
+⚠️ **GenerateAssemblyInfo handling** - Mixed true/false across projects without clear rationale
+⚠️ **SDK type selection** - Some WPF projects initially used wrong SDK (Microsoft.NET.Sdk vs. WindowsDesktop)
+⚠️ **Package reference patterns** - Inconsistent use of PrivateAssets and Exclude attributes
+⚠️ **Platform target** - Some projects have explicit x64, others rely on inherited property
 
 ---
 
@@ -173,7 +173,7 @@ CS0103: The name 'InitializeComponent' does not exist in the current context
 ```xml
 <!-- Before -->
 <Project Sdk="Microsoft.NET.Sdk">
-  
+
 <!-- After -->
 <Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">
   <PropertyGroup>
@@ -193,7 +193,7 @@ CS0103: The name 'InitializeComponent' does not exist in the current context
 
 **Error**:
 ```
-CS0436: The type 'MasterItem' in 'MGA/MasterItem.cs' conflicts with 
+CS0436: The type 'MasterItem' in 'MGA/MasterItem.cs' conflicts with
         the imported type 'MasterItem' in 'MGA, Version=0.0.0.0'
 ```
 
@@ -232,7 +232,7 @@ Projects use different exclusion patterns:
 
 **Error**:
 ```
-CS0535: 'NullThreadedProgress' does not implement interface member 
+CS0535: 'NullThreadedProgress' does not implement interface member
         'IThreadedProgress.Canceling'
 ```
 
@@ -333,7 +333,7 @@ Projects fall into 3 categories:
 - Category 2: Redundant but harmless, explicitly states x64 ⚠️
 - Category 3: Build tools that may run on different platforms (FwBuildTasks) ✅
 
-**Recommendation**: 
+**Recommendation**:
 - Remove explicit `<PlatformTarget>x64</PlatformTarget>` from Category 2 projects
 - Rely on Directory.Build.props for consistency
 - Keep explicit only for special cases (build tools)
@@ -383,7 +383,7 @@ Only some EXE projects import RegFree.targets:
 - ❌ LexText.exe (not yet integrated)
 - ❌ Other utility EXEs
 
-**Recommendation**: 
+**Recommendation**:
 - Identify all EXE projects that use COM
 - Add RegFree.targets import to all of them
 - Document which EXEs need manifests
@@ -409,35 +409,35 @@ Only some EXE projects import RegFree.targets:
 #### Challenge 5.1: Build Order Dependencies
 **Problem**: 110+ projects need correct build order
 
-**Approach**: Implemented MSBuild Traversal SDK with dirs.proj
+**Approach**: Implemented MSBuild Traversal SDK with FieldWorks.proj
 
 **Decision Matrix**:
 
-| Approach | Pros | Cons | Chosen |
-|----------|------|------|--------|
-| Manual MSBuild dependencies | Fine-grained control | Hard to maintain | ❌ |
-| Solution build order | Simple | No declarative dependencies | ❌ |
-| Traversal SDK | Declarative phases | Learning curve | ✅ |
+| Approach                    | Pros                 | Cons                        | Chosen |
+| --------------------------- | -------------------- | --------------------------- | ------ |
+| Manual MSBuild dependencies | Fine-grained control | Hard to maintain            | ❌      |
+| Solution build order        | Simple               | No declarative dependencies | ❌      |
+| Traversal SDK               | Declarative phases   | Learning curve              | ✅      |
 
 **Implementation**:
 ```xml
-<!-- dirs.proj -->
+<!-- FieldWorks.proj -->
 <Project Sdk="Microsoft.Build.Traversal/4.1.0">
   <ItemGroup Label="Phase 1: Build Tasks">
     <ProjectReference Include="Build\Src\FwBuildTasks\FwBuildTasks.csproj" />
   </ItemGroup>
-  
+
   <ItemGroup Label="Phase 2: Native C++">
     <ProjectReference Include="Build\Src\NativeBuild\NativeBuild.csproj" />
   </ItemGroup>
-  
+
   <!-- ... 21 phases total -->
 </Project>
 ```
 
 **Success Factor**: Declarative ordering makes dependencies explicit and maintainable
 
-**Consistency**: ✅ All projects referenced in dirs.proj in correct phase
+**Consistency**: ✅ All projects referenced in FieldWorks.proj in correct phase
 
 **Decision Documentation**: 21 phases documented with clear rationale
 
@@ -606,7 +606,7 @@ Criteria for GenerateAssemblyInfo=true (default):
 - ✅ Wildcards for pre-release (e.g., 11.0.0-*) - SUCCESS
 - ✅ Fixed for stable (e.g., 4.4.0) - No conflicts
 
-**Final Decision**: 
+**Final Decision**:
 - Pre-release packages: Use wildcards (`*`)
 - Stable packages: Use fixed versions
 
@@ -639,7 +639,7 @@ Criteria for GenerateAssemblyInfo=true (default):
 
 **Tried**:
 - ⚠️ Enhanced mkall.targets - Works but complex
-- ✅ MSBuild Traversal SDK with dirs.proj - Declarative, maintainable
+- ✅ MSBuild Traversal SDK with FieldWorks.proj - Declarative, maintainable
 
 **Final Decision**: Full Traversal SDK implementation
 
@@ -751,6 +751,6 @@ The SDK migration was largely successful, with **systematic approaches** yieldin
 
 ---
 
-*Analysis Date: 2025-11-08*  
-*Based on: 93 commits from 8e508dab to HEAD*  
+*Analysis Date: 2025-11-08*
+*Based on: 93 commits from 8e508dab to HEAD*
 *Method: Deep commit analysis + pattern detection + consistency audit*

Build/Installer.targets

@@ -127,12 +127,14 @@
 			Properties="Configuration=Release;Platform=x86"
 		/>
 	</Target>
-
 	<!-- Modern traversal build for installer (replaces legacy remakefw) -->
-	<Target Name="BuildFieldWorks" DependsOnTargets="CleanAll;Initialize;CopyDlls;setRegistryValues;GeneratePartsAndLayoutFiles">
+	<Target
+		Name="BuildFieldWorks"
+		DependsOnTargets="CleanAll;Initialize;CopyDlls;setRegistryValues;GeneratePartsAndLayoutFiles"
+	>
 		<Message Text="Building FieldWorks using MSBuild Traversal SDK..." Importance="High" />
 		<MSBuild
-			Projects="$(fwrt)/dirs.proj"
+			Projects="$(fwrt)/FieldWorks.proj"
 			Properties="Configuration=$(Configuration);Platform=$(Platform);action=$(action);desktopNotAvailable=$(desktopNotAvailable)"
 		/>
 		<Message Text="FieldWorks build complete." Importance="High" />

Build/Orchestrator.proj

@@ -30,7 +30,7 @@
   <!-- Default Build target: orchestrate full traversal build -->
   <Target Name="Build">
     <Message Text="Building FieldWorks via MSBuild Traversal SDK" Importance="high" />
-    <MSBuild Projects="$(MSBuildThisFileDirectory)..\dirs.proj" Properties="Configuration=$(Configuration);Platform=$(Platform)" />
+    <MSBuild Projects="$(MSBuildThisFileDirectory)..\FieldWorks.proj" Properties="Configuration=$(Configuration);Platform=$(Platform)" />
   </Target>
 
   <!-- Installer targets are imported from Installer.targets -->

Build/Src/NativeBuild/NativeBuild.csproj

@@ -7,7 +7,7 @@
   <!--
     NativeBuild: Build orchestrator for native C++ component builds
 
-    This project serves as a bridge between the MSBuild Traversal SDK (dirs.proj)
+    This project serves as a bridge between the MSBuild Traversal SDK (FieldWorks.proj)
     and the native build system (mkall.targets). It allows the traversal
     build to properly sequence native component builds before managed projects.
 

Build/mkall.targets

@@ -4,10 +4,10 @@
 		Native C++ Build Orchestration for FieldWorks
 
 		This file coordinates building native C++ components (DebugProcs, GenericLib, FwKernel, Views)
-		and their associated test executables. It is called by the MSBuild Traversal SDK via dirs.proj.
+		and their associated test executables. It is called by the MSBuild Traversal SDK via FieldWorks.proj.
 
 		Modern Build Path (MSBuild Traversal SDK):
-		  dirs.proj → Build/Src/NativeBuild/NativeBuild.csproj → This file
+		  FieldWorks.proj → Build/Src/NativeBuild/NativeBuild.csproj → This file
 
 		Responsibilities:
 		1. Native C++ component builds (DebugProcs, GenericLib, FwKernel, Views)