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,101 @@
+#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }
+
+<#
+    Pins the V-5a observation about Test-Json -SchemaFile.
+
+    OTD-005 chose a cmdlet whose failure reporting is version-dependent, and
+    validation layer 2 is written against the behaviour observed on PowerShell 7.6.5
+    (specs/001-persona-engine/verification/V-5a.md). If a future build changes any row
+    of that table, the wrapper's assumptions change with it - and the failure mode is
+    silent: configurations start passing validation that should not.
+
+    These tests fail loudly at that moment instead.
+#>
+
+BeforeAll {
+    $repoRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
+
+    $script:schemaFile = Join-Path ([System.IO.Path]::GetTempPath()) ("pe-pin-{0}.json" -f [guid]::NewGuid().ToString('N'))
+    Set-Content -LiteralPath $script:schemaFile -Encoding utf8NoBOM -Value @'
+{ "type": "object", "required": ["a"], "properties": { "a": { "type": "string" } } }
+'@
+
+    $script:brokenSchemaFile = Join-Path ([System.IO.Path]::GetTempPath()) ("pe-pin-broken-{0}.json" -f [guid]::NewGuid().ToString('N'))
+    Set-Content -LiteralPath $script:brokenSchemaFile -Encoding utf8NoBOM -Value '{ not json'
+}
+
+AfterAll {
+    Remove-Item -LiteralPath $script:schemaFile, $script:brokenSchemaFile -Force -ErrorAction SilentlyContinue
+}
+
+Describe 'Test-Json -SchemaFile failure behaviour (V-5a)' {
+
+    It 'returns $true and writes nothing for a valid document' {
+        $errors = $null
+        $result = '{ "a": "ok" }' | Test-Json -SchemaFile $script:schemaFile -ErrorAction SilentlyContinue -ErrorVariable errors
+
+        $result | Should -BeTrue
+        @($errors).Count | Should -Be 0
+    }
+
+    It 'returns $false and writes one error for a type mismatch' {
+        $errors = $null
+        $result = '{ "a": 123 }' | Test-Json -SchemaFile $script:schemaFile -ErrorAction SilentlyContinue -ErrorVariable errors
+
+        $result | Should -BeFalse
+        @($errors).Count | Should -Be 1
+    }
+
+    It 'returns $false and writes one error for a missing required property' {
+        $errors = $null
+        $result = '{}' | Test-Json -SchemaFile $script:schemaFile -ErrorAction SilentlyContinue -ErrorVariable errors
+
+        $result | Should -BeFalse
+        @($errors).Count | Should -Be 1
+    }
+
+    It 'reports failure without throwing, so -ErrorVariable is sufficient' {
+        # If a future build made this terminating, layer 2 would abort the run instead
+        # of returning findings, and the editor would report an exception rather than
+        # a PE-SCH finding.
+        { '{ "a": 123 }' | Test-Json -SchemaFile $script:schemaFile -ErrorAction SilentlyContinue } | Should -Not -Throw
+    }
+
+    It 'returns $TRUE when the schema itself cannot be parsed - the trap layer 2 is built around' {
+        # The load-bearing observation. A wrapper trusting the return value alone
+        # would report every configuration as schema-valid against a schema that
+        # never ran.
+        $errors = $null
+        $result = '{}' | Test-Json -SchemaFile $script:brokenSchemaFile -ErrorAction SilentlyContinue -ErrorVariable errors
+
+        $result | Should -BeTrue
+        @($errors).Count | Should -Be 1
+        $errors[0].Exception.Message | Should -Match 'Cannot parse the JSON schema'
+    }
+
+    It 'embeds a JSON pointer in the failure message, which VR-004 needs for Location' {
+        $errors = $null
+        $null = '{ "a": 123 }' | Test-Json -SchemaFile $script:schemaFile -ErrorAction SilentlyContinue -ErrorVariable errors
+
+        $errors[0].Exception.Message | Should -Match "at '/a'"
+    }
+
+    It 'reports one error per violating location when several properties fail' {
+        # Not exhaustive across nested subschemas, but not first-failure-only either.
+        # Layer 2 therefore emits one finding per collected error rather than assuming
+        # a single one.
+        $multiSchema = Join-Path ([System.IO.Path]::GetTempPath()) ("pe-pin-multi-{0}.json" -f [guid]::NewGuid().ToString('N'))
+        Set-Content -LiteralPath $multiSchema -Encoding utf8NoBOM -Value @'
+{ "type": "object", "required": ["a", "b"], "properties": { "a": { "type": "string" }, "b": { "type": "string" } } }
+'@
+        try {
+            $errors = $null
+            $null = '{ "a": 1, "b": 2 }' | Test-Json -SchemaFile $multiSchema -ErrorAction SilentlyContinue -ErrorVariable errors
+
+            @($errors).Count | Should -Be 2
+            ($errors | ForEach-Object { $_.Exception.Message }) -join ' ' | Should -Match "at '/a'"
+            ($errors | ForEach-Object { $_.Exception.Message }) -join ' ' | Should -Match "at '/b'"
+        }
+        finally { Remove-Item -LiteralPath $multiSchema -Force -ErrorAction SilentlyContinue }
+    }
+}