Cross-Object Priority Enum Coercion and Parity Guide
Comprehensive architectural specification, operational guide, and invariant definition for Cross-Object Priority Enum Coercion and Parity (pkg/objects, pkg/validation, pkg/storage, cmd/zqk).
1. Executive Summary & Foundational Invariants
In the ZQK Knowledge Kernel, work prioritization operates across distinct ontological planes:
- Strategic Contract Plane (
requirement): Timeless feature contracts specifying what the system must deliver. Prioritization on requirements is expressed using relative urgency tiers:p0,p1,p2,p3. - Execution Delivery Plane (
backlog_item): Atomic units of effort grouped within 1-cycle Priority Plans. Prioritization on backlog items is expressed using human-legible severity/urgency labels:critical,high,medium,low, paired with an ontological tier:P0,P1,P2,P3.
Prior to this specification (resolved in GH-928 / TDE-001), differences between requirement priority strings (p0..p3) and backlog item priority strings (critical..low) caused friction during automated orchestration, bulk updates, and cross-object queries.
Under POL-DOC-001 and criteria CRIT-001, CRIT-001, and CRIT-001, this guide establishes:
- The authoritative bidirectional mapping between requirement tiers and backlog item labels.
- The operational normalization and coercion engine in
pkg/objectsandpkg/validation. - Fail-closed negative boundary rejection for invalid priority literals.
- Verification invariants for CLI mutations (
zqk object update).
+──────────────────────────────────────────────────────────────────────────+
│ Human Operator / Agent Swarms │
│ zqk object update <id> --field priority=<value> │
+──────────────────────────────────────────────────────────────────────────+
│
▼
+──────────────────────────────────────────────────────────────────────────+
│ Bidirectional Coercion Engine │
│ (pkg/objects, pkg/validation, pkg/storage) │
│ │
│ [ Input Detection ] ──► Accepts p-tier or word alias (case-insensitive) │
│ [ Kind Dispatch ] ──► requirement: "medium" ──► "p2" │
│ ──► backlog_item: "p2" ──► "medium" (tier P2) │
│ [ Boundary Check ] ──► "urgent" / "p4" ──► Reject with options │
+──────────────────────────────────────────────────────────────────────────+
│
▼
+──────────────────────────────────────────────────────────────────────────+
│ Persistent Knowledge Kernel CAS │
│ • requirement.priority: p0 | p1 | p2 | p3 │
│ • backlog_item.priority: critical | high | medium | low │
│ • backlog_item.priority_tier: P0 | P1 | P2 | P3 │
+──────────────────────────────────────────────────────────────────────────+
2. The Ontological Model: Requirements vs. Backlog Items
Requirements: Timeless Strategic Compass
- Ontological Role: Timeless functional contracts declaring feature invariants. Requirements exist outside of sprint cadence or release schedules.
- Priority Representation: Relative urgency tiers:
p0(highest urgency / blocker),p1(high urgency),p2(standard / normal urgency, default),p3(low urgency / deferred). - Parity Rule: When an operator or agent supplies word aliases (
critical,high,medium,low) to a requirement, the system automatically coerces the value to its canonical lowercase p-tier representation (p0,p1,p2,p3).
Backlog Items: Atomic Units of Execution
- Ontological Role: Tactical units of effort executed within a single Priority Plan cycle (2–5 BLIs per plan).
- Priority Representation: Word labels:
critical,high,medium,low. - Tier Synchronization: Backlog items additionally maintain
priority_tier(P0,P1,P2,P3) synchronized topriority. - Parity Rule: When an operator or agent supplies p-tier aliases (
p0,p1,p2,p3,P0..P3) to a backlog item, the system automatically coercespriorityto the canonical word label (critical,high,medium,low) and synchronizespriority_tierto the uppercase tier (P0,P1,P2,P3).
3. Bidirectional Priority Parity Matrix
The following table defines the normative mapping across all priority tiers and labels:
| Tier Rank | Requirement Priority (priority) |
Backlog Item Priority (priority) |
Backlog Item Tier (priority_tier) |
Semantics & Operational Urgency |
|---|---|---|---|---|
| 0 | p0 |
critical |
P0 |
System outage, blocker, critical release invariant |
| 1 | p1 |
high |
P1 |
Major milestone deliverable, primary capability |
| 2 | p2 |
medium |
P2 |
Standard feature scope, normal cycle delivery (default) |
| 3 | p3 |
low |
P3 |
Non-blocking enhancement, opportunistic task |
Case-Insensitive Acceptance
All validation and coercion entry points accept case-insensitive inputs:
- Requirement:
MEDIUM,Medium,medium,P2,p2all normalize top2. - Requirement:
CRITICAL,Critical,critical,P0,p0all normalize top0. - Backlog Item:
P2,p2,MEDIUM,Medium,mediumall normalize topriority: "medium"andpriority_tier: "P2". - Backlog Item:
P0,p0,CRITICAL,Critical,criticalall normalize topriority: "critical"andpriority_tier: "P0".
4. Operational Normalization & Coercion Engine
4.1 Package Architecture (pkg/objects)
PriorityToTier(priority string) (string, bool): Maps words (critical,high,medium,low) or p-tier strings (p0..p3) to uppercase tiers (P0..P3).TierToPriority(tier string) (string, bool): Maps uppercase tiers (P0..P3) or words to canonical lowercase words (critical,high,medium,low).IsLegitimatePriority(priority string) bool: Validates that a string is a recognized priority level (critical,high,medium,low) or tier alias (p0..p3), case-insensitively.IsLegitimatePriorityTier(tier string) bool: Validates that a string is a recognized tier (P0..P3) or word alias, case-insensitively.CoerceRequirementPriority(obj map[string]any): Normalizes requirement priority top0..p3.CoerceBacklogItemPriorityAndTier(obj map[string]any): Normalizes backlog item priority tocritical..lowand synchronizespriority_tiertoP0..P3.NormalizePriority(kind string, obj map[string]any): Unified kind-dispatched entry point.CoerceMutationFields(kind string, obj map[string]any): Invokes normalization across all create, update, and persist pipelines.
4.2 Validation Pipeline (pkg/validation)
NormalizePriority(kind string, obj map[string]any): Exposed inpkg/validationfor pipeline symmetry.GoValidator.Validate: CallsNormalizePriorityprior to SHACL shape inspection, ensuring that objects submitted with valid equivalent priorities pass schema validation seamlessly.ValidatePriority(kind string, priority string) error: Validates priority literals, returning an informative enum error on rejection.
4.3 Storage Pipeline (pkg/storage)
prepareFileObjectUpdate: ExecutesCoerceMutationFields(kind, updates)before value-restricted field validation, ensuring commands likezqk object update REQ-001 --field priority=mediumorzqk object update BLI-001 --field priority=p2succeed without schema constraint errors.mergeFileObjectUpdate: Synchronizespriorityandpriority_tierwhen only one field is mutated in an update payload.
5. Negative Adversarial Boundary & Fail-Closed Validation
Any priority literal outside the legitimate spectrum (p0..p3 and critical..low) must be cleanly and immediately rejected.
Disallowed Values
Values such as urgent, p4, p5, blocker, normal, unknown, tbd, or arbitrary strings are invalid.
Error Message Formatting
When an invalid value is supplied, validators emit an explicit error listing the allowed enum options:
field "priority" has invalid value "urgent"; must be one of: [critical, high, medium, low, p0, p1, p2, p3]
Or from schema enum validation:
Field priority must be one of: p0, p1, p2, p3, critical, high, medium, low
6. Verification & Test Case Traceability
This specification is verified by automated test suites satisfying the three-fold proof:
- Static Invariant Proof (
CRIT-001): - Verified by this specification:docs/guides/PRIORITY_ENUM_PARITY.md. - Operational Dynamic Proof (
CRIT-001): -pkg/validation/priority_enum_coercion_test.go:TestPriority_EnumCoercionAndParity- Unit tests covering bidirectional coercion across requirements (medium->p2) and backlog items (p2->medium,priority_tier: "P2"). - Validation test confirmingzqk object updatecompatibility for both kinds. - Negative Adversarial Boundary Proof (
CRIT-001): - Tests asserting that literalsurgent,p4,unknownfail with descriptive enum option errors.