Implement Stage A: rule engine, validation, audit, and safety gates

Completes 109 of 121 tasks. Every remaining task needs a tenant connection (T055, T056, T101-T103) or an Azure Automation account (T115-T121). 354 offline Pester tests PASS Engine purity (Principle IV) PASS Sanitization (SC-013) PASS (156 files) Graph module loaded in tests none (SC-008 holds) What landed - Four-layer configuration validation with stable finding codes, covering every VR-002 and VR-003 condition, plus a 23-fixture invalid-config corpus - Run loop, audit records (NDJSON through a single sink), summaries, reconciliation, and exit codes 0-6 - Persistence behind a single write-body builder whose result always has exactly one key - Invoke-PersonaEngine.ps1 and Edit-PersonaEngineConfig.ps1 - Six docs, two pipelines, traceability matrix, V-5a and sanitization records Three deviations from tasks.md, each recorded in its status block T033 is not in Resolve-UserPersona. evaluationErrorThreshold is run-level state and the rule engine is pure; a counter there would break Principle IV. It lives in New-PersonaRunCounter and is applied in the run loop. A new src/Engine/ layer holds Invoke-PersonaEngineRun. The entry script imports the manifest, which requires Microsoft.Graph.Authentication, so a loop living only inside it could not run on a machine without the Graph SDK and SC-004 could not be proven at all. The entry script is now a thin wrapper and what ships is what is tested. The invalid-config corpus is generated by a committed script, with the generated fixtures committed too, so a reviewer sees the fixture in the diff. Defects found by running the code, not by reading it Group and role ID lists were double-wrapped: @(Get-PersonaGroupIdPage ...) around a comma-returned array collapsed every membership list into one bogus space-joined entry. That is a silent false non-match, exactly what FR-013 exists to prevent. A 403 whose status appears only in the exception message parsed as $null, which the retry policy treats as a transport error - five requests per account against a tenant already refusing. Status extraction now falls back to the message text, bounded to 400-599. The sanitization scan walked tracked files only, so it covered 34 of 156 files and none of this phase's code. It now scans untracked non-ignored files too, and a negative control confirms it catches a planted leak. Test-Json reports one error per violating location, not first-failure-only as the V-5a draft claimed. Record and pin corrected. Enforcement remains blocked on the V-4 security sign-off. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-20 21:48:19 -04:00
parent c59c85dd55
commit cdc6bb33d3
124 changed files with 16638 additions and 199 deletions
@@ -0,0 +1,175 @@
+#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }
+
+<#
+    SC-009, VR-003 half: every safety condition produces a finding.
+
+    Layer 3 asks whether a configuration makes sense. These tests are about layer 4,
+    which asks what happens to the directory if it runs - a coherent configuration can
+    still be a silent no-op or a change nobody declared.
+
+    Several findings change severity with -EnforcementEnabled. Both cases are asserted
+    for each: the same configuration carries very different risk in preview and in
+    enforcement, and a validator that ignored the difference would either block
+    harmless previews or wave through real writes.
+#>
+
+BeforeAll {
+    $repoRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
+    . (Join-Path $repoRoot 'tests/TestHelpers.ps1')
+    foreach ($file in (Get-PersonaSourceFile -RepoRoot $repoRoot)) { . $file }
+
+    $script:corpus = Join-Path $repoRoot 'tests/TestData/InvalidConfigs'
+    $script:baseline = Join-Path $script:corpus 'baseline-deployed.json'
+
+    function Get-SafetyFinding {
+        param(
+            [string] $Fixture,
+            [string] $Code,
+            [switch] $EnforcementEnabled,
+            [string] $PreviousConfigPath
+        )
+
+        $document = Get-Content -LiteralPath (Join-Path $script:corpus "$Fixture.json") -Raw | ConvertFrom-Json -Depth 32
+
+        $params = @{ Document = $document; EnforcementEnabled = $EnforcementEnabled }
+        if ($PreviousConfigPath) { $params['PreviousConfigPath'] = $PreviousConfigPath }
+
+        @(Test-PersonaConfigurationSafety @params | Where-Object Code -EQ $Code)
+    }
+}
+
+Describe 'Safety validation, VR-003 conditions (SC-009)' {
+
+    It 'detects a blank target attribute and blocks it under enforcement' {
+        $findings = Get-SafetyFinding -Fixture 'PE-SAF-001-blank-target-production' -Code 'PE-SAF-001' -EnforcementEnabled
+
+        $findings.Count | Should -Be 1
+        $findings[0].Severity | Should -Be 'Error'
+    }
+
+    It 'reports the same blank target attribute as a Warning in preview' {
+        # In preview there is nothing to write, so the configuration is merely
+        # pointless rather than dangerous.
+        $findings = Get-SafetyFinding -Fixture 'PE-SAF-001-blank-target-production' -Code 'PE-SAF-001'
+
+        $findings.Count | Should -Be 1
+        $findings[0].Severity | Should -Be 'Warning'
+    }
+
+    It 'detects an unsupported writable attribute' {
+        # 'department' is authoritative in the sync source. Holding permission to
+        # write it is not the same as owning it.
+        $findings = Get-SafetyFinding -Fixture 'PE-SAF-002-unsupported-writable-attribute' -Code 'PE-SAF-002'
+
+        $findings.Count | Should -BeGreaterThan 0
+        $findings[0].Severity | Should -Be 'Error'
+        $findings[0].Description | Should -Match 'department'
+    }
+
+    It 'detects enabled group rules while group retrieval is disabled' {
+        $findings = Get-SafetyFinding -Fixture 'PE-SAF-003-group-rules-without-group-retrieval' -Code 'PE-SAF-003'
+
+        $findings.Count | Should -BeGreaterThan 0
+        $findings[0].Severity | Should -Be 'Error'
+        $findings[0].Location | Should -Be 'dataSources.groups.enabled'
+    }
+
+    It 'detects a configuration version downgrade against the deployed baseline' {
+        $findings = Get-SafetyFinding -Fixture 'PE-SAF-004-version-downgrade' -Code 'PE-SAF-004' `
+            -PreviousConfigPath $script:baseline -EnforcementEnabled
+
+        $findings.Count | Should -BeGreaterThan 0
+        $findings[0].Severity | Should -Be 'Error'
+        $findings[0].Location | Should -Be 'configVersion'
+    }
+
+    It 'detects a rule removed without a version change' {
+        $findings = Get-SafetyFinding -Fixture 'PE-SAF-005-rule-removed-without-version-change' -Code 'PE-SAF-005' `
+            -PreviousConfigPath $script:baseline -EnforcementEnabled
+
+        $findings.Count | Should -BeGreaterThan 0
+        $findings[0].Severity | Should -Be 'Error'
+        $findings[0].Description | Should -Match 'RULE-0900-EMPLOYEE'
+    }
+
+    It 'accepts a rule removal when the version was raised to declare it' {
+        $document = Get-Content -LiteralPath (Join-Path $script:corpus 'PE-SAF-005-rule-removed-without-version-change.json') -Raw | ConvertFrom-Json -Depth 32
+        $document.configVersion = '1.1.0'
+
+        $findings = @(Test-PersonaConfigurationSafety -Document $document -PreviousConfigPath $script:baseline -EnforcementEnabled |
+                Where-Object Code -EQ 'PE-SAF-005')
+
+        $findings.Count | Should -Be 0
+    }
+
+    It 'detects condition tracing enabled without acknowledgement' {
+        $findings = Get-SafetyFinding -Fixture 'PE-SAF-006-tracing-without-acknowledgement' -Code 'PE-SAF-006'
+
+        $findings.Count | Should -Be 1
+        $findings[0].Severity | Should -Be 'Error'
+        $findings[0].Location | Should -Be 'logging.traceConditionValues'
+    }
+
+    It 'accepts tracing when it is acknowledged in the same configuration' {
+        $document = Get-Content -LiteralPath (Join-Path $script:corpus 'PE-SAF-006-tracing-without-acknowledgement.json') -Raw | ConvertFrom-Json -Depth 32
+        $document.logging | Add-Member -NotePropertyName 'acknowledgeConditionTracing' -NotePropertyValue $true
+
+        @(Test-PersonaConfigurationSafety -Document $document | Where-Object Code -EQ 'PE-SAF-006') | Should -BeNullOrEmpty
+    }
+
+    It 'detects a save that would overwrite an existing configuration with no backup' {
+        $document = Get-Content -LiteralPath $script:baseline -Raw | ConvertFrom-Json -Depth 32
+
+        $findings = @(Test-PersonaConfigurationSafety -Document $document -SavePath $script:baseline |
+                Where-Object Code -EQ 'PE-SAF-007')
+
+        $findings.Count | Should -Be 1
+        $findings[0].Severity | Should -Be 'Error'
+    }
+
+    It 'accepts the same save when a backup is planned' {
+        $document = Get-Content -LiteralPath $script:baseline -Raw | ConvertFrom-Json -Depth 32
+
+        @(Test-PersonaConfigurationSafety -Document $document -SavePath $script:baseline -BackupPlanned |
+            Where-Object Code -EQ 'PE-SAF-007') | Should -BeNullOrEmpty
+    }
+}
+
+Describe 'A skipped check is reported as skipped, never as a pass' {
+
+    It 'reports an Information finding when no baseline is supplied' {
+        # Silence would be read as approval. The comparison checks did not run, and
+        # the output has to say so.
+        $document = Get-Content -LiteralPath $script:baseline -Raw | ConvertFrom-Json -Depth 32
+
+        $findings = @(Test-PersonaConfigurationSafety -Document $document | Where-Object Code -EQ 'PE-SAF-004')
+
+        $findings.Count | Should -Be 1
+        $findings[0].Severity | Should -Be 'Information'
+        $findings[0].Description | Should -Match 'not a pass'
+    }
+
+    It 'does not block on the skipped-check notice' {
+        $document = Get-Content -LiteralPath $script:baseline -Raw | ConvertFrom-Json -Depth 32
+
+        @(Test-PersonaConfigurationSafety -Document $document | Where-Object Severity -EQ 'Error') | Should -BeNullOrEmpty
+    }
+}
+
+Describe 'Safety findings carry everything VR-004 requires' {
+
+    It 'gives every finding a severity, code, location, description, resolution, and layer' {
+        foreach ($fixture in (Get-ChildItem -Path $script:corpus -Filter 'PE-SAF-*.json')) {
+            $document = Get-Content -LiteralPath $fixture.FullName -Raw | ConvertFrom-Json -Depth 32
+
+            foreach ($finding in (Test-PersonaConfigurationSafety -Document $document -PreviousConfigPath $script:baseline)) {
+                $finding.Severity | Should -BeIn @('Error', 'Warning', 'Information')
+                $finding.Code | Should -Match '^PE-SAF-\d{3}$'
+                $finding.Location | Should -Not -BeNullOrEmpty
+                $finding.Description | Should -Not -BeNullOrEmpty
+                $finding.SuggestedResolution | Should -Not -BeNullOrEmpty
+                $finding.Layer | Should -Be 'Safety'
+            }
+        }
+    }
+}