dave
cdc6bb33d3
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>
91 lines
3.5 KiB
Markdown
91 lines
3.5 KiB
Markdown
# Contract: `Edit-PersonaEngineConfig.ps1`
|
||
|
||
Configuration validation, interactive editing, synthetic rule testing, and pipeline enforcement
|
||
(FR-023 – FR-026).
|
||
|
||
## Signature
|
||
|
||
```powershell
|
||
[CmdletBinding(SupportsShouldProcess = $true)]
|
||
param(
|
||
[Parameter(Mandatory)][string] $ConfigPath,
|
||
[Parameter()][switch] $ValidateOnly,
|
||
[Parameter()][switch] $NonInteractive,
|
||
[Parameter()][string] $SchemaPath,
|
||
[Parameter()][string] $OutputPath,
|
||
[Parameter()][switch] $TreatWarningsAsErrors,
|
||
[Parameter()][string] $TestDataPath
|
||
)
|
||
```
|
||
|
||
## Parameter contract
|
||
|
||
| Parameter | Behaviour |
|
||
| --- | --- |
|
||
| `-ConfigPath` | Required. Configuration to validate or edit. |
|
||
| `-ValidateOnly` | Validate and report; never enter the editor. |
|
||
| `-NonInteractive` | Pipeline mode. **MUST NOT prompt and MUST NOT hang** (SC-010). Returns an exit code. |
|
||
| `-SchemaPath` | Override the shipped schema. |
|
||
| `-OutputPath` | Save-As target; leaves the input file untouched. |
|
||
| `-TreatWarningsAsErrors` | Escalates `Warning` findings to blocking (VR-005). |
|
||
| `-TestDataPath` | Synthetic sample users for offline rule testing (FR-025). No tenant connectivity. |
|
||
|
||
## Validation layers (VR-001, ordered, fail-fast between layers)
|
||
|
||
| Layer | Mechanism | Example findings |
|
||
| --- | --- | --- |
|
||
| 1. Syntax | `ConvertFrom-Json` | Malformed JSON |
|
||
| 2. Schema | `Test-Json -SchemaFile` (draft-07, OTD-005) | Missing required field, wrong type, bad enum |
|
||
| 3. Semantic | PowerShell checks | Every condition in VR-002 |
|
||
| 4. Safety | PowerShell checks | Every condition in VR-003 |
|
||
|
||
A layer that produces `Error` findings stops the sequence — running semantic checks over a
|
||
structurally invalid document yields noise, not signal.
|
||
|
||
### Layer 2 error-handling requirement
|
||
|
||
`Test-Json` reports schema failure by writing errors rather than returning `$false` in several
|
||
PowerShell versions. The wrapper MUST invoke it with `-ErrorAction SilentlyContinue -ErrorVariable`
|
||
and convert collected errors into `ValidationFinding` objects, so layer 2 emits the same structured
|
||
shape as every other layer (VR-004).
|
||
|
||
## Finding contract
|
||
|
||
Every finding carries `Severity`, `Code`, `Location` (JSON path or rule ID), `Description`,
|
||
`SuggestedResolution`, and `Layer`. Finding codes are stable and namespaced by layer:
|
||
|
||
```text
|
||
PE-SYN-nnn syntax
|
||
PE-SCH-nnn schema
|
||
PE-SEM-nnn semantic (one code per VR-002 condition)
|
||
PE-SAF-nnn safety (one code per VR-003 condition)
|
||
```
|
||
|
||
Stability matters: pipelines and runbooks will match on these codes.
|
||
|
||
## Exit codes
|
||
|
||
| Code | Condition |
|
||
| --- | --- |
|
||
| `0` | Valid; no blocking findings |
|
||
| `1` | One or more `Error` findings |
|
||
| `2` | `Warning` findings present with `-TreatWarningsAsErrors` |
|
||
| `3` | Configuration file not found or unreadable |
|
||
| `4` | Schema file not found or itself invalid |
|
||
|
||
## Save contract (FR-026)
|
||
|
||
1. Re-validate the edited document in full.
|
||
2. Block the save on any `Error` finding.
|
||
3. Write a timestamped backup — or require `-OutputPath` — before replacing an existing file.
|
||
4. Overwriting the only valid configuration without a backup is a safety finding (VR-003), not
|
||
merely a warning.
|
||
|
||
## Invariants (test-asserted)
|
||
|
||
| Invariant | Assertion |
|
||
| --- | --- |
|
||
| Non-interactive never prompts | Runs to completion with stdin closed; no prompt, no hang (SC-010) |
|
||
| Every VR-002/VR-003 condition detected | One test per condition, each asserting code, severity, and location (SC-009) |
|
||
| Offline | Full validation and synthetic rule testing complete with no network access (SC-008) |
|