personaEngine2/specs/001-persona-engine/contracts/cli-edit-persona-engine-config.md

Contract: Edit-PersonaEngineConfig.ps1

Configuration validation, interactive editing, synthetic rule testing, and pipeline enforcement (FR-023 – FR-026).

Signature

[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:

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

Interactive editor commands (FR-023, FR-027 – FR-030)

The interactive loop (entered when neither -ValidateOnly nor -NonInteractive is set) supports:

Command	Behaviour
List rules	Show every rule's priority, ID, persona, and enabled state.
Toggle a rule	Flip enabled on an existing rule.
Change a priority	Set a new numeric priority on an existing rule.
Add a rule	Prompt for every RE-001 field (id, name, description, priority, persona, enabled, and optional fields) and for the condition tree — nested all/any groups and, per leaf condition, the property/membership source, operator, and comparison value. Reject on the spot if the id or priority collides with an existing rule (FR-027).
Edit a rule	Select an existing rule by id; change any top-level field and/or the condition tree — add, edit, remove, or renest conditions and groups within MaxConditionDepth (FR-028).
Delete a rule	Select an existing rule by id; show its id, name, and priority and require explicit confirmation before removing it (FR-029).
Re-validate	Run all four validation layers against the in-memory document, including any unsaved add/edit/delete, and print findings without saving.
Run rule test	Evaluate the in-memory document (including unsaved structural edits) against -TestDataPath fixtures.
Save	Re-validate, then persist per the save contract below.
Quit	Warn if there are unsaved changes (including structural edits) before discarding them.

All structural edits (add/edit/delete) are applied to the in-memory document only. They are never written to -ConfigPath (or -OutputPath) until a Save re-validates the full document and that validation passes — the same rule that governs field-level edits (FR-030). A depth violation introduced by an add or edit is reported immediately using the same finding the runtime validator would produce, rather than deferred to the next save or re-validate.

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)