Skip to content

This is an internal working record, not an everyday instruction. It was written while the system was being rebuilt, for whoever maintains it. If you are here to do today's work, use the everyday documents instead: Procedures · Processes · Runbooks · The working day, step by step

Loader Assignment, Execution, Clock And Break Policy Decision Matrix

  • Status: P6-007 DECISION INPUT / NOT USER-APPROVED
  • Source reconciliation: INBOUND_PLANNING_ASSIGNMENT_LOADER_RECONCILIATION.md
  • Migration packet: INBOUND_PLANNING_MIGRATION_PACKET.md
  • Source baseline: 4fc2f5a893765fbb95e0a2bdcb971322b0ec9fc0
  • Owners: Operations/Product decide policy; P2 validates access; P5/P12 implement accepted contracts
  • Effect boundary: documentation only

1. Decision Summary

ID Topic Current source fact Recommended target M4 impact
LDR-POL-001 Process decomposition one atomic document covers planning, execution, time and Break current umbrella becomes composite or explicit capability umbrella; child owners separate blocking
LDR-POL-002 Normal execution entry Assignment Board and Loader Page both Start/Complete Loader Page normal path; Office board override/recovery only blocking
LDR-POL-003 Loader identity comma-separated user IDs in LOADER_NAME typed assigned-Loader set; legacy field hidden by repository adapter blocking
LDR-POL-004 Multi-Loader source supports multiple tokens; ownership semantics unclear designate primary executor plus supporting Loaders, or forbid multiple for Start authority blocking
LDR-POL-005 One active job UI presents one current job; server parity not fully proven one active physical job per Loader unless explicit team-job rule blocking
LDR-POL-006 Queue order persisted order plus legacy fallback; UI controls Start availability server validates next eligible item; UI mirrors reason blocking
LDR-POL-007 Clock In before Start no universal server prerequisite found require Clock In for Loader self-service Start; allow audited manager recovery override user decision required
LDR-POL-008 Clock Out with active job Clock Out releases scheduled jobs; active-job handling not defined block self-service Clock Out while active job or open Break; manager correction path handles exceptions blocking
LDR-POL-009 Clock Out assignment release scheduled/unstarted assignments released in same local transaction retain explicit released-ID result and separate reassignment/notification blocking
LDR-POL-010 Break storage Break reuses planner row keep compatibility adapter initially; domain uses BreakQueueItem non-blocking if hidden
LDR-POL-011 Break current condition self-service requires assigned Loader and Telegram sent separate READY_FOR_BREAK business readiness from provider send evidence; preserve current gating until approved replacement blocking
LDR-POL-012 Break priority Break shares Loader queue/order explicit precedence rule relative to active/current/next job blocking
LDR-POL-013 Break duration/pay 10-minute paid; lunch 30-minute unpaid explicit tenant workforce policy with unit/minutes/pay classification blocking
LDR-POL-014 Break expiry owner read/list/timeline/cron may close expired Break one worker/explicit command owns expiry; reads are side-effect free blocking
LDR-POL-015 Telegram local state and send result can diverge durable intent/result or bounded reconciliation; never replay business command to resend blocking for effect migration
LDR-POL-016 QuickBooks Time local event commits first; external sync after commit preserve local authority, explicit external status/manual review blocking for workforce M4
LDR-POL-017 Office override Office/Admin can act with explicit Loader token semantic override capability, reason and audit blocking
LDR-POL-018 Undo compensation is incomplete across all effects variant-specific correction/compensation; no full rollback wording blocking for completion migration
LDR-POL-019 Completion files/fields UI and variant requirements differ server-owned variant schema and validation blocking
LDR-POL-020 Post-completion handoff downstream varies by completion type explicit child-process identity/readback per variant blocking

2. Process Composition

Options

A. Keep one atomic process

Simple registry but poor migration boundaries. Planning, Loader, Clock, Break and provider effects remain one oversized owner.

B. Convert current ID to composite and add atomic children

Best semantic clarity, but stable-ID/type change requires registry and downstream review.

C. Keep current ID as compatibility umbrella and introduce capability packets before formal type change

Lower immediate disruption. Migration packets enforce separate commands while registry decision waits.

Recommendation

Use C now, then approve B when registry consumers and scenario ownership are reconciled.

3. Normal Loader Entry And Office Override

Current fact

Both Assignment Board and Loader Page can invoke Start/Complete.

Forklift Operator normal path
= Loader Page

Office/Manager Assignment Board
= plan, assign, reorder, monitor
+ audited override/recovery when required

Override requires:

  • semantic capability;
  • selected Loader identity;
  • reason for acting on behalf of Loader;
  • same command and invariant set;
  • audit/correlation;
  • no hidden bypass of Clock/Break/queue rules unless the override contract names it.

4. Loader Identity And Multi-Loader Assignment

Current fact

LOADER_NAME is a comma-separated field containing user IDs. Current UI can assign multiple Loaders.

Policy choices

A. One primary Loader only

Simplifies queue, Clock and Start ownership.

B. Primary plus supporting Loaders

One primary owns Start/Complete; supporting Loaders are visible participants and may receive notification.

C. Any assigned Loader can Start/Complete

High concurrency/duplicate ambiguity.

Recommendation

Use B if Operations needs teams; otherwise A. Do not use C without a shared-team-job state and concurrency contract.

Target fields:

primaryLoaderId
supportingLoaderIds[]
assignedBy
assignedAt
assignmentVersion or conditional state

Initial migration may derive these from legacy token order, but the order's business meaning must be approved first.

5. One Active Job And Queue Order

For self-service Loader Start:

  • Loader is Clocked In when policy requires it;
  • no open Break;
  • no other active physical job;
  • target planner is assigned to that Loader;
  • target is the first eligible queue item after current approved exceptions;
  • planner/transload state is startable;
  • conditional update succeeds.

Office override may bypass queue order only with explicit capability/reason, not by using a different UI.

Queue order must be enforced server-side. React merely displays the server decision and reason.

6. Clock In Before Job Start

Options

A. Mandatory

Forklift Loader must be Clocked In before Start.

B. Independent

Job events can exist without attendance Clock state; reconciled later.

C. Mandatory for self-service, manager recovery override

Recommendation

Use C. It preserves normal workforce integrity while allowing controlled correction for missed Clock In.

Required manager recovery:

  • create/correct missing Clock event with reason;
  • exact current-state reread;
  • then Start or reconcile existing job;
  • no silent synthetic Clock event in the job command.

7. Clock Out Policy

Current behavior

Clock Out creates the local event and releases scheduled assignments in one transaction, then attempts QuickBooks Time sync after commit.

  • no active Loader job;
  • no open Break;
  • current Clock state is Clocked In;
  • show scheduled assignments that will be released;
  • explicit confirmation.

Result

CLOCK_OUT committed
+ released scheduled assignment IDs
+ local current state
+ separate QBO Time effect status

Clock Out does not complete or undo an active job. Manager correction handles exceptional missed/late events.

8. Break Queue Readiness And Telegram

Current fact

Break self-service becomes available only when:

  • active current-date Break row is assigned to the Loader;
  • status is Scheduled and no start time exists;
  • Telegram LAST_SENT_TIME exists;
  • the Break is selected as current by queue behavior.

Decision

Is Telegram delivery itself the approval signal, or merely notification of an already-approved Break?

Recommendation

Model:

Break approval/readiness
= local queue state and ordering

Telegram
= notification effect

During compatibility, preserve the current requirement that notification be sent before self-service Start if Operations relies on it. The target contract must still store local READY_FOR_BREAK independently so provider outage can be recovered without changing business meaning.

9. Break Priority

Required explicit policy among:

  • active physical job;
  • current Break;
  • next assigned job;
  • urgent/priority work;
  • lunch versus paid Break;
  • late/expired Break.

Recommended initial rule:

  1. active physical job cannot be interrupted except approved pause/exception path;
  2. approved current Break precedes the next not-started job;
  3. only one open Break;
  4. Break does not erase assignment queue;
  5. completion resumes/re-notifies next queue according to local policy.

10. Break Duration And Pay

Current source:

10MIN BREAK = 10 minutes, paid
LUNCH BREAK = 30 minutes, unpaid

Target policy fields:

breakType
scheduledDurationMinutes
paid
requiresNotification
selfServiceAllowed
lateStartPolicy
overrunPolicy

Do not derive pay status by searching free-text note for lunch in target domain code.

11. Break Expiry Owner

Current problem

Read/list/timeline/cron paths can invoke expired-Break closure and create staff-time effects. This hides mutation behind a read and makes duplicate/observability behavior harder to reason about.

scheduled worker tick
-> claim due Break instance idempotently
-> confirm current Started/open state
-> append one BREAK_OUT
-> complete Break queue item
-> enqueue next-queue notification if required
-> reread and record result

Manual manager recovery handles missed/incorrect closure.

Until worker migration, characterize every current caller and preserve idempotency before moving ownership.

12. Telegram Effect Policy

For assignment, Break, completion and next queue:

local business result
+ notification intent
+ provider attempt/result
+ retry/manual fallback

Required stable identity:

  • tenant;
  • notification type;
  • Loader/user/Telegram destination;
  • related planner/transload/Break ID;
  • logical version or event;
  • message/result identity where available.

Failure never authorizes replay of assignment, Start, Complete, Clock or Break command.

13. QuickBooks Time Policy

Current fact

Local T_STAFF_TIME_EVENT commits first. QuickBooks Time is attempted after commit, can be skipped and can require manual review.

LOCAL_RECORDED
SYNC_PENDING
SYNCED
SYNC_FAILED_RETRYABLE
MANUAL_REVIEW_REQUIRED
NOT_CONFIGURED

These states may be derived from approved integration evidence rather than added to the core event table. Do not expose OAuth/provider detail to ordinary Loader UI.

14. Completion Variant Policy

Each completion variant requires a server-owned schema:

allowed current state
required fields/files
quantity/weight/location/seal rules
transaction owner
downstream child processes
post-commit effects
correction/Undo limit

The browser cannot be the only enforcer of photo count, Loader assignment or completion field requirements.

15. Downstream Handoff Policy

Completion type Required next process/readback
Reload / Transload Final Loading Review Pending/derived state
Unload Inventory Lot/warehouse placement and/or Yard follow-up
Spare approved inventory/lot/Final Review relation depending source contract
Domestic Pickup customer/order and completion owner readback
Stack footprint review explicit Office/Warehouse review queue/result

Loader Complete does not itself prove any child process completed.

16. Wiki Decision

Current slugs: inbound-planning, loader-yard, roles, errors-recovery, ctc-daily.

Recommended content separation:

  • Office Planning And Assignment;
  • Loader Current Job And Queue;
  • Time Clock;
  • Break/Lunch;
  • notification failures;
  • completion variants and next process;
  • manager recovery/escalation.

A single page may link these sections, but role-specific procedures should not force a Loader to read Office planning internals.

17. User Decision Package

Approve or revise:

  1. current umbrella decomposition;
  2. normal Loader page and Office override;
  3. primary/supporting multi-Loader model;
  4. one-active-job and server queue order;
  5. Clock In requirement;
  6. Clock Out active-job/open-Break policy;
  7. local Break readiness versus Telegram;
  8. Break priority/duration/pay/overrun;
  9. worker-owned expiration;
  10. Telegram/QBO reconciliation visibility;
  11. completion variant server schemas;
  12. downstream handoffs;
  13. Wiki role structure;
  14. migration wave order.

Until approved, recommendations remain migration inputs and current source behavior remains compatibility, not target Product policy.

---

Source: docs/processes/LOADER_WORKFORCE_POLICY_DECISION_MATRIX.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.