Add sync-drift watchdog test for instruction-templates vs instructions

[tablackburn]

Context

PR #17 found that instruction-templates/powershell.instructions.md had silently fallen behind instructions/powershell.instructions.md since release 0.8.12 (2026-01-14). Specifically: the $backupDirectory predefinition, the entire "Directory vs Path Naming" subsection, the $configurationPath/$documentsDirectory rename, and the $filePath predefinition + quoted 'Stop' in Error Handling were added to instructions/ but not propagated to instruction-templates/.

Effect: downstream repositories pulling from instruction-templates/ for ~4 months got stale examples that contradicted the rules in those examples (e.g., $configPath violates the shorthand rule, $userPath was misnamed for a directory).

The existing tests/Instructions.Tests.ps1 validates frontmatter, version consistency, and changelog format, but does not check content equivalence between the two mirror copies.

Request

Add a Pester test that catches sync drift between instruction-templates/ and instructions/ for any pair of files that exists in both directories.

Suggested approach

For each file present in both instruction-templates/ and instructions/:

1. Read both files' content
2. Compare. They should be identical (or, if the repo decides certain files can legitimately differ, the test should encode that exception explicitly)
3. Fail with a clear diff if they differ

Open question: should the test enforce strict equality, or should it tolerate certain known divergences (e.g., the active copy temporarily ahead during in-progress work)? Strict equality is simplest and matches the apparent intent (active = dogfood = should match what gets distributed), but might cause friction during multi-step refactors. A // AIM: drift-allowed comment marker is a possible escape hatch.

Acceptance criteria

• New test in tests/Instructions.Tests.ps1 (or a new test file) that fails when any mirrored *.instructions.md differs between the two directories
• Test runs as part of the existing Pester suite (no new CI workflow needed)
• Decision documented on whether divergence is ever allowed; mechanism added if so
• Existing tests still pass after the new test is added (i.e., the two directories are currently in sync — PR docs: Add line continuation guidance to PowerShell instructions (v0.8.13) #17 just brought them back into sync, so this should hold)

Related

• PR docs: Add line continuation guidance to PowerShell instructions (v0.8.13) #17 (docs: Add line continuation guidance to PowerShell instructions (v0.8.13) #17) — fixed the existing drift; this issue is to prevent recurrence
• 0.8.12 release commit — where the drift was introduced