Decision 0016 — Six-Phase Delivery And Tenant Productization¶

Status: ACCEPTED
Authority: RATIONALE_ONLY
Date: 2026-08-25
Supersedes: Decision 0013 phase count and the placement of PostgreSQL as Phase 5
Retains: Decision 0013 separation of Product Core, cohort migration, current-operation migration, process evolution and persistence; Decision 0014 continuous Phase-1/Phase-2 evidence rules
Current Roadmap: ../ROADMAP.md
Documentation authority: ../README.md
Partially superseded by: Decision 0027, only basic administration placement and blanket advanced-console sequencing

Currently Applied Scope¶

The phase layout and alternatives below are the basis of the 2026-08-25 decision. Some of the blanket prerequisites for the basic administration feature layout and the advanced console are partly superseded by Decision 0027. The six-phase split and the Phase-6 persistence boundary are kept in that follow-up decision too. The current phase and exit conditions are in ROADMAP, and the real work state in the Task and git history. Revisit results are reflected in the basis, impact and supersession relation of the relevant ADR and in the current specification. ROADMAP updates the phase and exit conditions, and the Task and git history updates the work scope and results. The retired EXECUTION ledger and a separate Task manifest are not created again.

Context¶

The program direction remained one modular multi-tenant logistics Product, but the five-phase Roadmap left two material ambiguities:

Phase 1 officially described Booking only even though a read-only Transload surface already serves as the second real consumer of shared collection/workspace contracts.
Configuration-only onboarding was a Product horizon but had no phase owner or exit gate because PostgreSQL occupied Phase 5.

Current source also shows that Phase 2 cannot safely expand through MK workflows while profile resolution is hard-coded/inferred, missing module assignment is compatible fail-open, business actions are largely menu-authorized, typed configuration provenance is incomplete and some exposed Admin actions have no implemented handler.

The decision must avoid both extremes:

postponing all tenant foundations until after both cohort migrations; and
building a broad Control Plane before a real operator journey consumes it.

Alternatives¶

Alternative 1 — Keep Five Phases And Treat Multi-Tenancy As Cross-Cutting¶

Keep PostgreSQL in Phase 5 and add tenant-profile/configuration requirements to individual Tasks.

Advantages

minimal document and phase-number change;
no new program boundary.

Disadvantages

no single owner or exit gate for configuration-only onboarding, release rollback, support-console separation and tenant operational hardening;
cross-cutting work can be repeatedly deferred;
Phase 2 may continue to accumulate menu, tenant-ID and cohort-adapter debt.

Alternative 2 — Complete The Full Control Plane Before Phase 2¶

Pause Trade/Inventory work until profile, module, capability, config, versioned publication, third-tenant onboarding and support operations are all complete.

Advantages

strong tenant model before business expansion;
fewer temporary compatibility paths.

Disadvantages

horizontal platform construction precedes the real consumer;
high speculative-framework and untyped-rule-engine risk;
delays the operator value and business invariants that should shape configuration;
violates value-first bounded delivery.

Alternative 3 — Split Minimum Runtime Foundation From Full Productization¶

Complete only the tenant Runtime and bounded Admin applied-state capabilities required by Phase 1 and Phase 2, then make full Productization an explicit Phase 5 and move PostgreSQL to Phase 6.

Advantages

every early foundation element has an immediate Booking, Transload or Trade/Inventory consumer;
prevents tenant/customer branches before Phase-2 verticals become harder to unwind;
provides a dedicated exit gate for configuration-only onboarding and operational support;
keeps database-engine migration after Product and tenant semantics stabilize.

Disadvantages

adds one program phase and renumbers persistence work;
requires careful boundary enforcement so Phase 2 does not absorb the full Control Plane;
retains explicit compatibility states during staged rollout.

Decision¶

Choose Alternative 3.

The authoritative phase order becomes:

Phase 1  Product Core: Booking + read-only Transload foundation
Phase 2  MK migration + Trade/Inventory proof + minimum tenant Runtime foundation
Phase 3  current CTC migration
Phase 4  shared Product evolution and new pages
Phase 5  multi-tenant Productization and Control Plane completion
Phase 6  PostgreSQL persistence migration

Phase-1 Transload Boundary¶

Phase 1 proves Transload list, detail, UUID deep link and shared collection/workspace behavior only. Transload writers, status transitions, appointment, Scale, yard, trucking, evidence effects, route/writer cutover and caller-zero remain Phase 3.

Tenant Foundation Boundary¶

Phase 2 owns only what its real journeys require:

persisted operating profile
explicit module state
business capability authorization
typed configuration and effective-state resolution
Admin UI/API contract repair
bounded Tenant/Platform Admin applied-state management

Phase 5 owns:

draft/validate/impact/approve/publish/readback/rollback
configuration-only third-tenant onboarding
template/bootstrap lifecycle
Support/Engineering/QA Console separation
mass-action and repair governance
tenant operational hardening

Stable profile keys describe operating models, not customers. Cohort labels and numeric client IDs remain migration evidence or compatibility aliases.

Consequences¶

Positive¶

the user's intended Product Core -> MK -> CTC -> new pages -> multi-tenant -> PostgreSQL sequence is explicit;
Phase 2 cannot claim completion while relying on menu-only authorization or hard-coded profiles;
full Control Plane work has a dedicated owner and measurable onboarding outcome;
PostgreSQL no longer competes with unresolved Product and tenant semantics;
current Legacy migration and later process redesign remain separate.

Negative¶

existing queued persistence Task numbers become superseded planning records;
the execution registry grows and requires predecessor maintenance;
Phase-1 acceptance is completed after part of the Phase-2 tenant Runtime foundation because the authenticated multi-profile contract is shared;
compatibility states must be visible and reduced rather than removed in one step.

Guardrails¶

no customer/cohort-specific backend package, adapter, writer or business branch;
no arbitrary configuration language;
no broad Admin migration before a bounded consumer;
no PostgreSQL implementation before Phase-5 acceptance;
no local/cloud synchronization design hidden inside persistence migration;
no source/page/HTTP success claim above its evidence level.

Revisit¶

Revisit this decision only if one of the following is proven:

the third compatible tenant requires a different Product semantic owner rather than configuration;
the minimum Phase-2 tenant foundation cannot support two profiles without a larger boundary;
the Control Plane has an immediate commercial requirement that justifies earlier versioned publication;
persistence limitations block an accepted operator journey and cannot be contained in the MySQL adapter;
Phase-3 migration proves local/cloud authority must be decided before Product evolution.

Rollback¶

Restore the five-phase numbering and prior Phase-5 persistence placement only through a superseding decision. Runtime, DB, route, writer, deployment and Legacy effects are not required to roll back this Roadmap decision.

Source: new-system/docs/decisions/0016-six-phase-delivery-and-tenant-productization.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged. A user instruction quoted inside the text is kept in its original language.