@danmoisan/drm-copilot-mcp 0.0.1

package/resources/claude-customizations/.claude/hooks/validate-planner-output.ps1

@@ -0,0 +1,288 @@
+<#
+.SYNOPSIS
+    SubagentStop hook for the atomic-planner subagent.
+
+.DESCRIPTION
+    Blocks termination of the atomic-planner subagent unless the agent's final
+    output advertises a plan-path, includes an exact preflight signal, and the
+    advertised plan file satisfies the repository's mechanical atomic-plan
+    structure requirements.
+
+    Enforced checks:
+      - hook payload is valid JSON and contains non-empty output,
+      - output advertises `plan-path: <path>` (or supported equivalent forms),
+      - output contains `PREFLIGHT: ALL CLEAR` or
+        `PREFLIGHT: REVISIONS REQUIRED`,
+      - the advertised plan exists on disk,
+      - the plan contains canonical `### Phase N - <Title>` headings,
+      - Phase 0 exists and includes policy-read and baseline tasks,
+      - each task uses `- [ ] [P#-T#]` (or checked equivalent),
+      - task numbering is sequential within each phase,
+      - every task includes at least one explicit path token,
+      - the final phase contains QA-oriented work.
+
+.NOTES
+    Reads the hook payload from CLAUDE_HOOK_INPUT as JSON. Exits 0 to allow
+    termination; exits 1 with an error message to block. Filesystem reads go
+    through Get-PlanFileContent so tests can mock the boundary without writing
+    temporary files.
+#>
+
+[CmdletBinding()]
+param()
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+function Get-PlanFileContent {
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $Path
+    )
+
+    if (-not (Test-Path -LiteralPath $Path -PathType Leaf)) {
+        return @{ Exists = $false; Lines = @() }
+    }
+
+    $lines = Get-Content -LiteralPath $Path -ErrorAction Stop
+    if ($null -eq $lines) {
+        $lines = @()
+    }
+    elseif ($lines -isnot [array]) {
+        $lines = @($lines)
+    }
+
+    return @{ Exists = $true; Lines = $lines }
+}
+
+function Get-PlanPathFromOutput {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $AgentOutput
+    )
+
+    $pattern = 'plan-path\s*[:=]\s*["'']?([^\s"''\)`]+)|\[plan-path\]\(([^)]+)\)'
+    $match = [regex]::Match(
+        $AgentOutput,
+        $pattern,
+        [System.Text.RegularExpressions.RegexOptions]::IgnoreCase
+    )
+    if (-not $match.Success) {
+        return $null
+    }
+
+    $value = if ($match.Groups[1].Success) { $match.Groups[1].Value } else { $match.Groups[2].Value }
+    $value = $value.Trim()
+    if ([string]::IsNullOrWhiteSpace($value)) {
+        return $null
+    }
+
+    return $value
+}
+
+function Test-TaskContainsExplicitPath {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $TaskText
+    )
+
+    $pathPattern = '(?i)(?:[.\w*?-]+[\\/])+[.\w*?-]+'
+    return [regex]::IsMatch($TaskText, $pathPattern)
+}
+
+function Test-HasPreflightSignal {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $AgentOutput
+    )
+
+    return [regex]::IsMatch(
+        $AgentOutput,
+        '(?m)^\s*PREFLIGHT:\s*(ALL CLEAR|REVISIONS REQUIRED)\s*$'
+    )
+}
+
+function Get-PlanStructureValidationReport {
+    [CmdletBinding()]
+    [OutputType([string[]])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string[]] $Lines
+    )
+
+    $phasePattern = '^### Phase (?<Phase>\d+)\s+-\s+(?<Title>.+)$'
+    $taskPattern = '^- \[(?<State>[ xX])\] \[P(?<Phase>\d+)-T(?<Task>\d+)\] (?<Text>.+)$'
+    $errors = [System.Collections.Generic.List[string]]::new()
+    $tasksByPhase = @{}
+    $phaseTitles = @{}
+    $currentPhase = $null
+    $expectedPhase = 0
+    $foundTask = $false
+
+    for ($i = 0; $i -lt $Lines.Count; $i++) {
+        $lineNumber = $i + 1
+        $line = $Lines[$i]
+
+        if ($line -match '^### Phase ') {
+            $phaseMatch = [regex]::Match($line, $phasePattern)
+            if (-not $phaseMatch.Success) {
+                $errors.Add("Line ${lineNumber}: phase heading must match `### Phase N - <Title>`.")
+                $currentPhase = $null
+                continue
+            }
+
+            $phaseNumber = [int]$phaseMatch.Groups['Phase'].Value
+            if ($phaseNumber -ne $expectedPhase) {
+                $errors.Add("Line ${lineNumber}: expected Phase $expectedPhase but found Phase $phaseNumber.")
+                $expectedPhase = $phaseNumber
+            }
+
+            $currentPhase = $phaseNumber
+            $expectedPhase = $phaseNumber + 1
+            $tasksByPhase[$phaseNumber] = [System.Collections.Generic.List[string]]::new()
+            $phaseTitles[$phaseNumber] = $phaseMatch.Groups['Title'].Value.Trim()
+            continue
+        }
+
+        if ($line -notmatch '^- \[') {
+            continue
+        }
+
+        $foundTask = $true
+        $taskMatch = [regex]::Match($line, $taskPattern)
+        if (-not $taskMatch.Success) {
+            $errors.Add("Line ${lineNumber}: task line must match `- [ ] [P#-T#] <description>`.")
+            continue
+        }
+
+        if ($null -eq $currentPhase) {
+            $errors.Add("Line ${lineNumber}: task appears before the first canonical phase heading.")
+            continue
+        }
+
+        $taskPhase = [int]$taskMatch.Groups['Phase'].Value
+        $taskNumber = [int]$taskMatch.Groups['Task'].Value
+        $taskText = $taskMatch.Groups['Text'].Value.Trim()
+
+        if ($taskPhase -ne $currentPhase) {
+            $errors.Add("Line ${lineNumber}: task phase P$taskPhase does not match current phase $currentPhase.")
+        }
+
+        if (-not $tasksByPhase.ContainsKey($taskPhase)) {
+            $tasksByPhase[$taskPhase] = [System.Collections.Generic.List[string]]::new()
+        }
+        $expectedTaskNumber = $tasksByPhase[$taskPhase].Count + 1
+        if ($taskNumber -ne $expectedTaskNumber) {
+            $errors.Add("Line ${lineNumber}: expected task number T$expectedTaskNumber for phase $taskPhase, found T$taskNumber.")
+        }
+
+        if (-not (Test-TaskContainsExplicitPath -TaskText $taskText)) {
+            $errors.Add("Line ${lineNumber}: task [P$taskPhase-T$taskNumber] must include at least one explicit path.")
+        }
+
+        $tasksByPhase[$taskPhase].Add($taskText)
+    }
+
+    if ($phaseTitles.Count -eq 0) {
+        $errors.Add('Plan does not contain any canonical phase headings.')
+        return [string[]]@($errors)
+    }
+
+    if (-not $foundTask) {
+        $errors.Add('Plan does not contain any canonical task lines.')
+    }
+
+    if (-not $tasksByPhase.ContainsKey(0) -or $tasksByPhase[0].Count -eq 0) {
+        $errors.Add('Plan must include Phase 0 with at least one baseline task.')
+    }
+    else {
+        $phaseZeroText = ($tasksByPhase[0] -join "`n")
+        if ($phaseZeroText -notmatch '(?i)\b(policy|instruction|read)\b') {
+            $errors.Add('Phase 0 must include a policy-read task.')
+        }
+        if ($phaseZeroText -notmatch '(?i)\bbaseline\b') {
+            $errors.Add('Phase 0 must include a baseline task.')
+        }
+    }
+
+    $maxPhaseMeasure = ($phaseTitles.Keys | Measure-Object -Maximum).Maximum
+    $maxPhase = if ($null -eq $maxPhaseMeasure) { $null } else { [int]$maxPhaseMeasure }
+    $finalPhaseText = ''
+    if ($null -ne $maxPhase -and $tasksByPhase.ContainsKey($maxPhase)) {
+        $finalPhaseText = (($phaseTitles[$maxPhase]), ($tasksByPhase[$maxPhase] -join "`n")) -join "`n"
+    }
+    if ([string]::IsNullOrWhiteSpace($finalPhaseText) -or $finalPhaseText -notmatch '(?i)(qa|quality|toolchain|format|lint|type|test|coverage)') {
+        $errors.Add('The final phase must contain explicit QA or toolchain validation work.')
+    }
+
+    return [string[]]@($errors)
+}
+
+function Invoke-PlannerOutputValidation {
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [string] $RawPayload
+    )
+
+    if ([string]::IsNullOrWhiteSpace($RawPayload)) {
+        return @{ Ok = $false; Message = 'atomic-planner hook: CLAUDE_HOOK_INPUT is empty; cannot validate planner output.' }
+    }
+
+    try {
+        $payload = $RawPayload | ConvertFrom-Json -ErrorAction Stop
+    }
+    catch {
+        return @{ Ok = $false; Message = "atomic-planner hook: failed to parse CLAUDE_HOOK_INPUT as JSON: $($_.Exception.Message)" }
+    }
+
+    $agentOutput = $null
+    if ($payload.PSObject.Properties.Name -contains 'output') {
+        $agentOutput = $payload.output
+    }
+    if ([string]::IsNullOrWhiteSpace($agentOutput)) {
+        return @{ Ok = $false; Message = 'atomic-planner hook: agent output is empty; planner must return plan-path and final preflight signal.' }
+    }
+
+    if (-not (Test-HasPreflightSignal -AgentOutput $agentOutput)) {
+        return @{ Ok = $false; Message = 'atomic-planner hook: agent output must include `PREFLIGHT: ALL CLEAR` or `PREFLIGHT: REVISIONS REQUIRED`.' }
+    }
+
+    $planPath = Get-PlanPathFromOutput -AgentOutput $agentOutput
+    if ($null -eq $planPath) {
+        return @{ Ok = $false; Message = 'atomic-planner hook: agent output does not advertise a plan-path. Planner must report `plan-path: <path>` per atomic-plan-contract.' }
+    }
+
+    $file = Get-PlanFileContent -Path $planPath
+    if (-not $file.Exists) {
+        return @{ Ok = $false; Message = "atomic-planner hook: planner advertised plan-path '$planPath' but no file exists at that location." }
+    }
+
+    $errors = @(Get-PlanStructureValidationReport -Lines $file.Lines)
+    if ($errors.Count -gt 0) {
+        $message = "atomic-planner hook: plan '$planPath' violates the atomic plan contract:`n  - " + ($errors -join "`n  - ")
+        return @{ Ok = $false; Message = $message }
+    }
+
+    return @{ Ok = $true; Message = $null }
+}
+
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+$result = Invoke-PlannerOutputValidation -RawPayload $env:CLAUDE_HOOK_INPUT
+if (-not $result.Ok) {
+    Write-Error $result.Message
+    exit 1
+}
+
+exit 0

package/resources/claude-customizations/.claude/hooks/validate-required-artifact-output.ps1

@@ -0,0 +1,171 @@
+<#
+.SYNOPSIS
+    Generic SubagentStop hook for agents that must advertise exact artifact paths.
+
+.DESCRIPTION
+    Validates that the hook payload is well-formed JSON, the agent output is
+    non-empty, each required artifact token is advertised in the output, the
+    advertised path matches the configured contract regex, and the file exists
+    on disk.
+
+    Each required artifact spec must use:
+        token|regex|description
+
+    Example:
+        spec-path|^docs/features/active/.+/spec\.md$|spec artifact
+
+.NOTES
+    Reads the hook payload from CLAUDE_HOOK_INPUT as JSON. Exits 0 to allow
+    termination; exits 1 with an error message to block. Filesystem existence
+    checks go through Test-ArtifactFile so tests can mock the boundary without
+    writing temporary files.
+#>
+
+[CmdletBinding()]
+param(
+    [string] $AgentName,
+
+    [string[]] $RequiredArtifact
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+function Test-ArtifactFile {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $Path
+    )
+
+    return [bool](Test-Path -LiteralPath $Path -PathType Leaf)
+}
+
+function ConvertTo-ArtifactSpec {
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $Spec
+    )
+
+    $parts = $Spec -split '\|', 3
+    if ($parts.Count -ne 3) {
+        throw "Invalid artifact spec '$Spec'. Expected format: token|regex|description."
+    }
+
+    return @{
+        Token       = $parts[0].Trim()
+        Pattern     = $parts[1].Trim()
+        Description = $parts[2].Trim()
+    }
+}
+
+function Get-ArtifactPathFromOutput {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $AgentOutput,
+
+        [Parameter(Mandatory = $true)]
+        [string] $Token
+    )
+
+    $escapedToken = [regex]::Escape($Token)
+    $pattern = "$escapedToken\s*[:=]\s*[""']?([^\s""'\)`]+)|\[$escapedToken\]\(([^)]+)\)"
+    $match = [regex]::Match($AgentOutput, $pattern, [System.Text.RegularExpressions.RegexOptions]::IgnoreCase)
+    if (-not $match.Success) {
+        return $null
+    }
+
+    $value = if ($match.Groups[1].Success) { $match.Groups[1].Value } else { $match.Groups[2].Value }
+    $value = $value.Trim()
+    if ([string]::IsNullOrWhiteSpace($value)) {
+        return $null
+    }
+
+    return $value
+}
+
+function Invoke-RequiredArtifactOutputValidation {
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [string] $RawPayload,
+        [string] $AgentName,
+        [string[]] $RequiredArtifact
+    )
+
+    if ([string]::IsNullOrWhiteSpace($RawPayload)) {
+        return @{ Ok = $false; Message = "$AgentName hook: CLAUDE_HOOK_INPUT is empty; cannot validate required artifact output." }
+    }
+
+    try {
+        $payload = $RawPayload | ConvertFrom-Json -ErrorAction Stop
+    }
+    catch {
+        return @{ Ok = $false; Message = "$AgentName hook: failed to parse CLAUDE_HOOK_INPUT as JSON: $($_.Exception.Message)" }
+    }
+
+    $agentOutput = $null
+    if ($payload.PSObject.Properties.Name -contains 'output') {
+        $agentOutput = $payload.output
+    }
+    if ([string]::IsNullOrWhiteSpace($agentOutput)) {
+        return @{ Ok = $false; Message = "$AgentName hook: agent output is empty; artifact paths must be reported before termination." }
+    }
+
+    $errors = [System.Collections.Generic.List[string]]::new()
+    foreach ($specText in $RequiredArtifact) {
+        try {
+            $spec = ConvertTo-ArtifactSpec -Spec $specText
+        }
+        catch {
+            return @{ Ok = $false; Message = "$AgentName hook: $($_.Exception.Message)" }
+        }
+
+        $path = Get-ArtifactPathFromOutput -AgentOutput $agentOutput -Token $spec.Token
+        if ($null -eq $path) {
+            $errors.Add("missing $($spec.Token): <path> for the required $($spec.Description)")
+            continue
+        }
+
+        if (-not [regex]::IsMatch($path, $spec.Pattern)) {
+            $errors.Add("$($spec.Token) '$path' does not match the required location for the $($spec.Description)")
+            continue
+        }
+
+        if (-not (Test-ArtifactFile -Path $path)) {
+            $errors.Add("$($spec.Token) '$path' was advertised for the $($spec.Description) but no file exists at that location")
+        }
+    }
+
+    if ($errors.Count -gt 0) {
+        $message = "$AgentName hook: required artifact validation failed:`n  - " + ($errors -join "`n  - ")
+        return @{ Ok = $false; Message = $message }
+    }
+
+    return @{ Ok = $true; Message = $null }
+}
+
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+if ([string]::IsNullOrWhiteSpace($AgentName) -or $null -eq $RequiredArtifact -or $RequiredArtifact.Count -eq 0) {
+    Write-Error 'validate-required-artifact-output hook: AgentName and at least one RequiredArtifact spec are required.'
+    exit 1
+}
+
+$result = Invoke-RequiredArtifactOutputValidation `
+    -RawPayload $env:CLAUDE_HOOK_INPUT `
+    -AgentName $AgentName `
+    -RequiredArtifact $RequiredArtifact
+if (-not $result.Ok) {
+    Write-Error $result.Message
+    exit 1
+}
+
+exit 0

package/resources/claude-customizations/.claude/hooks/validate-task-researcher-output.ps1

@@ -0,0 +1,142 @@
+<#
+.SYNOPSIS
+    SubagentStop hook for the task-researcher subagent.
+
+.DESCRIPTION
+    Blocks termination of the task-researcher subagent unless the agent's
+    final output advertises a `research-path` token, the path is rooted
+    under artifacts/research/, matches the documented filename convention,
+    and the file exists on disk.
+
+.NOTES
+    Reads the hook payload from CLAUDE_HOOK_INPUT as JSON. Exits 0 to allow
+    termination; exits 1 with an error message to block. Filesystem reads go
+    through Test-ResearchFile so tests can mock the boundary without writing
+    temporary files.
+#>
+
+[CmdletBinding()]
+param()
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+function Test-ResearchFile {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $Path
+    )
+
+    return [bool](Test-Path -LiteralPath $Path -PathType Leaf)
+}
+
+function Get-ResearchPathFromOutput {
+    [CmdletBinding()]
+    [OutputType([string])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $AgentOutput
+    )
+
+    $pattern = 'research-path\s*[:=]\s*["'']?([^\s"''\)`]+)|\[research-path\]\(([^)]+)\)'
+    $match = [regex]::Match($AgentOutput, $pattern, [System.Text.RegularExpressions.RegexOptions]::IgnoreCase)
+    if (-not $match.Success) {
+        return $null
+    }
+
+    $value = if ($match.Groups[1].Success) { $match.Groups[1].Value } else { $match.Groups[2].Value }
+    $value = $value.Trim()
+    if ([string]::IsNullOrWhiteSpace($value)) {
+        return $null
+    }
+
+    return $value
+}
+
+function Test-IsUnderResearchRoot {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $Path
+    )
+
+    $normalized = $Path -replace '\\', '/'
+    return $normalized.StartsWith('artifacts/research/', [System.StringComparison]::OrdinalIgnoreCase)
+}
+
+function Test-IsValidResearchFileName {
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $Path
+    )
+
+    $normalized = $Path -replace '\\', '/'
+    $fileName = [System.IO.Path]::GetFileName($normalized)
+    return [regex]::IsMatch(
+        $fileName,
+        '^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-[A-Za-z0-9][A-Za-z0-9-]*-research\.md$'
+    )
+}
+
+function Invoke-TaskResearcherOutputValidation {
+    [CmdletBinding()]
+    [OutputType([hashtable])]
+    param(
+        [string] $RawPayload
+    )
+
+    if ([string]::IsNullOrWhiteSpace($RawPayload)) {
+        return @{ Ok = $false; Message = 'task-researcher hook: CLAUDE_HOOK_INPUT is empty; cannot validate task-researcher output.' }
+    }
+
+    try {
+        $payload = $RawPayload | ConvertFrom-Json -ErrorAction Stop
+    }
+    catch {
+        return @{ Ok = $false; Message = "task-researcher hook: failed to parse CLAUDE_HOOK_INPUT as JSON: $($_.Exception.Message)" }
+    }
+
+    $agentOutput = $null
+    if ($payload.PSObject.Properties.Name -contains 'output') {
+        $agentOutput = $payload.output
+    }
+    if ([string]::IsNullOrWhiteSpace($agentOutput)) {
+        return @{ Ok = $false; Message = 'task-researcher hook: agent output is empty; researcher must return research-path before termination.' }
+    }
+
+    $researchPath = Get-ResearchPathFromOutput -AgentOutput $agentOutput
+    if ($null -eq $researchPath) {
+        return @{ Ok = $false; Message = 'task-researcher hook: agent output does not advertise a research-path. Researcher must report `research-path: <path>` pointing to artifacts/research/.' }
+    }
+
+    if (-not (Test-IsUnderResearchRoot -Path $researchPath)) {
+        return @{ Ok = $false; Message = "task-researcher hook: research-path '$researchPath' is not under artifacts/research/. All research artifacts must be written to artifacts/research/." }
+    }
+
+    if (-not (Test-IsValidResearchFileName -Path $researchPath)) {
+        return @{ Ok = $false; Message = "task-researcher hook: research-path '$researchPath' does not match the required filename convention `artifacts/research/<timestamp>-<short-name>-research.md`." }
+    }
+
+    if (-not (Test-ResearchFile -Path $researchPath)) {
+        return @{ Ok = $false; Message = "task-researcher hook: researcher advertised research-path '$researchPath' but no file exists at that location." }
+    }
+
+    return @{ Ok = $true; Message = $null }
+}
+
+if ($MyInvocation.InvocationName -eq '.') {
+    return
+}
+
+$result = Invoke-TaskResearcherOutputValidation -RawPayload $env:CLAUDE_HOOK_INPUT
+if (-not $result.Ok) {
+    Write-Error $result.Message
+    exit 1
+}
+
+exit 0

package/resources/claude-customizations/.claude/rules/csharp.md

@@ -0,0 +1,62 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.csproj"
+description: C#-specific toolchain and coding standards.
+---
+
+# C# Code Standards
+
+This rule file summarizes the C#-specific policies for this repository.
+
+## Toolchain
+
+1. **Formatting — CSharpier**: All C# source files must be formatted with CSharpier. Do not use `dotnet format`. Command: `dotnet tool run csharpier .` or `csharpier .`
+2. **Linting — .NET Analyzers**: C# code must pass Roslyn/.NET analyzer diagnostics. Command: `msbuild TaskMaster.sln /t:Build /p:Configuration=Debug /p:Platform="Any CPU" /p:EnableNETAnalyzers=true /p:EnforceCodeStyleInBuild=true`
+3. **Type Checking — Nullable Analysis**: Enable nullable reference types and fail on warnings. Command: `msbuild TaskMaster.sln /t:Build /p:Configuration=Debug /p:Platform="Any CPU" /p:Nullable=enable /p:TreatWarningsAsErrors=true`
+4. **Testing — MSTest + Moq + FluentAssertions**: Run tests with: `vstest.console.exe <test-assembly-paths> /EnableCodeCoverage`
+
+Run the toolchain in order: format → lint → type-check → test. Restart from step 1 if any step fails or changes files.
+
+## Coding Standards
+
+- **Naming**: `PascalCase` for types and public members. `camelCase` for locals and private fields/parameters.
+- **Null safety**: Keep nullable reference types enabled. Model optional values with nullable annotations and guard clauses.
+- **Composition over inheritance**: Keep classes cohesive and scoped to one responsibility. Favor composition unless polymorphism is a clear requirement.
+- **Async/await**: Use `async`/`await` for I/O-bound operations. Prefer `using`/`await using` for disposable resources.
+- **Exceptions**: Fail fast with explicit exceptions. Avoid broad `catch (Exception)` unless at a defined boundary with added context.
+- **Public surface**: Keep public API surface intentional and minimal. Prefer `internal` for non-public APIs.
+- **XML docs**: Public APIs should include XML documentation comments when behavior or contract is non-obvious.
+
+## Testing Standards
+
+- Use **MSTest** (`Microsoft.VisualStudio.TestTools.UnitTesting`) as the test framework.
+- Use **Moq** for mocking.
+- Prefer **FluentAssertions** for assertions; use MSTest `Assert` only when FluentAssertions is not practical.
+- Use `[TestClass]` and `[TestMethod]` attributes.
+- Follow Arrange–Act–Assert structure.
+- No external dependencies in unit tests.
+- Repository-wide line coverage must remain >= 80%.
+- Any new module, class, or method must reach >= 90% coverage.
+- Coverage regression on changed lines is a blocking finding.
+
+## Deterministic Test Rules
+
+Unit tests must not depend on network, mutable machine PATH or profile state, implicit working-directory assumptions, or external services. Use seam-based mocking for all external boundaries (processes, HTTP, filesystem, clocks). Tests must produce identical results in the IDE test runner and in CLI runs so local and CI behavior agree.
+
+## DI Seams
+
+Introduce the smallest seam that enables reliable unit testing. Apply in this order of preference:
+
+1. **Interface seam (preferred)** — extract boundary calls into narrow purpose-specific interfaces (for example, `IProcessRunner`, `IFileSystem`, `IClock`). Keep interfaces minimal.
+2. **Injectable delegate seam** — use a narrow `Func<>`/`Action<>` delegate for a single call path when a full interface is excessive. Default behavior must remain safe and deterministic.
+3. **Adapter seam for static or third-party APIs** — wrap the static or third-party call behind a small adapter so tests can mock the adapter with Moq.
+
+## Prohibited Behaviors
+
+- Broad refactors across unrelated projects or files.
+- Introducing heavy generic abstraction frameworks without need.
+- Creating analyzer debt and deferring cleanup.
+- Weakening assertions or relaxing test expectations to make tests pass.
+- Adding sleeps, retries, or timing hacks to mask flaky behavior.
+- Reporting success without running the required toolchain.