Implementation Phasing & Maturity Plan
Purpose
This document defines what must be implemented now (before any serious UI/UX work) and what is intentionally deferred until Evalium matures as a product.
Its goal is to:
- Protect the backend from UX-driven churn
- Ensure defensibility primitives are first-class and uniform
- Prevent future features from bypassing core laws
- Give a solo developer a clear, low-cognitive-load execution order
This document is authoritative for sequencing, not priority inflation.
Guiding Principle
Primitives first. Workflows later. UX last.
If a capability cannot be expressed without screens, it is almost always too early.
Phase A — Mandatory Platform Primitives (Implement Now)
These items must exist before UI/UX work, even if they are completely invisible to users.
They define the laws of the system. Every feature must consume them.
Consumption Contract (Non-Negotiable)
All Phase A primitives are platform services, not feature-level concerns.
features are permitted to:
- Request lifecycle transitions
- Trigger executions that bind snapshots
- Propose amendments
- Read defensibility state
features are not permitted to:
- Manage lifecycle state directly
- Rewrite historical outcomes
- Bind or modify snapshots manually
- Emit amendment records ad hoc
- Implement feature-specific defensibility logic
Any new feature must explicitly declare:
- Which Phase A primitives it consumes
- The enforcement mode used (mandatory / optional / situational)
- Whether consumption is direct or inherited
Observation Consumption Map (Non-Negotiable)
| Observation capability | Phase A primitive(s) consumed |
|---|---|
| Findings enforcement (comment/evidence) | A3 Amendments, A7 Enforcement |
| Evidence capture & decisions | A3 Amendments, A7 Enforcement |
| Review & approval (four-eyes, auto-approve) | A1 Lifecycle, A7 Enforcement |
| Actor vs Subject attribution | A8 Identity & Attribution |
Batch grouping (batch_id) | A2 Snapshots, A7 Enforcement |
| Glass Box visibility | A5 Visibility Events |
A1. Canonical Lifecycle State Machine
Status: Mandatory
What must exist
- A single lifecycle model shared by all durable objects
- Canonical states (e.g. Draft, Active, Superseded, Corrected, Archived)
- Canonical review/approval states (e.g. Pending Review, Approved, Rejected)
- Legal transitions enforced centrally
- Transition metadata (actor, timestamp, reason where applicable)
Applies to
- Questions
- Evaluations
- Submissions
- Evidence
- Results
- Reports
Notes
- features may request transitions, never implement them
- UI must not invent states
A2. Snapshot Addressability Guarantee
Status: Mandatory
What must exist
- Immutable snapshot objects
- Every execution bound to exactly one snapshot
- Snapshot references stored with outcomes
- Ability to resolve "the world as it was then"
Notes
- Snapshots are automatic
- Users never manage snapshots directly
A3. Amendments as First-Class Events
Status: Mandatory
What must exist
-
Append-only amendment records
-
Typed amendments (correction, challenge, invalidation)
-
Mandatory provenance metadata:
- reason
- scope
- actor
- timestamp
Notes
- No feature may rewrite historical outcomes
- Recalculation without amendment is forbidden
A4. Delegated Authority Provenance
Status: Mandatory (Backend-only)
What must exist
- Optional authority reference on executions and amendments
- Ability to record "acting on behalf of" relationships
Notes
- This is provenance, not permissioning
- No workflow or UI required at this stage
A5. Observation & Visibility Events
Status: Mandatory (Lightweight)
What must exist
- Uniform emission of view / export / client-access events
- Minimal metadata (who, what, when, how)
- Glass Box view access is a visibility event
Notes
- This is not verbose logging
- Events are captured silently
A6. Retention Intent Markers
Status: Mandatory (Non-automated)
What must exist
- Retention intent fields (retain_until, basis, hold_flag)
- Defaults inherited hierarchically
Notes
- No deletion automation required
- Used to prevent accidental erasure
A7. Enforcement Mode Declaration
Status: Mandatory (Meta-primitive)
What must exist
-
Every defensibility capability declares an enforcement mode:
- mandatory
- optional
- situational
- future
Notes
- Used by scorecard, roadmap, and later UI
- Prevents accidental drift to over-compliance
A8. Identity & Attribution Primitive (Actor vs Subject)
Status: Mandatory
What must exist
- A first-class Subject abstraction distinct from Actor identity
- Durable linkage of submissions to subjects (people, assets, locations)
- RLS-safe visibility based on tenant/org scope and assignment context
Notes
- Actor = who performed/approved the work
- Subject = who/what the work is about
- This is a platform identity primitive, not an Observations-only feature
Phase A Status Snapshot (Current)
This is a quick, explicit checkpoint against the platform matrix. When this table and the matrix disagree, the matrix wins.
| Primitive | Status | Notes |
|---|---|---|
| A1 Canonical Lifecycle + Review States | Implemented | Approval status + review policy enforced across K/O/E. |
| A2 Snapshot Addressability | Implemented | Submissions bind immutable snapshots. |
| A3 Amendments as First-Class Events | Implemented | Remediation/amendment flows live. |
| A4 Delegated Authority Provenance | Implemented | Authority context captured on submissions/evidence and remediation actions. |
| A5 Observation & Visibility Events | Implemented | View/export/client-access events logged across submission/evidence/subjects/assignments/programmes/engagements. |
| A6 Retention Intent Markers | Implemented | Fields + defaults live; automation deferred by design. |
| A7 Enforcement Mode Declaration | Implemented | Enforcement mode registry seeded and referenced by scorecard. |
| A8 Identity & Attribution | Implemented | Subject abstraction + submission/assignment linkage + visibility rules live. |
Phase A is complete.
Phase B — Assurance Semantics (Document Now, Implement Later)
These capabilities build professional meaning on top of primitives.
They must be documented to prevent architectural drift. Backend foundations are implemented; workflow/UX expression remains intentionally deferred.
B1. Claim / Assertion Objects
- Durable professional verdicts
- reference evidence, snapshots, authority
- Carry lifecycle and validity windows
Status: Implemented (backend); workflow/UX deferred
B2. Explicit Validity Windows
- Start / end dates on claims
- Expiry without deletion
Status: Implemented (backend); workflow/UX deferred
B3. Formal Dispute Lifecycle
- Containers grouping challenges, responses, resolution
Status: Implemented (backend); workflow/UX deferred
B4. Active Evidence Integrity Verification
- Periodic or on-demand hash checks
Status: Implemented (backend); workflow/UX deferred
Phase B Status Snapshot (Current)
| Capability | Status | Notes |
|---|---|---|
| B1 Claim / Assertion Objects | Implemented (backend) | UX/workflow deferred. |
| B2 Explicit Validity Windows | Implemented (backend) | UX/workflow deferred. |
| B3 Formal Dispute Lifecycle | Implemented (backend) | UX/workflow deferred. |
| B4 Active Evidence Integrity Verification | Implemented (backend) | Worker and integrity checks in place; UX/workflow deferred. |
Phase C — UX & Workflow Expression (Later)
These phases surface existing guarantees to users.
C1. Progressive Disclosure UX
- Normal use remains calm
- Seriousness appears only when required
C2. Governance & Audit Views
- Explain
- History
- Dispute review
C3. Advanced Policy Controls
- Admin-only
- Situational enforcement
Uniformity Check (Required for New features)
Before a feature is considered complete, it must pass the following check:
- Does it rely on the canonical lifecycle state machine?
- Does it bind executions to a snapshot automatically?
- Does it express changes exclusively via amendments?
- Does it emit visibility or access events uniformly?
- Does it respect declared enforcement modes?
If any answer is no, the feature is incomplete and must be revised.
Explicit Anti-Goals
The following are intentionally avoided at early stages:
- Forcing users to configure defensibility
- UI-led implementation of invariants
- Feature-specific lifecycle logic
- Early enterprise compliance workflows
Definition of "Backend Complete"
The backend is considered "ready for UX" when:
-
All Phase A primitives are enforced
-
No feature can bypass lifecycle, snapshot, or amendment laws
-
All defensibility scorecard items are explainable as:
- implemented
- intentionally optional
- intentionally deferred
Only then should sustained UX work begin.
Relationship to Other Docs
- Defensibility Scorecard → Measures confidence, not backlog
- Engineering Roadmap → Sequences delivery
- Normal Use & Depth Discovery → Describes experience
- Language & Tone Guidelines → Enforces communication
This document defines when things should exist, not how they look.