Epic 003 — Foodtruck Order MVP

Status

Ready

Purpose

Deliver the first Foodtruck Order version that can plausibly be deployed and used during a real foodtruck service. This epic changes the primary specification style from foundation-oriented technical prompts to user stories and externally observable behavior.

The implementation flow is:

human/product intent
→ user story
→ Given/When/Then acceptance scenario
→ executable E2E/integration evidence
→ implementation
→ passing acceptance evidence

The current implementation is tracked in current-state.md. The first five product-administration tasks (MVP-TASK-001 through MVP-TASK-005) and current-order tasks MVP-TASK-006 through MVP-TASK-010 are implemented: the authenticated /kds route has an always-active cart, direct/repeated product taps, item count, exact gross total, review correction, safe abandonment, and bounded operational metadata. MVP-TASK-011 adds the provider-neutral checkout boundary and its deterministic local/test fake, MVP-TASK-012 finalizes non-commercial orders, and MVP-TASK-013 finalizes a commercial order after a confirmed payment. MVP-TASK-014 adds the first active kitchen-queue read and renders the oldest active order as one detailed slip, MVP-TASK-015–017 add the following slips, one compact entry per later order, and the visible active count, and MVP-TASK-018–020 implement the forward path through delivery with appended timestamped history. MVP-TASK-021 adds the two active-state corrections while preserving full chronology. No explicit state selector, live push, or history UI is implemented yet. Later MVP behavior remains specified work. Acceptance scenarios are the behavioral contract, and tests provide executable evidence for the delivered slice.

How to navigate this epic

• Scope, domain language, and global invariants
• Headline journeys
• User stories and acceptance scenarios
• Ordered implementation tasks
• Traceability and evidence conventions

The hierarchy is explicit:

Epic
  → Headline journeys
  → Stories
      → Acceptance scenarios
          ↔ executable evidence
      → Small implementation tasks

Headline journeys are a few long, understandable product demonstrations. Story scenarios are smaller contracts covering success, failure, and boundary behavior. They may use the same test framework, but they are not interchangeable.

Operational loop

configure menu
→ construct order
→ commercial checkout OR intentional non-commercial bypass
→ kitchen queue
→ preparing
→ ready
→ delivered
→ live daily sales

Assume one store, one active KDS, SEK, one configured local timezone, tablet-sized KDS minimum, no offline operation, and the existing Application Zero authentication. The protected product page and KDS use the existing authenticated session. The current identity model has no roles; this epic does not add or imply RBAC.

Surfboard is the selected external payment provider and Swedish fiscal cash-register system, kept behind provider-neutral backend ports. Local development and automated acceptance use the existing deterministic fake. Staging uses Surfboard Demo. A future production environment uses the same adapter with independently managed Live configuration only after certification and operational approval; credentials and environment identifiers are never stored in the repository.

Stable identifiers and status

• Journeys use MVP-JRN-NNN.
• Stories use domain identifiers such as MVP-PROD-001.
• Scenarios append -SNN, for example MVP-PAY-001-S03.
• Tasks use MVP-TASK-NNN.

Once committed, identifiers are never casually renumbered or reused. Retired requirements remain discoverable and are marked superseded with a link to their replacement.

This epic uses the repository statuses Idea, Draft, Ready, In progress, and Done. Update a task's document and the task index together. Ready means the task is implementable when its declared dependencies have landed. A story is Done only when all required scenarios have their specified passing evidence, traceability is intact, relevant lower-level tests pass, the project Definition of Done is satisfied, and no result violates a global invariant.

Specification map

Implementation contract

Each implementation agent reads this README, scope, the selected story and task, AGENTS.md, and relevant canonical guides, then inspects actual code. Implement only the selected increment. Put every applicable scenario ID in test titles or native metadata, for example:

test("[MVP-KDS-002-S02] preparing order advances to ready", async () => {});

Use E2E for externally observable flows; use integration tests for persistence, history, checkout safety, and domain invariants that would be artificial through a browser. Architecture/static or discovery/manual evidence is valid only where the scenario says so. Update traceability, normal project documentation, current state, and handover as part of implementation. pnpm traceability:check mechanically rejects duplicate or dangling IDs, scenarios without an evidence declaration, and missing/duplicate/Planned index rows; it cannot judge whether the named evidence proves a scenario.

No implementation in this specification change

The files in this epic define requirements and future work. Their presence is not evidence that products, orders, checkout, KDS, history, sales, or Surfboard support exists.