Plock — Demo Readiness

Canonical PLOCK baseline package, QA review, and narrow verification notes.

Demo Readiness — Index
Canonical Source of Truth
User Stories Baseline
Feature Baseline
Gaps and Next Steps
QA Checklist Baseline
Initial Package QA Review
API Spec Verification Pass

Demo Readiness — Index

Source: ~/ALAI/products/Plock/docs/demo-readiness/INDEX.md

PLOCK Demo Readiness — Canonical Baseline Index

Date: 2026-03-14
Purpose: Entry point for all agents and humans working on PLOCK demo-readiness, documentation QA, and subsequent backlog generation.

Read in This Order

Working Rules

Use repo reality first.
Do not use docs/ARCHITECTURE.md as canonical architecture input.
Do not trust agent narrative output unless the claimed files actually exist.
All future QA and backlog generation for PLOCK must reference this baseline package.

Status

This package is a manually curated canonical baseline created after discovering:

documentation drift,
stale/conflicting architecture docs,
and unreliable delegated documentation artifact generation.

It is the temporary source of truth until a fuller reviewed demo-readiness package replaces it.

Canonical Source of Truth

Source: ~/ALAI/products/Plock/docs/demo-readiness/00-canonical-source-of-truth.md

PLOCK — Canonical Source of Truth

Date: 2026-03-14
Purpose: Define which files are authoritative for PLOCK and which files are stale/conflicting, so all future documentation, QA, and implementation work is based on real system state.

1. Why This Exists

PLOCK currently has a real codebase and substantial documentation, but not all documentation reflects the same architecture.

Without a canonical source-of-truth map:

user stories can be extracted from stale assumptions
feature catalogs can be built against the wrong architecture
QA can validate one document against another document that is itself outdated
implementation tasks can be generated against a system that does not match the actual repo

This document defines what is authoritative and what is not.

2. Authority Order

When files conflict, use this precedence:

Actual code and repository structure
Database migrations and runtime configuration
BUILD-BLUEPRINT.md
README.md
Runbooks and operational docs
ADR documents
PRD / GTM / Regulatory docs
API-SPEC.md (reference only unless confirmed against code)
Stale/conflicting docs must not be used as source of truth

3. Authoritative Sources

3.1 Codebase

The following repo areas are authoritative:

backend/
frontend/
backend/src/main/resources/db/migration/
tests/
e2e/
infrastructure/

3.2 Primary Architecture / Build Docs

These are currently the strongest documentation sources:

README.md
BUILD-BLUEPRINT.md
RUNBOOK.md
docs/RUNBOOK.md
docs/RLS-AUDIT.md
docs/SECRETS-MANAGEMENT.md

3.3 Product / Business / Compliance Docs

These are authoritative for product intent, market framing, compliance assumptions, and user-level needs — but must still be reconciled against code:

docs/PRD.md
docs/GTM-STRATEGY.md
docs/REGULATORY.md

3.4 ADRs

Use as authoritative for declared decisions when they match repo reality:

adr/ADR-001-flyway-over-prisma.md
adr/ADR-002-module-federation.md
adr/ADR-003-rls-tenant-isolation.md

4. Current Real Architecture

Based on actual code and authoritative docs, the real current system is:

Backend

Kotlin
Ktor
Exposed ORM
Flyway migrations
PostgreSQL
Redis

Frontend

React 19
TypeScript
Vite
Module Federation
Micro-frontends
- shell
- mfe-inventory
- mfe-orders
- mfe-picking
- mfe-settings
- mfe-ai

Infrastructure / Deployment

Railway-oriented deployment and infra
Docker / docker-compose for local setup
Terraform and deployment helper scripts under infrastructure/

Multi-tenancy

Tenant boundary is warehouse_id
Isolation enforced via PostgreSQL RLS
Tenant context set through application request flow

Integrations

Fortnox
PostNord
DHL
Instabee

5. Semi-Authoritative / Needs Verification

`docs/API-SPEC.md`

This file is useful as a product/API intent document, but it must be verified against the real Ktor routing and actual backend implementation before being treated as canonical.

Use it as:

reference
gap analysis input
API-intent documentation

Do not use it as final truth without code verification.

6. Stale / Conflicting Sources

`docs/ARCHITECTURE.md`

This file is currently stale/conflicting and must not be used as the main architecture source.

It describes a different architecture, including:

Next.js
Express
Prisma
Python ML microservice
Supabase
Upstash
organization_id-based tenancy

That conflicts with the actual repo and stronger sources, which show:

Kotlin/Ktor
Exposed + Flyway
React + Vite MFEs
PostgreSQL + Redis
warehouse_id tenant model

Rule: docs/ARCHITECTURE.md may be used only as historical/stale material until rewritten or archived.

7. Operational Constraints

7.1 Agent Output Is Not Source of Truth

The following are not authoritative:

/tmp/verify-*
/tmp/gotcha-task-*
agent-generated summaries that claim files were created but no files exist
MC task status alone (done, blocked, etc.) without artifact verification

7.2 Deliverable Existence Is Required

Any documentation task that claims output files must be verified against the actual filesystem. A claimed file path is not considered real unless:

the file exists
it is readable
its contents are relevant to the requested task

8. What Future Docs Must Be Based On

The next canonical PLOCK documentation pass must be based on:

User Stories

docs/PRD.md
actual route/service domains in backend
AI strategy / GTM / regulatory documents where relevant

Feature Catalog

backend routes and services
frontend MFEs
migrations / schema
integrations
security / RLS docs

ADR / BDR

adr/*
BUILD-BLUEPRINT
actual code decisions already visible in repo
business decisions visible in PRD / GTM / pricing docs

Test Scenarios

existing backend tests
existing e2e tests
route/service/module structure
runbook incident scenarios
compliance-sensitive workflows

9. Current Remaining Gaps

The baseline canonical package now exists under docs/demo-readiness/, but important follow-up artifacts and cleanups still remain.

Current remaining gaps:

no canonical 00-program-map.md yet
no canonical 00a-deterministic-task-contract.md yet
no canonical 01-doc-inventory-gap-audit.md yet
docs/API-SPEC.md still needs explicit verification against real Ktor routes before it can be treated as canonical
docs/ARCHITECTURE.md is still stale/conflicting and has not yet been rewritten or archived

Current hygiene issue:

infrastructure/README.md contains secret-like example material and must be reviewed/cleaned

10. Working Rule for All Remaining PLOCK Work

Until a new canonical documentation package exists:

use repo reality first
use BUILD-BLUEPRINT + README + RLS-AUDIT + runbooks as architectural truth
use PRD + GTM + REGULATORY for business, user, and market truth
treat docs/ARCHITECTURE.md as stale
treat agent narrative output as non-authoritative unless backed by real files

11. Decision

This document is the baseline authority map for all remaining PLOCK planning, QA, and implementation prep work.

Any future PLOCK task that produces:

user stories
feature lists
ADR/BDR registers
QA checklists
implementation backlog

must explicitly reference this authority model before proceeding.

User Stories Baseline

Source: ~/ALAI/products/Plock/docs/demo-readiness/01-user-stories-baseline.md

PLOCK — User Stories Baseline

Date: 2026-03-14
Purpose: Establish a first canonical user-story baseline for PLOCK using real repository evidence and authoritative product documents. This is not yet the final polished story set; it is the operational baseline for documentation, QA, and backlog slicing.

1. Scope and Method

This baseline is derived from:

docs/PRD.md
actual backend route/service structure
actual frontend MFE structure
integration modules present in the repository
operational and regulatory documentation where relevant

This document intentionally avoids inventing features not supported by either:

current product docs, or
current repository structure

2. Story Status Model

Each story is tagged as one of:

exists — strongly supported by real code/routes/docs
partial — visible in docs and/or code structure, but maturity unclear
planned — described in docs, but implementation evidence is limited or phase-dependent

3. Receiving / Inbound

US-INB-001 — Receive goods via barcode

Status: exists
Evidence: PRD.md, ReceivingRoutes.kt, ReceivingService.kt, barcode-related backend structure

As a warehouse worker
I want to scan a barcode and identify the purchase order it belongs to
So that I can receive goods correctly without manual lookup

US-INB-002 — View open purchase orders

Status: exists
Evidence: PRD.md, ReceivingRoutes.kt, supplier/receiving route structure

As a warehouse manager
I want to see all open purchase orders and expected arrival dates
So that I can plan staffing and dock capacity

US-INB-003 — Guided putaway after receiving

Status: partial
Evidence: PRD.md, LocationRoutes.kt, PutAwayService.kt

As a warehouse worker
I want to be guided to the correct bin location after receiving
So that I do not need to memorize where products belong

US-INB-004 — Detect receiving discrepancies

Status: exists
Evidence: PRD.md, ReceivingDiscrepancyTest.kt, discrepancy migration/table evidence

As a warehouse manager
I want to be notified immediately when received quantities do not match the purchase order
So that I can resolve supplier issues before inventory is corrupted

4. Inventory Management

US-INV-001 — Real-time inventory visibility

Status: exists
Evidence: PRD.md, InventoryRoutes.kt, InventoryService.kt

As a warehouse manager
I want to see the exact quantity of a SKU by location in real time
So that I can answer operational questions without walking the warehouse

US-INV-002 — Reorder point alerting

Status: partial
Evidence: PRD.md, inventory domain present; implementation maturity unclear

As a warehouse manager
I want to receive an alert when inventory falls below reorder point
So that I can prevent avoidable stockouts

US-INV-003 — Zone-based cycle counts

Status: exists
Evidence: PRD.md, CycleCountRoutes.kt, CycleCountService.kt, tests

As a warehouse manager
I want to run a cycle count for a specific zone without stopping all operations
So that I can maintain inventory accuracy continuously

US-INV-004 — Mobile-assisted physical inventory count

Status: partial
Evidence: PRD.md, V7 mobile support migrations, runbook/mobile references

As a warehouse worker
I want to perform physical inventory counts on a mobile device
So that counting is faster and less error-prone than paper workflows

5. Orders / Outbound

US-OUT-001 — Release urgent orders quickly

Status: exists
Evidence: PRD.md, OrderRoutes.kt, order/picking domain structure

As a warehouse manager
I want to release urgent orders with a single action
So that I can respond quickly to escalations and deadlines

US-OUT-002 — Work from structured picking flow

Status: exists
Evidence: PickingRoutes.kt, PickingService.kt, mfe-picking

As a picker
I want to receive a structured picking workflow
So that I can pick efficiently and consistently

US-OUT-003 — Verify packing with product photo

Status: partial
Evidence: PRD.md, frontend/product/packing intent visible in docs

As a packing worker
I want to see a product photo during packing
So that I can confirm I am sealing the correct item

US-OUT-004 — Unified shipment tracking view

Status: partial
Evidence: PRD.md, ShipmentRoutes.kt, carrier integration structure

As a warehouse manager
I want to see outbound shipment status in one place
So that I can proactively handle delays and customer issues

6. Shipping / Carrier Operations

US-SHP-001 — Print carrier labels directly from Plock

Status: exists
Evidence: PRD.md, PostNord/DHL/Instabee integration code, shipment/carrier routes

As a warehouse worker
I want to print shipping labels directly from Plock
So that I do not need to log into separate carrier portals

US-SHP-002 — Use multiple carriers in one operational flow

Status: exists
Evidence: CarrierRoutes.kt, CarrierIntegrationRoutes.kt, multiple carrier adapters/services

As a warehouse manager
I want to work with PostNord, DHL, and Instabee in one system
So that outbound shipping does not depend on multiple manual carrier workflows

US-SHP-003 — Track carrier sync and integration health

Status: partial
Evidence: integration_sync_log schema, runbook sections for Fortnox/carrier failures

As a system operator
I want to inspect carrier/integration sync behavior
So that I can detect and troubleshoot failures quickly

7. AI / Smart Warehouse Operations

US-AI-001 — Ask warehouse questions in Swedish

Status: partial-to-exists
Evidence: PRD.md, AI-STRATEGY.md, mfe-ai/, product positioning

As a warehouse manager
I want to ask warehouse questions in Swedish and get immediate answers
So that I can make decisions without SQL, exports, or manual searching

US-AI-002 — Execute warehouse commands via AI with confirmation

Status: planned / partial
Evidence: PRD.md, AI-STRATEGY.md

As a warehouse manager
I want to trigger operational actions through natural language with explicit confirmation
So that I can manage exceptions faster than through deep UI navigation

US-AI-003 — Optimize pick routes

Status: partial-to-exists
Evidence: PRD.md, AI-STRATEGY.md, picking domain, runbook references to Smart Picking

As a warehouse manager
I want to use smart pick route optimization
So that workers spend less time walking and more time picking

8. Dashboard / Monitoring

US-DASH-001 — Operational dashboard

Status: exists
Evidence: DashboardRoutes.kt, PRD.md, dashboard domain

As a warehouse manager
I want to see a real-time dashboard with today’s operational KPIs
So that I can spot bottlenecks before they become incidents

US-DASH-002 — Monitor shipment and fulfillment progress

Status: partial
Evidence: dashboard/shipment routes, PRD

As a operations lead
I want to monitor fulfillment progress and pending shipments
So that I can intervene before SLAs are missed

9. Users / Roles / Multi-Tenancy

US-SEC-001 — Manage users and roles

Status: exists
Evidence: UserRoutes.kt, RoleRoutes.kt, RbacService.kt

As an admin
I want to manage users and roles
So that only the right people can perform sensitive warehouse actions

US-SEC-002 — Restrict data by warehouse

Status: exists
Evidence: TenantPlugin.kt, RLS-AUDIT.md, RLS migrations

As a warehouse operator
I want to only see data for my warehouse
So that tenant/customer separation is enforced safely

US-SEC-003 — Keep tenant isolation enforced at the DB layer

Status: exists
Evidence: RLS-AUDIT.md, migration V6__rls_tenant_isolation.sql

As the platform
I want to enforce tenant isolation in PostgreSQL using RLS
So that application bugs do not automatically become cross-tenant data leaks

10. Integrations / Accounting

US-INT-001 — Sync warehouse/accounting data with Fortnox

Status: exists
Evidence: Fortnox integration modules, docs, secrets, runbook

As a Swedish SMB operator
I want to integrate Plock with Fortnox
So that warehouse operations and accounting stay aligned

US-INT-002 — Re-authorize or recover from Fortnox sync failure

Status: partial-to-exists
Evidence: Fortnox OAuth/sync routes, runbook incident section

As a tenant admin
I want to reconnect or recover the Fortnox integration when it fails
So that business operations are not blocked by stale tokens or sync errors

11. 3PL / Client Isolation (Phase-Dependent)

US-3PL-001 — Separate client inventory views

Status: planned
Evidence: PRD.md, GTM-STRATEGY.md, regulatory references

As a 3PL operations lead
I want to see inventory separated by client
So that I can manage a multi-client warehouse safely

US-3PL-002 — Support 3PL billing workflows

Status: planned
Evidence: REGULATORY.md, GTM and pricing logic

As a 3PL operator
I want to support warehousing-service billing workflows
So that customer charging is structured and scalable

12. Business / Sales / Market Layer

US-BIZ-001 — Position as Fortnox-next-step WMS

Status: planned/business
Evidence: GTM-STRATEGY.md

As the business
I want to position Plock as the natural next step after Fortnox Lager
So that market entry is focused and credible

US-BIZ-002 — Support Swedish SMB self-serve onboarding motion

Status: planned/business
Evidence: GTM and product docs

As the product business
I want to enable a low-friction onboarding and trial motion
So that acquisition cost stays low and distribution scales

13. Summary

Strongly supported by current code/docs

receiving
inventory
orders
picking
shipments
carriers
RBAC
tenant isolation
Fortnox integration
dashboard
barcode
audit/webhook/SSE infrastructure

Present but maturity unclear

AI chat execution depth
smart picking maturity
mobile/PWA operational depth
packing/photo verification
full shipment monitoring UX
reorder alerting maturity

More Phase 2 / strategic than current MVP

3PL client isolation workflows
3PL billing
full commercial/demo/support packaging
polished sales enablement materials

14. Working Rule

This user-story baseline is the first canonical operational extraction.

Any future:

feature catalog
QA gate
implementation backlog
demo script
support playbook

must map back to these stories and mark each item as:

exists
partial
planned

Feature Baseline

Source: ~/ALAI/products/Plock/docs/demo-readiness/02-feature-baseline.md

PLOCK — Feature Baseline

Date: 2026-03-14
Purpose: Establish a first canonical feature baseline for PLOCK using real repository evidence and authoritative documentation. This is the operational feature map that future QA, backlog slicing, implementation planning, and demo prep should build on.

1. Method

This baseline is based on:

actual repository structure
backend route/service modules
frontend micro-frontend structure
database migrations
runbooks, security, and integration docs
PRD / GTM / regulatory context where relevant

Every feature is tagged with a maturity label:

exists — strongly supported by code + docs
partial — real evidence exists, but depth/completeness is unclear
planned — documented as intended direction, but implementation evidence is weak or phase-dependent

2. Feature Groups

Platform / architecture
Backend domain features
Frontend / UX features
Database / tenant isolation
Integrations
AI features
Testing / QA
Ops / deployment / observability
Security
Business / GTM / support
Known contradictions and gaps

3. Platform / Architecture

F-PLAT-001 — Kotlin/Ktor backend platform

Status: exists
Evidence: backend/build.gradle.kts, Application.kt, Ktor plugins and route modules

PLOCK uses a Kotlin/Ktor backend, not an Express/Node backend.

F-PLAT-002 — React micro-frontend frontend platform

Status: exists
Evidence: frontend/, frontend/shell/package.json, MFE folders, Vite setup

PLOCK frontend is a React 19 + TypeScript + Vite Module Federation system with multiple MFEs.

F-PLAT-003 — Monorepo with mixed backend/frontend tooling

Status: exists
Evidence: root package.json, backend/, frontend/, workspaces, Turborepo scripts

PLOCK uses:

Gradle for backend
npm/Turborepo workspace structure for frontend packages and MFEs

F-PLAT-004 — Railway-oriented deployment model

Status: partial-to-exists
Evidence: infrastructure/README.md, Terraform files, Railway env references

The deployment model is strongly Railway-oriented, although production readiness should still be independently verified.

4. Backend Domain Features

F-BE-001 — Authentication

Status: exists
Evidence: AuthRoutes.kt, Authentication.kt, JWT config in application.yaml

F-BE-002 — Warehouse management

Status: exists
Evidence: WarehouseRoutes.kt, warehouse references in API/docs, migrations

F-BE-003 — Location/bin management

Status: exists
Evidence: LocationRoutes.kt, LocationService.kt, locations schema

F-BE-004 — Product management

Status: exists
Evidence: ProductRoutes.kt, products table, DTOs/services

F-BE-005 — Inventory management

Status: exists
Evidence: InventoryRoutes.kt, InventoryService.kt, inventory schema, tests

F-BE-006 — Order management

Status: exists
Evidence: OrderRoutes.kt, OrderService.kt, order schema

F-BE-007 — Picking workflow

Status: exists
Evidence: PickingRoutes.kt, PickingService.kt, mfe-picking, tests

F-BE-008 — Receiving workflow

Status: exists
Evidence: ReceivingRoutes.kt, ReceivingService.kt, receiving tables/migrations, discrepancy test

F-BE-009 — Shipment management

Status: exists
Evidence: ShipmentRoutes.kt, ShipmentService.kt, shipment schema, tests

F-BE-010 — Carrier management

Status: exists
Evidence: CarrierRoutes.kt, CarrierService.kt, carriers schema

F-BE-011 — Carrier integration endpoints

Status: exists
Evidence: CarrierIntegrationRoutes.kt, integration clients and services

F-BE-012 — Cycle counts

Status: exists
Evidence: CycleCountRoutes.kt, CycleCountService.kt, tests, schema

F-BE-013 — Stock movements / audit trail for inventory changes

Status: exists
Evidence: StockMovementRoutes.kt, stock_movements table, schema

F-BE-014 — Returns workflow

Status: exists
Evidence: ReturnRoutes.kt, ReturnService.kt, return schema

F-BE-015 — Supplier management

Status: exists
Evidence: SupplierRoutes.kt, SupplierService.kt, supplier schema

F-BE-016 — Zone management

Status: exists
Evidence: ZoneRoutes.kt, ZoneService.kt, zones schema

F-BE-017 — User and role management

Status: exists
Evidence: UserRoutes.kt, RoleRoutes.kt, RbacService.kt

F-BE-018 — Dashboard endpoints

Status: exists
Evidence: DashboardRoutes.kt

F-BE-019 — Barcode support

Status: exists
Evidence: BarcodeRoutes.kt, BarcodeService.kt, ZXing dependencies

F-BE-020 — Audit endpoints

Status: exists
Evidence: AuditRoutes.kt, AuditService.kt, audit schema

F-BE-021 — SSE / real-time update infrastructure

Status: exists
Evidence: SseRoutes.kt, SseService.kt, Ktor SSE dependency

F-BE-022 — Webhooks

Status: exists
Evidence: WebhookRoutes.kt, WebhookService.kt, webhook tables

F-BE-023 — Offline/mobile sync support

Status: partial
Evidence: OfflineSyncRoutes.kt, OfflineSyncService.kt, V7__mobile_pwa_support.sql

F-BE-024 — Health endpoints

Status: exists
Evidence: HealthRoutes.kt, runbooks

5. Frontend / UX Features

F-FE-001 — Shell application

Status: exists
Evidence: frontend/shell

F-FE-002 — Inventory MFE

Status: exists
Evidence: frontend/mfe-inventory

F-FE-003 — Orders MFE

Status: exists
Evidence: frontend/mfe-orders

F-FE-004 — Picking MFE

Status: exists
Evidence: frontend/mfe-picking

F-FE-005 — Settings MFE

Status: exists
Evidence: frontend/mfe-settings

F-FE-006 — AI MFE

Status: partial-to-exists
Evidence: frontend/mfe-ai, AI strategy docs

F-FE-007 — Shared shell + MFE architecture

Status: exists
Evidence: frontend repo structure, module federation dependency, blueprint/docs

6. Database / Tenant Isolation Features

F-DB-001 — PostgreSQL primary database

Status: exists
Evidence: build config, env docs, migrations, runbooks

F-DB-002 — Flyway-managed schema

Status: exists
Evidence: Flyway dependency, migrations, ADR references

F-DB-003 — RLS tenant isolation by `warehouse_id`

Status: exists
Evidence: RLS-AUDIT.md, V6 migration, TenantPlugin docs

F-DB-004 — Warehouse-scoped data model

Status: exists
Evidence: RLS docs, warehouse-based route and domain model

F-DB-005 — Encrypted Fortnox token storage

Status: exists
Evidence: FortnoxTokens.kt, CryptoService.kt, docs

F-DB-006 — Mobile/offline support tables

Status: partial
Evidence: V7__mobile_pwa_support.sql

7. Integration Features

F-INT-001 — Fortnox OAuth

Status: exists
Evidence: FortnoxOAuthRoutes.kt, secrets docs

F-INT-002 — Fortnox sync flow

Status: exists
Evidence: FortnoxSyncRoutes.kt, FortnoxSyncService.kt, runbook incident section

F-INT-003 — PostNord integration

Status: exists
Evidence: PostNord client/service files, docs, secrets config

F-INT-004 — DHL integration

Status: exists
Evidence: DHL client/service files, docs, secrets config

F-INT-005 — Instabee integration

Status: exists
Evidence: Instabee client/service files, docs, secrets config

F-INT-006 — Integration sync logging

Status: exists
Evidence: integration_sync_log schema, runbook references

8. AI Features

F-AI-001 — AI Chat positioning and product surface

Status: partial
Evidence: AI-STRATEGY.md, PRD, mfe-ai

F-AI-002 — Smart Picking / route optimization

Status: partial
Evidence: PRD, AI strategy, runbook mentions

F-AI-003 — Natural language warehouse querying

Status: planned-to-partial
Evidence: PRD + AI strategy

9. Testing / QA Features

F-QA-001 — Backend automated tests

Status: exists
Evidence: backend/src/test/kotlin/*

F-QA-002 — E2E tests

Status: exists
Evidence: e2e/app.spec.ts, e2e/inventory.spec.ts

F-QA-003 — Performance testing structure

Status: partial
Evidence: tests/performance/, infrastructure/k6/

F-QA-004 — Regression test structure

Status: partial
Evidence: tests/regression/

10. Ops / Deployment / Observability Features

F-OPS-001 — Local docker-based dev environment

Status: exists
Evidence: docker-compose.yml, runbooks

F-OPS-002 — Deployment scripts / Terraform infra

Status: exists
Evidence: infrastructure/README.md, main.tf, scripts

F-OPS-003 — Runbooks for incident handling

Status: exists
Evidence: RUNBOOK.md, docs/RUNBOOK.md

F-OPS-004 — Sentry-based monitoring

Status: partial-to-exists
Evidence: backend and frontend Sentry references, runbooks, secrets docs

11. Security Features

F-SEC-001 — JWT auth

Status: exists
Evidence: auth plugin, application.yaml, docs

F-SEC-002 — BCrypt password hashing

Status: exists
Evidence: backend dependencies, security docs

F-SEC-003 — AES-256-GCM token encryption

Status: exists
Evidence: CryptoService.kt, Fortnox token docs

F-SEC-004 — PostgreSQL RLS enforcement

Status: exists
Evidence: RLS migration and audit docs

F-SEC-005 — Role-based access control

Status: exists
Evidence: role/user routes and services

F-SEC-006 — Secret management model

Status: exists but needs cleanup
Evidence: docs/SECRETS-MANAGEMENT.md, infra docs

12. Business / GTM / Commercial Features

F-BIZ-001 — Pricing model

Status: exists in docs
Evidence: README.md, PRD.md, GTM-STRATEGY.md

F-BIZ-002 — Fortnox ecosystem GTM strategy

Status: exists in docs
Evidence: GTM-STRATEGY.md

F-BIZ-003 — Swedish SMB WMS positioning

Status: exists in docs
Evidence: README, PRD, GTM

F-BIZ-004 — 3PL commercial direction

Status: planned
Evidence: PRD, GTM, regulatory references

F-BIZ-005 — Regulatory/compliance framing

Status: exists in docs
Evidence: REGULATORY.md

13. Known Contradictions / Risks

RISK-001 — Stale architecture document

docs/ARCHITECTURE.md conflicts with actual repo reality and must not be used as canonical architecture input.

RISK-002 — API spec likely drifted

docs/API-SPEC.md appears to reflect an org-centric model and may not be fully synchronized with current Ktor routing and warehouse-based tenancy.

RISK-003 — Runbook drift

There are conflicting operational instructions around:

npm vs pnpm
startup flow
JDK/runtime expectations

RISK-004 — Secrets hygiene problem

infrastructure/README.md contains secret-like Terraform environment variable examples that should be reviewed immediately.

RISK-005 — Missing canonical demo-readiness package

The intended documentation package under docs/demo-readiness/ does not exist yet.

14. Summary by Maturity

Exists

Kotlin/Ktor backend
React MFE frontend
Flyway + PostgreSQL
RLS tenant isolation
receiving / inventory / orders / picking / shipments
carrier integrations
RBAC
dashboard/backend operational domains
barcode
audit/webhooks/SSE
backend tests
e2e presence
pricing/GTM/business framing

Partial

AI execution depth
smart picking maturity verification
mobile/offline maturity
shipment monitoring UX depth
reorder alerting maturity
ops/monitoring completeness
performance/regression readiness
API spec accuracy

Planned

3PL billing and mature 3PL workflows
polished demo-readiness package
full support/onboarding package
fully canonical feature and QA documentation set

15. Working Rule

Future planning and QA work must use this feature baseline together with:

canonical source-of-truth map
user stories baseline

Nothing should be marked “implemented” solely because it appears in a stale document or in an agent-generated summary without artifact proof.

Gaps and Next Steps

Source: ~/ALAI/products/Plock/docs/demo-readiness/03-gaps-and-next-steps.md

PLOCK — Gaps and Next Steps

Date: 2026-03-14
Purpose: Convert the current PLOCK reality into an actionable plan: what is missing, what is conflicting, what is risky, and in which order the remaining work should happen.

1. Goal

The original goal was to get PLOCK into a state where we can:

understand the real product and architecture,
produce deterministic documentation,
QA that documentation,
then generate implementation tasks by feature area,
and move toward demo-readiness / production-readiness in a controlled way.

This document defines what blocks that goal today and what sequence should be followed next.

2. Current State Summary

PLOCK already has:

substantial real code,
real integrations,
real tests,
real infrastructure scaffolding,
real product and GTM documentation.

However, PLOCK is currently blocked by:

conflicting architecture documentation,
missing canonical documentation package,
weak documentation-to-artifact execution flow,
and lack of a clean, approved “source-of-truth → QA → backlog” chain.

3. Gap Categories

3.1 Canonical Documentation Gaps

GAP-DOC-001 — Canonical `docs/demo-readiness/` package exists, but is still incomplete

Severity: P0

The canonical demo-readiness package now exists, but it is still only a baseline layer.

Already present:

source-of-truth baseline
user stories baseline
feature baseline
gaps/next-steps baseline
QA checklist baseline

Still missing or incomplete for the fuller package:

program map
deterministic task contract
doc inventory gap audit
package-level review expansion
later demo/sales/support readiness docs
program map
deterministic task contract
doc inventory gap audit
user stories baseline
feature catalog
QA gate checklist

Impact:
Without this package, there is no stable documentation handoff point for QA or implementation backlog generation.

GAP-DOC-002 — No canonical feature catalog

Severity: P0

Features are spread across:

code structure,
PRD,
GTM docs,
API spec,
runbooks,
integration docs.

But there is no single authoritative feature catalog that says:

what exists,
what is partial,
what is planned.

Impact:
Implementation task generation will drift or duplicate work.

GAP-DOC-003 — User stories are present, but not operationalized

Severity: P1

User stories exist mainly in docs/PRD.md, but not yet in a clean, implementation-ready canonical user-story document.

Impact:
Traceability between product vision and implementation work is weaker than it should be.

GAP-DOC-004 — Canonical QA checklist exists, but QA execution is still incomplete

Severity: P0

A trusted QA checklist now exists, but the review process is still immature and must continue with explicit review records and package verdicts.

What now exists:

deterministic QA checklist baseline
package review workflow

What still needs strengthening:

continued document-by-document review records as the package grows
repeatable reviewer discipline for future generated docs
explicit re-review after any canonical doc changes

Impact:
QA can now start approving or rejecting the documentation layer, but the process still depends on careful manual review.

3.2 Architecture / Source-of-Truth Gaps

GAP-ARCH-001 — Conflicting architecture documents

Severity: P0

docs/ARCHITECTURE.md conflicts with the actual repo and stronger docs.

Examples of stale/conflicting claims:

Next.js instead of MFE shell
Express instead of Ktor
Prisma instead of Exposed + Flyway
organization_id instead of warehouse_id

Impact:
Any agent or human using the wrong document can generate incorrect output.

GAP-ARCH-002 — API spec drift

Severity: P1

docs/API-SPEC.md appears useful, but likely drifted from the actual backend implementation and tenant model.

Impact:
API-facing work may be built or reviewed against incorrect assumptions.

GAP-ARCH-003 — Runbook drift

Severity: P1

Different docs disagree on:

npm vs pnpm
startup flow
JDK/runtime expectations

Impact:
Ops/docs/support/demo execution can become inconsistent and brittle.

3.3 Product / Feature Gaps

GAP-FEAT-001 — AI feature maturity unclear

Severity: P1

AI Chat and Smart Picking are core product promises, but actual implementation depth is not yet cleanly verified against code and runtime behavior.

Impact:
Demo promises may exceed current product maturity.

GAP-FEAT-002 — 3PL capability is more strategy than current product

Severity: P1

3PL/client portal/billing appears strongly in docs and GTM, but current implementation evidence suggests this is more Phase 2 than current MVP.

Impact:
Sales/demo scope can overpromise if not constrained.

GAP-FEAT-003 — Sales/marketing/support artifacts not packaged

Severity: P2

The content exists in fragments:

GTM strategy
pricing
regulatory notes
runbooks

But not yet as:

demo script,
objection handling pack,
support playbook,
onboarding checklist,
sales-facing feature matrix.

Impact:
Cross-functional readiness is incomplete.

3.4 Security / Hygiene Gaps

GAP-SEC-001 — Secret-like material in infra docs

Severity: P0/P1

infrastructure/README.md contains environment variable examples that resemble real secrets or secret material.

Impact:
Security hygiene issue. Must be reviewed and cleaned immediately.

GAP-SEC-002 — Secrets/process docs need explicit verification pass

Severity: P1

Secrets strategy exists, but should be validated against:

actual deployment practice,
Vaultwarden usage,
Railway variable setup,
non-committed local env discipline.

Impact:
Production readiness risk if docs and reality differ.

3.5 Process / Orchestration Gaps

GAP-PROC-001 — Delegated doc output quality remains unreliable

Severity: P0

Even after improving task gating, agents still often:

narrate output,
claim files were created,
fail to produce actual artifacts.

Impact:
Important documentation work cannot yet be trusted blindly.

GAP-PROC-002 — Contradictory orchestration logging still exists

Severity: P1

Observed behavior:

task blocked by QA gate,
then orchestrator still logs it as completed.

Impact:
Operational trust and status reporting are still imperfect.

GAP-PROC-003 — Forge worker pool saturation

Severity: P1

Some tasks are delayed or requeued because:

forge pool is full,
H-priority tasks compete with unrelated workload.

Impact:
Even correctly defined tasks may not progress quickly.

4. What Must Happen Before Feature-by-Feature Implementation Tasks

Before generating backend/frontend/db/integration/security/sales/marketing task waves, we need:

Required Preconditions

canonical source-of-truth note
canonical user stories baseline
canonical feature baseline
canonical gaps/next-steps note
canonical QA checklist
clear exclusion of stale architecture doc from planning
security hygiene review of infra secret examples

If these are skipped, implementation tasks will be generated against mixed truths.

5. Recommended Execution Order

Phase 1 — Documentation Truth Lock

Priority: P0

Deliverables

Canonical source-of-truth note
User stories baseline
Feature baseline
Gaps and next steps
QA checklist baseline

Outcome:
One trusted planning layer.

Phase 2 — Documentation QA

Priority: P0

QA should validate the documentation set against:

actual repo structure
actual code domains
actual migrations
actual integrations
actual security/tenant model

QA must explicitly check:

no stale architecture assumptions
no references to nonexistent files
no contradictory stack descriptions
no unsupported feature claims
every feature mapped to status: exists / partial / planned

Outcome:
Trusted doc package.

Phase 3 — Controlled Backlog Generation

Priority: P1

Once the doc package passes QA:

generate backend task list
frontend task list
DB/data task list
integration task list
security task list
sales/marketing/support task list

Rules for backlog generation

Every generated task must include:

exact output contract
exact deliverable path or target
acceptance check
source references
explicit feature/user-story linkage

Outcome:
Deterministic implementation backlog.

Phase 4 — Demo Readiness Pass

Priority: P1

Once the controlled backlog exists:

create demo script
create UI/demo journey map
create sales narrative
create support/onboarding flow
create go/no-go checklist

Outcome:
Real demo package, not vague “prod-ready” claims.

Phase 5 — Production Readiness Pass

Priority: P2

Only after docs + QA + controlled backlog + demo prep:

ops readiness verification
secrets/process cleanup
observability checks
deployment validation
test coverage/reliability review
support and incident readiness

Outcome:
Production-readiness based on evidence, not optimism.

6. Immediate Next Actions

NOW-001 — Freeze stale architecture usage

Treat docs/ARCHITECTURE.md as stale
Do not use it for planning or QA

NOW-002 — Clean security hygiene issue

Review and sanitize infrastructure/README.md
Assume secret-like values may need rotation review

NOW-003 — Finalize canonical documentation baseline

source-of-truth
user stories
feature baseline
gaps/next steps
QA checklist baseline

NOW-004 — Do not launch broad implementation waves yet

no broad backend/frontend/db waves
no mass task fan-out based on stale or mixed docs

NOW-005 — Generate only narrow, deterministic tasks

Until process reliability improves, every task should be:

narrow,
artifact-bound,
source-referenced,
QA-verifiable.

7. Success Condition

We are ready to resume the original plan when all of the following are true:

authoritative vs stale docs are clearly defined
canonical user stories exist
canonical feature baseline exists
canonical QA checklist exists
documentation package passes QA
implementation tasks can be generated from trusted sources only

8. Decision

PLOCK should proceed through a documentation-truth-first path, not a broad parallel execution wave.

This is not extra process for its own sake.
It is the minimum needed to ensure the next backlog is based on the real product rather than conflicting documentation or fabricated agent output.

QA Checklist Baseline

Source: ~/ALAI/products/Plock/docs/demo-readiness/04-qa-checklist-baseline.md

PLOCK — QA Checklist Baseline

Date: 2026-03-14
Purpose: Define the deterministic review checklist that must be applied to every PLOCK demo-readiness document before it is treated as usable input for planning, QA, demo prep, or backlog generation.

1. Why This Exists

PLOCK documentation work has already shown two failure modes:

documents can be generated from conflicting or stale sources, and
tasks can claim deliverables were created when the files do not actually exist.

This checklist prevents both.

A document is not considered approved because:

an agent says it wrote it,
a task says done, or
the text sounds plausible.

A document is approved only if:

the file exists,
the path is correct,
the content matches the requested deliverable,
the claims are grounded in authoritative sources,
contradictions have been checked,
and the document passes the go/no-go review below.

2. Review Scope

Apply this checklist to every document under:

~/ALAI/products/Plock/docs/demo-readiness/

At minimum, this includes:

00-canonical-source-of-truth.md
01-user-stories-baseline.md
02-feature-baseline.md
03-gaps-and-next-steps.md
04-qa-checklist-baseline.md
any later files added to the same package

3. Authority Order

When a demo-readiness document makes a claim, validate it using this precedence:

Actual code and repo structure
Runtime configuration and DB migrations
BUILD-BLUEPRINT.md
README.md
Runbooks / security / ops docs
ADRs
PRD / GTM / Regulatory docs
docs/API-SPEC.md only if verified against code
Never use stale/conflicting docs as canonical truth

Explicit stale-doc rule

docs/ARCHITECTURE.md is currently treated as stale/conflicting and must not be used as a canonical architecture source until rewritten or formally re-approved.

4. Required QA Outcome Labels

Each reviewed document must end in one of these states:

PASS — safe to use as canonical planning input
PASS WITH NOTES — usable, but with explicit caveats recorded
FAIL — not safe to use; must be corrected before downstream work
BLOCKED — cannot be reviewed properly because source evidence is missing or inaccessible

No silent approval is allowed.

5. Pre-Review Checks

Before reading content, verify:

5.1 File existence

The file exists on disk.
The file is readable.
The filename matches the intended deliverable exactly.

5.2 Path correctness

The file is located under the expected canonical path.
If the task specified an exact path, the file is at that exact path.
A similarly named file elsewhere does not count as pass.

5.3 Index discoverability

docs/demo-readiness/INDEX.md links the file if it belongs in the canonical package.
docs/INDEX.md points to the canonical package when appropriate.

5.4 Basic format sanity

Markdown renders as a coherent document.
Headings are structured.
The document is not obviously truncated.
Placeholder/TBD/filler text is either resolved or clearly marked as unresolved risk.

6. Artifact Verification Checklist

A document automatically fails if any of the following are true:

claimed file does not exist
wrong filename
wrong directory
empty or near-empty content
content unrelated to requested deliverable
generic narrative that does not match the task contract
references to files, modules, or paths that do not exist without explicit “unverified” marking

Required artifact review questions

Does the file exist exactly where promised?
Is this the exact deliverable requested?
Does the document content materially satisfy the task?
Is it specific to PLOCK, not generic boilerplate?

7. Content Evidence Checklist

Every substantive claim should be supported by at least one of:

repo path
code module
migration
config file
runbook/security/ADR reference
product/business doc reference

Minimum evidence standard

For each major section, the reviewer should be able to answer:

What source supports this claim?
Is that source authoritative?
Does the claim overstate what the source proves?

Preferred evidence style

Use explicit references such as:

backend/src/main/kotlin/...
backend/src/main/resources/db/migration/...
frontend/mfe-*
docs/PRD.md
docs/RLS-AUDIT.md
README.md
BUILD-BLUEPRINT.md

8. Contradiction Check

The reviewer must actively search for contradictions between the reviewed document and stronger sources.

Mandatory contradiction checks

Verify the document does not incorrectly describe PLOCK as:

Next.js instead of React/Vite MFEs
Express instead of Ktor
Prisma instead of Exposed + Flyway
Supabase/Upstash as primary current stack without proof
organization_id as the current tenant model where repo reality shows warehouse_id

Contradiction rule

If a claim conflicts with code or stronger docs, the document fails unless the conflict is explicitly called out as historical/stale context.

9. User Story and Feature Traceability Check

Every story or feature-oriented document must support traceability.

For user-story documents

Check that stories are:

grounded in PRD and/or real code domains
labeled clearly (exists, partial, planned or equivalent)
not invented purely from marketing language
not duplicated under different names without explanation

For feature documents

Check that each major feature maps back to at least one of:

a route/service/module
a migration/schema element
a frontend MFE/module
a product doc with explicit “planned” labeling

Required traceability rule

A feature that has no code evidence may still appear only if it is clearly labeled planned and anchored to an authoritative product/business doc.

10. Source-of-Truth Compliance Check

The reviewed document must align with 00-canonical-source-of-truth.md.

Reviewer must verify:

repo reality is treated as primary
docs/ARCHITECTURE.md is not treated as canonical truth
docs/API-SPEC.md is used carefully and only with verification caveat if needed
agent-generated narrative is not cited as authoritative evidence

Automatic fail if the document:

treats agent output as primary evidence
uses stale architecture claims as current truth
ignores stronger repo evidence

11. Security Hygiene Check

Every demo-readiness document that touches environments, infra, auth, secrets, integrations, or deployment must be reviewed for security hygiene.

Required checks

No real secrets or secret-like material are copied into the doc.
No environment variable values are presented in a way that looks reusable as production material.
Any reference to infrastructure/README.md must respect the known hygiene issue around secret-like examples.
If secret examples are mentioned, they must be described as hygiene risks, not copied forward as acceptable practice.
Auth, token, encryption, and tenant-isolation claims must match real security docs/code where possible.

Automatic fail examples

document repeats secret-looking example values as if acceptable
document instructs users to commit secrets
document misstates RLS/tenant isolation model
document weakens existing security posture in prose without evidence

12. Canonical Path and Naming Check

The canonical package should remain predictable.

Reviewer should verify:

numbering is consistent
filenames are descriptive and stable
index references are correct
no duplicate “canonical” documents exist with competing names

Naming rule

If a document supersedes another document, the relationship must be explicit. Confusing parallel variants should fail review or be flagged for consolidation.

13. Acceptance Criteria by Document Type

13.1 Canonical source-of-truth docs

Must:

identify authoritative vs stale sources
define precedence clearly
match repo reality
explicitly quarantine stale architecture assumptions

13.2 User-story docs

Must:

identify user roles clearly
phrase stories in a usable operational way
mark maturity/status
avoid unsupported invention
allow later mapping to features and backlog

13.3 Feature baseline docs

Must:

group features coherently
distinguish exists vs partial vs planned
reference code/docs evidence
capture key risks/contradictions

13.4 Gap / next-step docs

Must:

separate current fact from recommendation
prioritize gaps clearly
define execution order
avoid pretending that future work already exists

13.5 QA docs

Must:

be deterministic
define pass/fail rules
include evidence expectations
include final review workflow and go/no-go outcome

14. Reviewer Workflow

Use this exact workflow:

Step 1 — Confirm artifact

file exists
path is exact
file is readable

Step 2 — Confirm task-fit

compare document against requested deliverable
reject generic filler or off-target content

Step 3 — Check evidence

scan each major section for source grounding
verify stronger-source precedence is respected

Step 4 — Check contradictions

compare against repo reality and known stale-doc risks
record any mismatch explicitly

Step 5 — Check traceability

ensure user stories/features/gaps can be traced to evidence

Step 6 — Check security hygiene

especially for env, infra, auth, tokens, integrations, deployment

Step 7 — Record verdict

Document one of:

PASS
PASS WITH NOTES
FAIL
BLOCKED

Step 8 — Record remediation

If not PASS, specify:

exact issue
exact file/section
exact correction needed
whether downstream work must pause

15. Review Record Template

Use this template for every reviewed document:

## QA Review Record
- Document:
- Path:
- Reviewer:
- Date:
- Verdict: PASS | PASS WITH NOTES | FAIL | BLOCKED

### Artifact Check
- Exists:
- Correct path:
- Correct filename:
- Indexed:

### Evidence Check
- Primary sources used:
- Any unsupported claims:

### Contradiction Check
- Conflicts found:
- Stale-doc contamination found:

### Traceability Check
- User-story traceability:
- Feature traceability:

### Security Hygiene Check
- Secret-like material copied: yes/no
- Security posture accurately described: yes/no

### Notes / Remediation
-

16. Go / No-Go Checklist

A demo-readiness document is GO only if all answers below are yes:

Does the file exist at the exact canonical path?
Does it match the requested deliverable?
Is it grounded in authoritative sources?
Does it avoid stale architecture assumptions?
Are major claims evidence-backed?
Are features/stories/gaps traceable?
Are security-sensitive claims hygienic and accurate?
Is the document specific enough to be used downstream?

If any answer is no, the outcome is NO-GO.

17. Package-Level Go / No-Go Rule

The full docs/demo-readiness/ package is not ready for downstream backlog generation until:

core baseline documents exist,
each has passed review,
no unresolved P0 contradiction remains,
and no document relies on stale architecture as current truth.

Package-level blockers

Any of these are automatic package-level NO-GO:

missing canonical file
unresolved architecture contradiction
unverified API assumptions treated as fact
security hygiene issue copied into canonical docs
major feature/story claims without evidence

18. Decision

This checklist is the minimum deterministic QA gate for PLOCK demo-readiness documentation.

No document in this package should be treated as approved planning input until it passes this checklist with an explicit recorded verdict.

Initial Package QA Review

Source: ~/ALAI/products/Plock/docs/demo-readiness/05-initial-package-review.md

PLOCK — Initial Package QA Review

Date: 2026-03-14
Reviewer: John
Scope: Manual QA review of the current canonical PLOCK demo-readiness baseline package under ~/ALAI/products/Plock/docs/demo-readiness/.

1. Package Verdict

Document Quality Verdict: PASS WITH NOTES
Downstream Usage Verdict: GO for narrow documentation-truth work; NO-GO for broad implementation fan-out until remaining P0/P1 issues are addressed.

Why

The package now exists on disk, is indexed, and provides a coherent baseline for source-of-truth, user stories, features, gaps, and QA review.

However, it still carries important caveats:

docs/ARCHITECTURE.md remains stale/conflicting in the repo
docs/API-SPEC.md still requires explicit verification against code
infrastructure/README.md still needs security-hygiene cleanup
the fuller demo-readiness package is not complete yet

2. Artifact Check

Reviewed files

INDEX.md
00-canonical-source-of-truth.md
01-user-stories-baseline.md
02-feature-baseline.md
03-gaps-and-next-steps.md
04-qa-checklist-baseline.md

Result

All reviewed files exist on disk
All are readable
All are located under the expected canonical path
docs/demo-readiness/INDEX.md links the core package correctly
docs/INDEX.md points to the canonical package

Artifact verdict: PASS

3. Per-Document Review Records

QA Review Record

Document: Canonical baseline index
Path: ~/ALAI/products/Plock/docs/demo-readiness/INDEX.md
Reviewer: John
Date: 2026-03-14
Verdict: PASS

Artifact Check

Exists: yes
Correct path: yes
Correct filename: yes
Indexed: n/a (entry point document)

Evidence Check

Primary sources used: package structure itself
Any unsupported claims: none material

Contradiction Check

Conflicts found: none
Stale-doc contamination found: no

Traceability Check

User-story traceability: n/a
Feature traceability: n/a

Security Hygiene Check

Secret-like material copied: no
Security posture accurately described: yes

Notes / Remediation

None

QA Review Record

Document: Canonical source of truth
Path: ~/ALAI/products/Plock/docs/demo-readiness/00-canonical-source-of-truth.md
Reviewer: John
Date: 2026-03-14
Verdict: PASS WITH NOTES

Artifact Check

Exists: yes
Correct path: yes
Correct filename: yes
Indexed: yes

Evidence Check

Primary sources used: repo structure, build docs, runbooks, RLS/security docs, PRD/GTM/REGULATORY docs
Any unsupported claims: no major unsupported claims after path correction and gap refresh

Contradiction Check

Conflicts found: corrected ADR path references from docs/adr/* to adr/*; refreshed outdated “missing package” statements
Stale-doc contamination found: no; stale architecture doc is explicitly quarantined

Traceability Check

User-story traceability: indirect but adequate
Feature traceability: indirect but adequate

Security Hygiene Check

Secret-like material copied: no
Security posture accurately described: yes

Notes / Remediation

Continue using this as the authority map, but refresh remaining-gap section when new canonical docs are added.

QA Review Record

Document: User stories baseline
Path: ~/ALAI/products/Plock/docs/demo-readiness/01-user-stories-baseline.md
Reviewer: John
Date: 2026-03-14
Verdict: PASS WITH NOTES

Artifact Check

Exists: yes
Correct path: yes
Correct filename: yes
Indexed: yes

Evidence Check

Primary sources used: docs/PRD.md, backend route/service structure, integrations, runbook/regulatory context
Any unsupported claims: some maturity labels remain approximate and should be revalidated during runtime/demo verification

Contradiction Check

Conflicts found: no major architecture contradictions found
Stale-doc contamination found: no

Traceability Check

User-story traceability: yes
Feature traceability: mostly yes; evidence is sufficient for a baseline but not yet exhaustive at section-by-section code depth

Security Hygiene Check

Secret-like material copied: no
Security posture accurately described: yes

Notes / Remediation

Good canonical baseline. Later passes should tighten evidence granularity and confirm AI/mobile maturity against runtime behavior, not just repo structure.

QA Review Record

Document: Feature baseline
Path: ~/ALAI/products/Plock/docs/demo-readiness/02-feature-baseline.md
Reviewer: John
Date: 2026-03-14
Verdict: PASS WITH NOTES

Artifact Check

Exists: yes
Correct path: yes
Correct filename: yes
Indexed: yes

Evidence Check

Primary sources used: routes, services, migrations, frontend MFE structure, test folders, ops/security docs
Any unsupported claims: a few maturity judgments remain intentionally approximate (partial, planned-to-partial) and should be revisited during deeper verification

Contradiction Check

Conflicts found: none material
Stale-doc contamination found: no

Traceability Check

User-story traceability: strong enough for baseline planning
Feature traceability: yes, with direct module/file references for most sections

Security Hygiene Check

Secret-like material copied: no
Security posture accurately described: yes

Notes / Remediation

Strong baseline. Future revisions should verify ops/monitoring and AI claims against live behavior before demo commitments.

QA Review Record

Document: Gaps and next steps
Path: ~/ALAI/products/Plock/docs/demo-readiness/03-gaps-and-next-steps.md
Reviewer: John
Date: 2026-03-14
Verdict: PASS WITH NOTES

Artifact Check

Exists: yes
Correct path: yes
Correct filename: yes
Indexed: yes

Evidence Check

Primary sources used: package state, repo findings, orchestration incident findings, doc drift findings
Any unsupported claims: none material after current-state refresh

Contradiction Check

Conflicts found: refreshed outdated statements that previously said the package and QA checklist did not exist
Stale-doc contamination found: no

Traceability Check

User-story traceability: indirect but acceptable
Feature traceability: indirect but acceptable

Security Hygiene Check

Secret-like material copied: no
Security posture accurately described: yes

Notes / Remediation

Keep this document current as additional canonical docs are created; it is time-sensitive by nature.

QA Review Record

Document: QA checklist baseline
Path: ~/ALAI/products/Plock/docs/demo-readiness/04-qa-checklist-baseline.md
Reviewer: John
Date: 2026-03-14
Verdict: PASS

Artifact Check

Exists: yes
Correct path: yes
Correct filename: yes
Indexed: yes

Evidence Check

Primary sources used: actual failure patterns observed in orchestration and documentation work
Any unsupported claims: none material

Contradiction Check

Conflicts found: none
Stale-doc contamination found: no

Traceability Check

User-story traceability: n/a
Feature traceability: n/a

Security Hygiene Check

Secret-like material copied: no
Security posture accurately described: yes

Notes / Remediation

This should be applied to all future additions to the package.

4. Package-Level Notes

What is now good enough

canonical source-of-truth layer exists
user stories and feature baseline exist
gaps/next-steps are documented
deterministic QA criteria now exist
package is discoverable via both filesystem and HiveMind

What still blocks a broad implementation wave

stale docs/ARCHITECTURE.md still exists in the repo and can mislead future agents
docs/API-SPEC.md still needs verification against code
infra security-hygiene issue still needs cleanup
fuller demo-readiness docs remain incomplete

5. Final Go / No-Go

GO

narrow documentation-truth work
narrow source-referenced QA work
controlled backlog preparation based on these canonical docs
explicit review of stale/conflicting docs

NO-GO

broad parallel implementation wave based on legacy docs
claims of demo-ready or prod-ready status without further verification
trusting docs/ARCHITECTURE.md as current truth
trusting docs/API-SPEC.md as canonical without code verification

6. Decision

The current PLOCK canonical baseline package passes manual review as a usable planning foundation, but only with explicit caveats. It is good enough to guide the next narrow, deterministic documentation and QA steps. It is not yet a license for broad implementation fan-out or readiness claims.

API Spec Verification Pass

Source: ~/ALAI/products/Plock/docs/demo-readiness/06-api-spec-verification-pass.md

PLOCK — API Spec Verification Pass

Date: 2026-03-14
Reviewer: John
Scope: Narrow manual verification of docs/API-SPEC.md against the real Ktor route surface under backend/src/main/kotlin/no/alai/plock/.

1. Verdict

Canonical verdict: FAIL as a canonical API source
Reference verdict: PASS WITH NOTES as API-intent/reference material

Why

docs/API-SPEC.md contains useful product intent, but it does not currently match the real backend route surface closely enough to be treated as canonical.

The biggest problems are:

org-centric model appears where repo reality is warehouse-centric
several documented endpoint groups do not exist in the current Ktor app
several real Ktor route groups are missing or materially different in the spec
multiple path shapes differ even when the domain concept is roughly aligned

2. Verification Sources

Primary sources used for this pass:

backend/src/main/kotlin/no/alai/plock/plugins/Routing.kt
backend/src/main/kotlin/no/alai/plock/routes/AuthRoutes.kt
backend/src/main/kotlin/no/alai/plock/routes/WarehouseRoutes.kt
backend/src/main/kotlin/no/alai/plock/routes/LocationRoutes.kt
backend/src/main/kotlin/no/alai/plock/routes/ProductRoutes.kt
backend/src/main/kotlin/no/alai/plock/routes/InventoryRoutes.kt
backend/src/main/kotlin/no/alai/plock/routes/OrderRoutes.kt
backend/src/main/kotlin/no/alai/plock/routes/PickingRoutes.kt
backend/src/main/kotlin/no/alai/plock/routes/ReceivingRoutes.kt
backend/src/main/kotlin/no/alai/plock/routes/CarrierRoutes.kt
backend/src/main/kotlin/no/alai/plock/routes/CarrierIntegrationRoutes.kt
backend/src/main/kotlin/no/alai/plock/routes/ShipmentRoutes.kt
backend/src/main/kotlin/no/alai/plock/routes/RoleRoutes.kt
backend/src/main/kotlin/no/alai/plock/routes/UserRoutes.kt
backend/src/main/kotlin/no/alai/plock/routes/DashboardRoutes.kt
backend/src/main/kotlin/no/alai/plock/routes/SseRoutes.kt
backend/src/main/kotlin/no/alai/plock/integrations/fortnox/FortnoxOAuthRoutes.kt
backend/src/main/kotlin/no/alai/plock/integrations/fortnox/FortnoxSyncRoutes.kt

3. Real Route Surface Snapshot

Routing.kt mounts these main groups under /api/v1 (plus unauthenticated Fortnox OAuth + health/auth):

/auth and /auth/me
/products
/users
/dashboard
/warehouses
/locations
/inventory
/orders
/picking
/zones
/suppliers
/receiving
/carriers
/shipments
/roles
/audit
/stock-movements
/cycle-counts
/returns
/webhooks
/events*
/barcodes
/integrations/fortnox/*

This is already enough to show that the live API surface is broader in some places and materially different in others than docs/API-SPEC.md suggests.

4. Sections That Are Roughly Aligned

These areas are directionally aligned, even when path or payload details differ:

4.1 Auth

docs/API-SPEC.md documents auth/login concepts, and real routes do include:

POST /auth/register
POST /auth/login
GET /auth/me

4.2 Warehouses / products / users / dashboard

These domains exist in the real backend and in the API spec at a high level.

4.3 Carrier + shipment integrations

The spec correctly signals that carrier and Fortnox integration domains exist, although the actual route design is different.

4.4 Real-time events

The spec includes SSE/event streaming, and the real backend does expose:

GET /events/stream
GET /events (legacy alias)
GET /events/connections
POST /events/test

5. Major Drift / Mismatch Areas

5.1 Tenancy model drift

Spec problem: org-centric model
Repo reality: warehouse-centric model

Examples in docs/API-SPEC.md:

Organizations
organization_name
slug
organization object inside auth responses
/organizations/me

Repo reality:

real tenant model is warehouse_id
auth/user DTOs expose warehouseId
no organization route group exists in the Ktor app

Impact: High. This is not a cosmetic difference; it changes the domain model.

5.2 Auth flow drift

Spec says

POST /auth/register creates organization + admin user
POST /auth/refresh exists
POST /auth/logout exists

Actual routes

POST /auth/register
POST /auth/login
GET /auth/me

Mismatch

Real auth routes do not currently expose documented refresh/logout endpoints, and register/login response shapes differ from the org-centric API spec.

Verdict: partial alignment only

5.3 Warehouses and locations path drift

Spec says

/warehouses/:warehouseId/zones
/warehouses/:warehouseId/bins
nested warehouse-scoped bin endpoints

Actual routes

/warehouses
/warehouses/{id}
/locations
/locations/{id}
/zones
/zones/{id}
/put-away/suggest

Mismatch

The real backend models zones and locations as first-class route groups, not nested warehouse bin endpoints as described in the spec.

5.4 Inventory route drift

Spec says

GET /inventory
POST /inventory/adjustments
GET /inventory/transactions
POST /inventory/cycle-count
GET /inventory/anomalies

Actual routes

GET /inventory
GET /inventory/balance
GET /inventory/summary
GET /inventory/search
POST /inventory
POST /inventory/recalculate
GET /inventory/{id}
POST /inventory/{id}/adjust
DELETE /inventory/{id}

Mismatch

The real system exposes different operational endpoints and splits stock adjustment and audit trail differently. Inventory transaction history is represented more directly via /stock-movements, not the spec’s /inventory/transactions route.

5.5 Receiving / inbound drift

Spec says

/inbound/purchase-orders
/inbound/purchase-orders/:poId/receive

Actual routes

/receiving
/receiving/{id}
/receiving/{id}/receive-item
/receiving/{id}/complete
/receiving/{id}/cancel
/receiving/{id}/process
/receiving/{id}/discrepancies
/receiving/discrepancies/{discrepancyId}/resolve

Mismatch

The real backend has a receiving-order workflow, not the purchase-order route structure described in the spec.

5.6 Orders / outbound drift

Spec says

/outbound/orders
/outbound/orders/release
/outbound/orders/:orderId/status

Actual routes

/orders
/orders/{id}
/orders/{id}/allocate
/orders/{id}/deallocate
/orders/{id}/ship

Mismatch

The domain overlaps, but path structure and supported actions differ materially.

5.7 Picking drift

Spec says

/picking/routes
/picking/routes/:routeId/confirm-pick
/picking/routes/:routeId/assign

Actual routes

/picking/waves
/picking/waves/{id}
/picking/waves/{id}/start
/picking/waves/{id}/pick-item
/picking/{pickListId}/items/{itemId}/confirm

Mismatch

The live system is pick-wave/pick-item oriented, not route-assignment oriented in the way the spec describes.

5.8 Carrier / shipment drift

Spec says

/carriers/labels/generate
/carriers/labels/:trackingNumber/status
/carriers/services
/carriers/labels/:trackingNumber/void

Actual routes include

carrier CRUD under /carriers
shipment CRUD and lifecycle under /shipments
provider-specific endpoints under /carriers/postnord/*, /carriers/dhl/*, /carriers/instabee/*
generic integration shipment routes under /shipments in CarrierIntegrationRoutes.kt

Mismatch

The spec compresses real shipping/carrier behavior into a simplified label-oriented interface that does not match the current route surface.

5.9 Dashboard / reports drift

Spec says

/dashboard/stats
/reports/inventory-health
/reports/performance
/reports/export

Actual routes

/dashboard/stats
/inventory/low-stock

Mismatch

Only dashboard/stats is clearly aligned. The /reports/* route group is not present in the current Ktor app.

5.10 AI route drift

Spec says

/ai/chat
/ai/actions/confirm
/ai/chat/history
/ai/pick-route/optimize
/ai/pick-route/job/:jobId

Actual routes

no /ai/* route group was found in the current backend route surface

Mismatch

This is major product-intent content, not current API reality.

5.11 Integrations drift

Spec says

GET /integrations
GET /integrations/fortnox/connect
GET /integrations/fortnox/callback
POST /integrations/fortnox/sync
DELETE /integrations/:provider
webhooks under integrations

Actual routes include

GET /integrations/fortnox/auth
GET /integrations/fortnox/callback
GET /integrations/fortnox/status
POST /integrations/fortnox/sync/articles
POST /integrations/fortnox/sync/orders
POST /integrations/fortnox/sync/stock
POST /integrations/fortnox/sync/products
POST /integrations/fortnox/confirm-shipment/{orderId}

Mismatch

The real Fortnox integration surface is more concrete and warehouse-scoped than the generic integration control plane described in the spec.

5.12 Users / RBAC drift

Spec says

POST /users/invite
PATCH /users/:userId
GET /users/me
mostly flat user-role assumptions

Actual routes include

/users
/users/{id} with GET, PUT, DELETE
/roles
/roles/assign
/roles/user/{userId}
/roles/user/{userId}/permissions
GET /auth/me

Mismatch

RBAC is present, but it is organized differently and more explicitly in the real backend than in the spec.

6. Important Real Route Groups Missing from the Spec

These live route groups exist in the backend but are not represented well, or at all, in docs/API-SPEC.md:

/audit
/stock-movements
/cycle-counts
/returns
/webhooks
/barcodes
/suppliers
/zones
/put-away/suggest
/events/connections
/events/test
/health and /health/ready

7. Practical Conclusion

Use docs/API-SPEC.md only for:

product/API intent
domain discovery hints
identifying candidate workflows to verify against code

Do not use it for:

canonical route inventory
API QA signoff
implementation planning without code check
tenant-model assumptions

8. Recommended Next Narrow Step

Do not rewrite the full API spec yet.

Instead, use this sequence:

keep the current warning on docs/API-SPEC.md
use this verification note as the current interpretation layer
later perform a targeted API-spec correction pass section-by-section, starting with:
- tenancy/auth
- inventory
- receiving/orders/picking
- carriers/integrations

9. Decision

docs/API-SPEC.md is now a verified non-canonical reference.

Until corrected, the canonical API truth for PLOCK remains:

the actual Ktor route files, and
the canonical demo-readiness baseline package.