- Five levels: Reality → Digital Representation → Current State → Intelligence → Prediction
- Unique value: Every object gets a life history
- Not a digital twin focused on visualization
- Focus: verified observations, changes over time, decision support, business value
- Living operational model that improves with each verified observation
Vision:
LandveX is a continuously updated operational model of the customer's
infrastructure that combines verified observations, history, and decision
support to help organizations prioritize the right actions at the right time.
Complements Product Levels, Platform Architecture, Engineering Standard.
Next: Pilot 001 — break the system!
- Level 0: Public (free) — open map, trends, heatmaps
- Level 1: Professional — own areas, dashboard, reports
- Level 2: Enterprise — AI rules, Mission Engine, Hotspots, Credits
- Level 3: Platform — multi-org, custom models, white-label, federation
Design Principle: Progressive Disclosure
- Default: very simple
- Advanced: more detail on same page
- Same Decision Case, different detail levels
Core Principle:
All users work in same LandveX platform.
License determines intelligence depth, not objects.
Complements Platform Architecture v2.0 and Engineering Standard v1.0.
Next: Pilot 001 — break the system!
- API running on port 3002
- UI running on port 3003
- Version endpoint: /version
- Health check: /health
- Platform Readiness: Mission Import ✅, Artifact Registry ✅,
Storage ✅, Operations ✅, Developer Mode ✅
Go Live Checklist updated with current status.
Docker Compose configured (ports adjusted for existing services).
Next: Pilot 001 — Break the system!
Test: bad coverage, large videos, interrupted upload,
multiple phones, bad GPS, darkness, rain, poor lighting.
- Go Live Checklist for LandveX Internal Pilot deployment
- Version endpoint: /version returns environment, version, commit, build
- Ready for Internal Pilot deployment
Next: Deploy with Docker Compose
- Kubernetes-first for platform architecture
- GitOps: never manual cluster changes
- Local-first for dev experience, K8s-first for platform
- All infrastructure as code, same Git flow as app code
- Standardized service contract: /health, /ready, /live, /metrics, /version
- OpenTelemetry tracing, structured JSON logging
- Correlation ID follows entire pipeline: Session → Mission → Artifact → Observation → Evidence → Decision
- Intelligence Lab integrated in same platform, not separate cluster
- Platform principle: no new service introduces new deploy/log/config/observability pattern
Binding for all developers and AI agents.
Complements E-001, EP-1.0, Architecture Principles.
Next: Deploy pilot environment
- LandveX is one platform, not two
- Same backend, database, API, map
- Intelligence Lab = Developer Mode (not separate product)
- Same Artifact Viewer, different detail by role
- Same map, different layers by role
- Role-based access: Erik, Johan, Pilot Customer, Municipality
Architecture Principle:
One platform. One API. One data model. One map.
One Artifact system. Multiple roles.
Next: Implement RBAC and Developer Mode toggle
- Verkliga data först
- Pipeline före modell
- Decision Case är målet
- Träna kontinuerligt
- STOP-regel: ingen funktion utan validering på pilotmaterial
- Sista princip: ingen modellförbättring färdig utan mätbar förbättring
Stoppregel: Ingen ny arkitektur förrän MVP-0 genomfört med verkligt uppdrag.
Next: Pilot 001 — First real field upload
- LANDVEX_PLATFORM_ARCHITECTURE.md: Five Engines (Reality, Knowledge,
Decision, Mission, Economic)
- Credit: first-class economic object with types (mission, validation,
training, priority, emergency)
- IntelligenceLedger: tracks value creation separate from financial accounting
- KnowledgeGap: missing information that drives missions
- Hotspot: composite score for mission generation
- Contradiction: conflicting information as opportunity
Key principle: Every component answers 'What value is created here?
Who pays for it?'
Next: PR-005A — Minimal Mission Import UI for MVP-0
- Added Three Rules to README:
1. Domain knows nothing about AI (no AIObservation, YOLODetection, etc.)
2. Everything is an Artifact (common contract for all produced objects)
3. All decisions are reproducible (answer: which observations, evidence,
model, version, rules, reviewer, when, approved version)
- Renamed Human Intelligence → Experience Intelligence
- Broader scope: citizen surveys, customer satisfaction, field technician
feedback, contractor experience, service desk data
- More future-proof than 'Human Intelligence'
- Added Capability Tags for developers:
- Observation: [Detection, Vision, GPS, Image]
- Decision: [Decision, Recommendation, Business]
- Artifact: [Storage, Versioning, Lineage]
- Makes dependencies clear as platform grows
- Updated Domain Invariants:
- DecisionCase: must have at least one Review before Approved
- Review: must belong to exactly one Decision, must have reviewer
- Added Merge Criteria:
- All stakeholders (developer, AI engineer, product owner, domain expert)
can read model and understand same terms
- No AI objects, all Artifacts, reproducible decisions
Rationale: Lock domain language before implementation. Shared vocabulary
for code, docs, APIs, tests, and product discussions.
- Added Human Intelligence as separate external module (not in core domain)
- Positioning: External Intelligence Module, not part of Epic-001
- Architecture: Reality Intelligence with four branches:
- Infrastructure Intelligence (core, Epic-001)
- Operational Intelligence (future)
- Human Intelligence (future module)
- External Intelligence (future)
- Human Insight Artifact: Source, Geography, Period, Metrics, Confidence
- Usage: Linked to Area or Decision Case, never mixed with raw observations
- Example: Decision Case enriched with 'Many complaints last 30 days'
- When: After Epic-001 stable and 20+ Decision Cases exist
Rationale: Keep core domain clean. Human data is context, not observation.
Add after basic pipeline is proven.
- Package: @landvex/domain
- Zero dependencies on Express, PostgreSQL, S3, or AI frameworks
- Four package structure: domain, contracts, shared, infrastructure
- Domain never depends on infrastructure
- Aggregate Roots: FieldSession, Mission, DecisionCase
- Entities: MissionAsset, Artifact, Observation, Evidence, Finding,
Decision, Review, Action, Outcome
- Value Objects: MissionId, ArtifactId, SessionId, ObservationId,
DecisionId, GeoLocation, GpsAccuracy, Confidence, Severity, Priority,
Hash, StorageUri, Version
- Enums: ArtifactType, ReviewStatus, DecisionVerb, MissionStatus, SessionStatus
- Event Contracts: FieldSessionCreated, MissionCreated, MissionImported,
ArtifactUploaded, ArtifactValidated, ObservationCreated, EvidenceCreated,
FindingCreated, DecisionCreated, DecisionReviewed, DecisionApproved
- Domain Invariants:
- FieldSession: must have location, date, can have zero missions
- Mission: must belong to one Session, must have at least one Artifact
- DecisionCase: must have at least one Observation, one Evidence,
exactly one Decision, cannot be Approved without Review
- Artifact: must have unique hash, storage URI, versioned
- TypeScript interfaces for all domain objects
- Branded ID types for type safety
- Strict rule: No new feature may introduce new domain concepts without
approved change to domain model
- README: 'This package describes LandveX domain model. Contains no
dependencies to database, HTTP, cloud storage, or AI frameworks.'
- Next: PR-002 Persistence Adapter (Repository Interface → PostgreSQL/S3/Event Store)
Rationale: Lock the language before writing infrastructure code.
Shared vocabulary for code, docs, APIs, tests, and product discussions.
- Session is root (not Mission): Field Session → Mission → Asset → Observation...
- Event Sourcing: never overwrite status, status is projection of history
- Artifact Registry: first-class object with id, type, version, hash, lineage
- Decision Case immutability: Review → Revision → Approved Version (like Git)
- Review Task: Assigned → Reviewed → Approved → Closed
- Processing Graph: nodes not hardcoded chain, swap models without changing rest
- Data Quality as domain: Blur, Duplicate, Bad GPS, Low Resolution, etc.
- Decision Case comparison: show exactly what changed, which evidence, model, human
- Golden Missions + Golden Datasets: two levels
- Domain Event Viewer: timeline (09:42 Mission Created, 09:43 Video Uploaded...)
- KPI: Verified Decision Throughput (verified decisions per day)
- Architecture Principle: 'Produces verified Decision Cases through reproducible
and traceable pipeline'
Updated PR-001 Domain Model:
- Added FieldSession (root)
- Added Artifact interface
- Added Event sourcing types
- Session ID format: session_YYYYMMDD_NNNNNN
- Updated API to include /sessions endpoints
Rationale: Three fundamental objects (Session, Artifact, Event) make the rest
natural. Scalable, auditable, well-suited for public sector traceability requirements.
- Added Vision: 'LandveX Intelligence Lab is the internal factory where
raw reality is refined into verified Control Intelligence'
- Added Architecture Goal: Every artifact traceable backward to source
and forward to decision
- Added Development Rule: No Story starts with UI. Order: Domain model →
API → Storage → Tests → UI
- Added Story 1 implementation plan with 5 PRs:
PR-001: Domain Model (Mission, MissionAsset, Upload, types)
PR-002: Storage (S3/R2 bucket, PostgreSQL metadata, checksums, EXIF, GPS)
PR-003: API (POST /missions, POST /missions/{id}/assets, GET /missions)
PR-004: Events (MissionCreated, AssetUploaded, RawDatasetReady)
PR-005: UI (simple drag-and-drop upload with progress)
- Added Definition of Done for Story 1:
Phone → Video → Upload → Bucket → Metadata → Mission visible in Dataset Explorer
- Added ID Convention: mission_YYYYMMDD_NNNNNN, asset_NNNNNN, obs_NNNNNN,
decision_NNNNNN. Never UUID in UI.
- Added Artifact Viewer: show raw asset metadata, hash, GPS, EXIF,
storage location, version for debugging
Rationale: Clean architecture, testable without UI, traceable artifacts.
- Reordered stories to reach First Verified Decision faster:
1. Mission Import (was 2) — proves we can receive real data
2. Dataset Explorer (was 3) — makes data visible
3. Annotation Workspace (was 4) — first human-in-the-loop
4. Decision Case (was 5) — first verified decision
5. Replay (was 6) — proves chain is reproducible
6. Session Management (was 1) — organizes when core works
- Added Golden Mission concept:
- Real mission that never changes, used as regression test
- Every new model runs against same mission
- See immediately if something got better or worse
- Added Review as first-class object:
- Observation → AI → Human Review → Approved/Rejected/Needs More Evidence
- Makes entire quality flow traceable
- Added Dashboard v1:
- Sessions, Missions, Decision Cases, Pending Reviews, Verified Decisions
- Big button: [Continue Reviewing]
- Work tool, not BI system
- Added vertical user journey (demo script):
- quiXzoom → photo → import → save → explore → AI observation →
correction → Decision Case → full chain viewer
- If this works, core is proven
- Added definition of 'First Verified Decision':
- Built on real observation data
- Reviewed by human
- Complete evidence chain
- Fully reproducible from raw data to recommendation
Rationale: Reach core proof faster, add organization later.
Golden Mission enables regression testing from day one.
Review object makes quality flow traceable.
- STOP Rule: No new pipeline until 20 real Decision Cases exist
- Field Readiness Gate: 5 questions before building any feature
- Sprint Goal: Every sprint must produce more verified Decision Cases
- Six stories:
1. Session Management — organize missions by location/date
2. Mission Import — upload video/images/GPS/EXIF, store immutably
3. Dataset Explorer — browse, filter, search, map view
4. Annotation Workspace — review/correct AI, version history
5. Decision Case — full chain: Observation→Evidence→Finding→Decision→Business Impact
6. Replay — step through mission chain (V1: simple playback)
- Not in first release (intentionally postponed):
GPU Queue, Hyperparameter Search, Distributed Training,
Benchmark, Canary Deployment, Auto Retraining,
Bias Dashboard, Drift Detection
- Definition of Done: Complete vertical slice from reality to verified decision
- Definition of Ready for Epic-002: 20 real Decision Cases + Field Readiness Gate
- Technical stack: React+TypeScript, Node.js+Express, PostgreSQL, S3/R2, Bull, Python AI service
- Quality gates: TypeScript strict ≥80% coverage, no secrets, OAuth 2.0, immutable audit log, GitOps
Rationale: Prove the system works end-to-end before scaling.
Focus on learning from reality, not building everything upfront.
- MVP Milestone: 'First Verified Decision'
- Developer films with quiXzoom, imports to Lab, corrects AI,
creates Decision Case, follows chain with full traceability
- When this works = first complete verifiable Control Intelligence pipeline
- Three development phases:
Phase 1 (Essential): Ingestion, Dataset Explorer, Annotation, Decision Case Viewer
Phase 2 (Scale): Replay, Benchmark, Evaluation
Phase 3 (Advanced): GPU Jobs, Hyperparameter Runs, Model Promotion, Canary
- Product Architecture: quiXzoom → Observations → Intelligence Lab →
Improved Models → LandveX → Better Decisions → Feedback → Intelligence Lab
- Two products: quiXzoom (observations), LandveX (decisions)
- Intelligence Lab = the factory that improves both
- New areas:
- Data Quality: Healthy/Blurred/Duplicate/Wrong GPS/Night/Rain/Occluded
+ Coverage (Roads, Buildings, Signs, Drainage, Vegetation)
- Decision Analytics: Acceptance Rate, Ignore Rate, Accuracy,
Insufficient Evidence, Data Collection Value
- Business value metrics, not traditional AI metrics
Rationale: Build MVP first, prove first real workflow, then scale.
Decision Cases are the heart. Data Quality explains model performance.
Decision Analytics measure business value.
- Internal development environment for Control Intelligence
- Core principle: 'Produces verified Control Intelligence, not AI models'
- Separate repo: landvex-intelligence-lab
- Navigation: Dashboard, Models, Datasets, Annotations, Training,
Evaluation, Decision Cases, Replay, Validation, Deploy, Settings
- Key features:
- Dashboard: AI status (models, datasets, jobs, cases)
- Mission Replay: click through entire chain
- Annotation: video + AI suggestion + manual correction
- Decision Cases: first-class objects, all playable
- Benchmark: compare YOLO, Grounding DINO, SAM, custom models
- Replay: find regressions between model versions
- Validation: field trials, scenario tests, decision tests
- Deploy: 'Promote Model' not 'Deploy' (dev → validation → pilot → prod)
- Experiments: link EP-1.0, DS-001, etc. to real data
- Target: New AI engineer understands in minutes:
'This is where we build, test, and verify LandveX Control Intelligence
before anything reaches production.'
Rationale: Single internal tool for all AI development. Centralizes
model training, annotation, validation, replay, decision chains,
regression tests, experiments, and model promotion.
- Added four pilot phases (product research, not marketing):
1. Collection — what can actually be detected?
2. Analysis — are decisions understandable?
3. Verification — was recommendation correct?
4. Reflection — what needs to change?
- Measurement principle:
- Not: Did AI find a crack?
- But: Did this become a decision a real person could act on?
- Document 'non-decisions' — equally valuable as clear decisions
- Film workflow, not just infrastructure:
- How you find area, choose mission, document
- What feels unclear, when you become uncertain
- When system saves time
- Observer mindset: document first, change model later
- Build model from real workflows, not assumptions
Rationale: First 20-50 real missions teach more than months of modeling.
- Created FIELD_TRIAL_LOG.md — observation protocol for real customer cases
- Log entry template with 10 fields
- Two example entries (accepted and rejected decisions)
- Questions the log answers: adoption, accuracy, calibration, rejection analysis
- Future KPIs: Decision Adoption Rate, Decision Accuracy, Time to Decision
- Updated MEMORY.md with Control Intelligence & Decision Model section
- Decision Pipeline v1.0 summary
- Decision Object v1.0 (STRUCTURE FROZEN)
- Status: VALIDATED FOR FIELD TRIALS
- Three target customer cases
- Future KPIs
- Key principle: No more modeling until first real customer case
- Added Decision Adoption Rate and Decision Accuracy as future product KPIs
- Not implemented yet — start collecting data now, calculate later
- Decision Adoption = accepted / total recommendations
- Decision Accuracy = correct / total decisions
Rationale: Stop modeling, start observing. First real customer case
will teach more than the last twenty documents combined.
- Status: STRUCTURE FROZEN (not LOCKED/FINAL)
- Frozen: field names, semantics, relationships
- Not frozen: implementation, algorithms, confidence calculation
- Three tests executed and PASSED:
1. Decision Invariance Test — all 8 scenarios use same 7-field structure
2. Evidence Variation Test — Decision Object identical regardless of evidence type
3. Explainability Invariance Test — chain Reality→Observation→Evidence→Finding→Decision
works for all actionable decisions
- Results summary:
- Manual Review: 6 PASS, 2 OBSERVATION, 0 FAIL
- Decision Invariance: PASS
- Evidence Variation: PASS
- Explainability Invariance: PASS
- Decision Quality Gate: PASS
- Verb Rule: PASS
- Overall: VALIDATED FOR FIELD TRIALS
- Internal validation complete
- Ready for real customer testing
- Not production truth yet
- Open questions documented (not added as fields):
- Observation A: Cost estimate for investment decisions
- Observation B: Explicit low confidence communication
- Next: Three real customer cases (municipality, property owner, contractor)
Rationale: Freeze structure before testing, run tests against locked model,
mark as 'Field Trial Ready' not 'Final'. Model changes when real data
contradicts it, not before.
- Added Step 7: Learning (feedback loop from Business Impact to Intelligence)
- Control Intelligence definition: LandveX produces Control Intelligence, not AI
- Three target customer cases defined:
1. Municipality — Inspect or wait? (Maintenance prioritization)
2. Property Owner — Repair now or plan later? (Cost vs risk)
3. Contractor/Operations — Which action first? (Operational planning)
- Validation requirements: Run each case through full pipeline, document breaks,
revise only after data contradicts model
- Communication principle: Observation → Analysis → Recommendation
(AI is implementation, recommendation is product)
Rationale: Stop modeling, start observing. Model changes when data contradicts
it, not before. Three real customer cases before freezing.
- Six layers (added Evidence between Observation and Finding):
1. Reality
2. Observation
3. Evidence (linked observations with context)
4. Finding
5. Decision
6. Business Impact
- Decision Object restructured:
1. Decision — what should user decide?
2. Why — why system recommends this
3. Evidence — what observations support this
4. Confidence — how certain (3 dimensions)
5. Consequence — what if nothing done
6. Action — next step
7. Business Impact — economic/operational meaning
- Confidence Model (3 dimensions):
- Observation Confidence: how certain is detection?
- Evidence Strength: how strongly supported?
- Recommendation Confidence: how certain is recommendation?
- Explainability Principle:
- Every Decision Card must be explorable
- User can click: Decision → Finding → Evidence → Observations → Reality
- Competitive advantage: traceability to source material
- Business Impact Model (4 dimensions):
- Risk, Cost, Time, Opportunity
- Three validation scenarios:
1. Road Crack — simple, common
2. Damaged Facade — complex, critical
3. Broken Road Sign — simple, regulatory
- Pass criteria: Same Decision Object works for all three
Rationale: Decision Intelligence, not BI. Evidence-backed decisions
are the core product. Explainability is competitive advantage.
Validation against real scenarios before freezing.
- DASHBOARD_AUDIT_PROTOCOL.md (v1.0, LOCKED):
- Five criteria: 3-Second Rule, Journey Principle, Reality→Decision,
Dashboard Principle, Decision Density
- Blink Test: 3-second exposure, consistent answers = pass
- Information-to-Decision Ratio: measure objects needed per decision
- Audit form with pass/fail for each criterion
- Decision matrix: all pass = proceed, some fail = adjust Dashboard,
most fail = review Foundation
Rationale: Dashboard is the stress test for Foundation v1.0. If Dashboard
passes without Foundation changes, the base is robust enough to scale.
If Dashboard fails, adjust Dashboard first — not Foundation.
- DASHBOARD_PRINCIPLE.md (v1.0, LOCKED):
- Four questions: What, Where, How serious, What now
- Information hierarchy: Score -> Observations -> Map -> History -> Details
- Decision Density: Dashboard = 1-3 decisions max
- Not BI: helps user make decision, not consume statistics
- Verification checklist
- EXPERIENCE_AUDIT_QA.md updated:
- Screen 4: Landvex Dashboard (Phase: Manage)
- Dashboard-specific questions: 3-second understanding, today's decision,
80% ignorable, primary CTA
- Dashboard Principle check: What/Where/How serious/What now
- Decision Density target: 1-3 decisions
- One-Sentence Test: understand area performance and what to act on
- Ready for Landvex Dashboard screen (stresstest for Foundation v1.0)
- JOURNEY_PRINCIPLE.md (v1.0, LOCKED):
- Five phases: Discover, Capture, Process, Outcome, Manage
- Maps to both quiXzoom and Landvex
- Screen mapping table
- Balance check reveals Capture/Process/Outcome are empty
- Verification: every screen must belong to a phase
- EXPERIENCE_AUDIT_QA.md updated:
- Screen 3 renamed: Public Map -> Mission Marketplace
- Added Phase column: Discover
- One-Sentence Test updated: which missions not how much
- Added Journey Principle reference
- Screen 4: Dashboard (Landvex) - awaiting screen
- Screen 5: Results/Decision View (Landvex) - awaiting screen
- Next: Landvex Dashboard audit (stresstest for Foundation v1.0)
Rationale: Journey Principle prevents screens from floating without
context. Mission Marketplace better reflects the page's purpose.
Dashboard is the most complex screen - best stresstest for principles.
- LANDVEX_DESIGN_CONSTITUTION.md:
- Added §0a: Capability Parity Principle
- All user functions must work on smartphone
- Desktop may enhance, never require
- Two-question rule for every new feature
- Desktop as enhancer (not exclusive)
- Examples: Payments, History, KYC
- Verification checklist for every new feature
- RFC_DEFINITION_OF_DONE.md:
- Added criterion #3: Capability Parity
- Can be used on smartphone; desktop is enhancement
- Total criteria: 14 (was 13)
- Exit criteria: must pass all 14
Rationale: quiXzoom targets field workers. Phone is primary or only
computer. Phone must always be a full client. Desktop is a more
comfortable workspace for some tasks, not a prerequisite. This is a
constitutional principle, not implementation.
- Updated audit framework with fixed 6-question matrix:
1. 3-Second Rule: understand purpose immediately
2. Three-Step Rule: Input → Processing → Outcome visible
3. Primary Decision: know what to do
4. Information Hierarchy: most important is largest
5. Cognitive Load: what can be removed
6. Call to Action: clear next action
- Added One-Sentence Test:
- Can user describe screen in one sentence?
- Examples for Onboarding, Map View, Dashboard, Results
- Two+ sentences = screen tries to do too much
- Added placeholders for next screens:
- Screen 3: Dashboard (Landvex)
- Screen 4: Map View (Landvex/quiXzoom)
- Screen 5: Results/Decision View (Landvex)
- Priority order: Dashboard → Map View → Results → Search → Settings
- Updated quiXzoom onboarding audit with new matrix format
Rationale: Fixed matrix ensures consistent evaluation across all screens.
One-Sentence Test reveals overloaded screens. Placeholders ready for
next screens. Priority reflects user journey impact.
- EXPERIENCE_AUDIT_QA.md (v1.0, DRAFT):
- Audit framework: 6 questions per screen
- Screen 1: quiXzoom Onboarding — 3s ✅, R→D ⚠️, Decision ✅
- Issue: 'kr' used instead of USD/EUR (Valutaregel violation)
- Issue: Launch date creates hesitation
- Screen 2: Landvex Process — 3s ✅, R→D ✅, Decision ✅
- Issue: Technical terms in step descriptions
- Action items: currency update, date removal, verb simplification
- Next screens: Dashboard, Map View, Search, Mission Details, Results
- COMPONENT_MATURITY.md (v1.0, LOCKED):
- Three levels: Foundation → Validated → Canonical
- Foundation: RFC approved, passes 13 DoD criteria
- Validated: used in 3 real screens, passes Experience Audit
- Canonical: used in 5 screens, 2 sprints stable, other components inherit
- Promotion process with verification requirements
- Current status: all 4 components at Foundation level
Rationale: Observe first, standardize second. Components become Canonical
only after proving value in real screens. Experience Audit identifies gaps
before building components. Maturity model prevents premature standardization.
- FOUNDATIONS-v1.0.md updated:
- Added Landvex Core Principle and Design Constitution to frozen foundations
- Added Core Principle Rules to invariants (2.4)
- Reordered component priority: Modal, Search, Map Panel, Navigation, Table, Data Grid
- Reflects business value: search and maps are central to Landvex
- EXPERIENCE_AUDIT.md (v1.0, LOCKED):
- Four questions for every screen:
1. Can purpose be understood in 3 seconds?
2. Is 'Reality → Decision' visible?
3. Is it obvious what the user should do?
4. Does everything contribute to the decision?
- Three-second rule levels with verification method
- Audit process: select screens → apply questions → prioritize fixes → verify
- Example audit format
- Core Principle Check for RFCs: 4 questions before approval
- COMPONENT_TEMPLATE.md updated:
- Added Core Principle section to template
- Requires: decision support, cognitive load reduction, 3-second understanding
- RFC_DEFINITION_OF_DONE.md updated:
- Added Core Principle as criterion #2 (was 12 criteria, now 13)
- Exit criteria: must pass all 13
Rationale: Freeze foundation with Core Principle as highest authority.
Experience audit ensures all screens support decision-making.
Core Principle Check prevents components that don't serve the user.
Business-value prioritization: search and maps before tables.
- LANDVEX_CORE_PRINCIPLE.md (v1.0, LOCKED):
- Single promise: From reality → decision
- Five steps: Question → Collect → Analyze → Calculate → Decision
- Business verbs, not technical terms
- Three-second rule: 3s/10s/60s understanding levels
- Gauge: Video → AI → Score
- Applies to all communication, UX, documentation, AI
- LANDVEX_DESIGN_CONSTITUTION.md:
- Added §0: From Reality → Decision as highest principle
- Five steps in Swedish
- Three-second rule
- Gauge explanation
- Positioned before Introduction as foundational principle
Rationale: Landvex sells one thing — from reality to decision.
Every screen, illustration, and presentation must follow this flow.
Business verbs make it human. Three-second rule makes it scannable.
Gauge makes it instantly understandable.
Four-point validation:
1. COMPLETENESS ✅ PASS
- All 6 Button states covered
- All 7 Input states covered
- All 10 Select states covered
- All 7 Card states covered
2. ORTHOGONALITY 🟡 PASS WITH NOTES
- 3 minor overlaps identified (surface.raised vs overlay, text.secondary vs muted, action.disabled vs text.muted)
- All resolved by distinct use cases
- 1 ambiguity noted (brand vs action), documented in contracts
3. MINIMALITY 🟡 PASS WITH NOTES
- 9 unused tokens identified
- All justified: needed for upcoming components (Modal, Link, Alert) or dark mode
- No tokens should be removed
4. STABILITY ✅ PASS
- Modal: 0 new tokens needed
- Navigation: 0 new tokens needed
- Table: 0 new tokens needed
- Map Panel: 0 new tokens needed
VERDICT: APPROVE with minor notes. Semantic Color System is stable enough to freeze.
Action items:
1. Freeze Semantic Color System v1.0
2. Update Input, Select, Card to semantic aliases (raise to ~80%)
3. Create Foundation Freeze milestone
4. Proceed with Modal, Navigation, Table, Map Panel
- RFC-002 Input:
- Token Dependencies updated to semantic aliases with primitives
- All tokens now map through color.surface, color.border, color.text, color.status
- No direct color references (e.g., semantic-red-500 → color.status.danger)
- Helper/error text uses semantic tokens
- RFC-003 Select:
- Token Dependencies updated to semantic aliases with primitives
- Dropdown, option, and error states use semantic tokens
- Selected option uses color.action.primary at 10% opacity
- No direct color references
- RFC-004 Card:
- Token Dependencies updated to semantic aliases with primitives
- Surface, border, text hierarchy use semantic tokens
- Shadow tokens mapped to elevation system
- No direct color references
- COMPLIANCE_MATRIX.md:
- Input: 33% → 83%
- Select: 33% → 83%
- Card: 33% → 83%
- All now have Governance ✅, Tokens ✅, Motion ✅, Accessibility ✅, AI ✅
Rationale: Semantic model first. Components never reference primitives.
Token contracts (purpose, allowed, forbidden) ensure correct usage.
Dark mode implementable via token swap without component changes.
- AI_DESIGN_PRINCIPLES.md:
- Restructured into 5 parts: A. Decision Process, B. Component Selection,
C. Token Usage, D. Design Review, E. Escalation
- All rules use RFC 2119 normative words (MUST/MUST NOT/SHOULD/MAY)
- Clearer escalation path: when to create DDR, when to flag uncertainty
- COMPLIANCE_MATRIX.md:
- Tracks readiness for all 29 components (Tier 1/2/3)
- 6 dimensions: Governance, Tokens, Motion, Accessibility, AI, QA
- Foundation documents tracked separately
- Button at 82% (reference for others)
- docs/platform/README.md:
- Reserved directory for cross-cutting governance
- Future: AI Governance, Product Governance, Review Process,
Quality Gates, Release Governance, Decision Frameworks
- Separates platform governance from design system
- LANDVEX_DESIGN_SPECIFICATION.md:
- Button renamed to RFC-001: Canonical Button Component
- Structured with: Cognitive Purpose, When to Use/NOT Use,
User Expectation, Interaction Contract, Failure Behaviour,
Accessibility Contract, AI Contract
- Sets standard for all future RFC component specs
Rationale: AI rules before components (AI writes components).
Compliance matrix makes progress visible. Platform governance
separates cross-cutting concerns from design system. RFC format
for components ensures production-ready specifications.
Bernt