Improve whitespace guidance and tooling (#767)

* Improve whitespace guidance and tooling

* Apply AI suggestions from code review

Co-authored-by: Copilot Autofix <175728472+Copilot@users.noreply.github.com>
Co-authored-by: papeh <hasso_pape@sil.org>

Author: 3 people

.github/instructions/repo.instructions.md

@@ -12,3 +12,6 @@ Provide clear, concise, and enforceable rules that help AI coding agents and aut
 ## Rules (high-impact, short)
 - Prefer the repository top-level build (`.\build.ps1`) and solution (`FieldWorks.sln`) for full builds.
 - Keep localization consistent: use `.resx` and follow `crowdin.json` for crowdin integration.
+- Before commit/push, run the existing VS Code task `CI: Full local check`.
+- After rebase/merge/cherry-pick conflict resolution, run `CI: Whitespace check`; if it fixes files, restage them and rerun.
+- When rewriting history or adding commits, run `CI: Commit messages` before pushing.

.github/instructions/terminal.instructions.md

@@ -13,6 +13,8 @@ Placement policy for wrappers:
 
 **MCP-first:** When the `ps-tools` MCP server is running, prefer MCP tools (`Git-Search`, `Read-FileContent`, `Invoke-AgentTask`, `build`, `test`, agent tools) instead of direct terminal commands. Use wrappers only when MCP is unavailable.
 
+**Task-first for CI parity:** Prefer the existing VS Code tasks `CI: Whitespace check`, `CI: Commit messages`, and `CI: Full local check` over ad-hoc shell commands. These tasks are already allowed for agent use and match the repository CI checks.
+
 ## Transformations
 
 | ❌ Blocked | ✅ Use Instead |

AGENTS.md

@@ -8,6 +8,10 @@ Minimal, high-signal guidance for coding agents in this repository.
 - Build with `.\build.ps1`.
 - Test with `.\test.ps1`.
 - Do not bypass repository scripts for normal build/test work.
+- Before committing or pushing, run the existing VS Code task `CI: Full local check`.
+- After any rebase, merge, cherry-pick, or manual conflict resolution, run `CI: Whitespace check` before committing.
+- If `CI: Whitespace check` rewrites files, review and restage those files, then rerun the task until it passes cleanly.
+- When commit history changes, run `CI: Commit messages` before pushing.
 
 ## Critical constraints
 
@@ -36,5 +40,6 @@ Minimal, high-signal guidance for coding agents in this repository.
 ## Validation checklist
 
 1. Run the relevant build/test scripts for touched areas.
-2. Keep edits scoped and avoid unrelated refactors.
-3. Update docs only when behavior/contracts/process changed.
+2. Run `CI: Full local check` before commit/push; use `CI: Whitespace check` immediately after conflict resolution.
+3. Keep edits scoped and avoid unrelated refactors.
+4. Update docs only when behavior/contracts/process changed.

Build/Agent/check-whitespace.ps1

@@ -85,6 +85,8 @@ Get-Content check-results.log | ForEach-Object {
 if ($problems.Count -gt 0) {
 	Write-Host "`u26A0`uFE0F Please review the output for further information."
 	Write-Host '### A whitespace issue was found in one or more of the commits.'
+	Write-Host 'This check validates commit history from origin/main..HEAD, not just the current working tree.'
+	Write-Host 'If the report names an older commit, fix the file and then amend, squash, or rebase so that commit no longer appears in the branch history.'
 	Write-Host ''
 	Write-Host 'Errors:'
 	$problems | ForEach-Object { Write-Host $_ }

Build/Agent/fix-whitespace.ps1

@@ -10,10 +10,39 @@ function Get-BaseRef {
 	return (Get-DefaultBranchRef)
 }
 
+function Test-HasUtf8Bom {
+	param([Parameter(Mandatory)][string]$Path)
+
+	# Read only the first three bytes to check for a UTF-8 BOM to avoid loading the entire file.
+	$buffer = [byte[]]::new(3)
+	$stream = [System.IO.File]::OpenRead($Path)
+	try {
+		$bytesRead = $stream.Read($buffer, 0, 3)
+	}
+	finally {
+		$stream.Dispose()
+	}
+
+	if ($bytesRead -lt 3) { return $false }
+	return $buffer[0] -eq 0xEF -and $buffer[1] -eq 0xBB -and $buffer[2] -eq 0xBF
+}
+
+function Write-Utf8Text {
+	param(
+		[Parameter(Mandatory)][string]$Path,
+		[Parameter(Mandatory)][string]$Content,
+		[Parameter(Mandatory)][bool]$EmitBom
+	)
+
+	$encoding = New-Object System.Text.UTF8Encoding($EmitBom)
+	[System.IO.File]::WriteAllText($Path, $Content, $encoding)
+}
+
 function Format-FileWhitespace {
 	param([Parameter(Mandatory)][string]$Path)
 	if (-not (Test-Path -LiteralPath $Path)) { return }
 	try {
+		$hasUtf8Bom = Test-HasUtf8Bom -Path $Path
 		$raw = Get-Content -LiteralPath $Path -Raw -Encoding utf8
 	}
  catch {
@@ -33,7 +62,7 @@ function Format-FileWhitespace {
 	# Join back and ensure exactly one trailing newline
 	$new = ($lines -join "`n") + "`n"
 	if ($new -ne $orig) {
-		Set-Content -LiteralPath $Path -Value $new -Encoding utf8 -NoNewline
+		Write-Utf8Text -Path $Path -Content $new -EmitBom $hasUtf8Bom
 		Write-Host "Fixed whitespace: $Path"
 	}
 }
@@ -56,5 +85,6 @@ $files = $fixFiles | Where-Object { $_ -and (Test-Path $_) }
 
 foreach ($f in $files) { Format-FileWhitespace -Path $f }
 
-Write-Host "Whitespace fix completed. Review changes, commit, and rebase as needed."
+Write-Host "Whitespace fix completed. Review and stage the updated files before committing."
+Write-Host "If check-whitespace reported an older commit in origin/main..HEAD, rewrite history with amend, squash, or rebase so that offending commit is no longer part of the branch."
 exit 0