Plock — Demo Readiness Canonical PLOCK baseline package, QA review, and narrow verification notes. 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 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 05-initial-package-review.md 06-api-spec-verification-pass.md 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.