Repository navigation
Description
Plan the work for issue #222 (title: "Add ordering and idempotence property tests for pkg/aifirewall Plan and ValidateGuardrail", author 0x73746F66, OPEN, no linked PRs or branches). Deliverable: plan.md at the repository root. Do not change code; this is the plan step of the sys-issue-to-pr workflow (card K-32c9d7). The board's existing build card K-f8ff00 already owns the code step, so plan.md must name K-f8ff00 as owner of the code change.
Issue body (verified against the repo at HEAD, commit 21dd9ec):
Files: pkg/aifirewall/policy.go (Plan, sortChanges, ValidateGuardrail, Validate, Mutating, Export). Existing tests: pkg/aifirewall/policy_test.go (16 example tests). Evidence: Plan is a state machine (diff desired policy against ServerState into an ordered []Change). Its invariants are currently pinned only by hand-written cases: execution order is guardrails before models before providers before keys before settings; map iteration over server.Models/server.Providers is made deterministic via sortedKeys, but determinism and convergence are not checked. This is separate from the in-flight K-f7ac4f, which covers detect, clients, and helper paths in the same package; do not touch those.
Invariants to check:
- Ordering: for any desired PolicyFile and ServerState, Plan output respects the kind order guardrail(0) < model(1) < provider(2) < key(3) < settings(4), and is deterministic across runs on equal inputs.
- Idempotence/convergence: applying a plan's mutating changes (Mutating(Plan(...))) to the server and re-planning produces no further mutating changes.
- ValidateGuardrail is total: it returns an error for unknown ruleType/action and nil for each known (ruleType, action) pair the gateway enforces; it never panics for any string inputs.
Change: add pkg/aifirewall/plan_property_test.go using stdlib testing/quick for ValidateGuardrail inputs and a small generated table for Plan/ServerState. Keep within policy.go's surface.
Gates (from the issue): runnable go suite pkg/aifirewall; runnable go suite pkg/aifirewall narrowed to TestPlanOrderingDeterministic (name the new test); manual: new test touches only policy.go, not K-f7ac4f's detect/client/helper surface.
Verified at HEAD (all confirmed):
- pkg/aifirewall/policy.go defines Plan, sortChanges, ValidateGuardrail, Validate, Mutating, Export, ServerState, Kind/Op constants (KindGuardrail 0 < KindModel 1 < KindProvider 2 < KindKey 3 < KindSettings 4), sortedKeys. No plan_property_test.go exists.
- pkg/aifirewall/policy_test.go has exactly 16 test functions.
- go.mod: module github.com/vulnetix/cli/v4, go 1.25.0.
GOWORK=off go test ./pkg/aifirewall/passes at HEAD (ok, 0.080s). Use GOWORK=off in this repo so workspace overrides do not skew results.- Known Plan subtleties plan.md should account for: a kind's changes appear only when that input section is non-empty (kind order holds across whatever kinds are present); keys are planned per provider (KindKey changes are emitted inside the provider loop, so a KindKey change always follows the KindProvider change for the same slug); re-planning must feed back the mutating changes' effects (server.Models/Providers updated, guardrails added/updated with UUIDs, logsEnabled flipped) for the convergence check.
- ValidateGuardrail known vocabulary (policy.go lines 132-157): content ruleTypes blocked_pattern, max_messages, pii_redact, delimiter_integrity; capability ruleTypes tool_allow, tool_deny, mcp_allow, mcp_deny, skill_allow, skill_deny, client_allow, client_deny; actions block, redact, flag, strip. Cross-family restrictions: delimiter_integrity only block/flag and no pattern; redact only with content rule types; strip only with tool_allow/tool_deny/mcp_allow/mcp_deny.
Write plan.md with: the change, the files it touches (pkg/aifirewall/plan_property_test.go only), the tests that show it works (name the new test functions, e.g. TestPlanOrderingDeterministic, TestPlanConverges, TestValidateGuardrailTotal, TestValidateGuardrailNeverPanics), and a note that K-f8ff00 owns the code step.
Synced from Belai card K-8af608 on Vulnetix. Edit here or on the board; both update.
Activity
0x73746F66 commentedon Nov 12, 2026
The plan this card asks for is superseded: #222 is implemented in PR #326 (property tests for Plan ordering, determinism and convergence, and ValidateGuardrail; the determinism property found and fixed map-ordered drift/deletes in Plan). Nothing further is needed here; it can be closed from the board.
0x73746F66 commentedon Nov 14, 2026
Stale: plan-step artefact for #222, which is closed and implemented by #326 (4d829f3).