AI-First Commerce Operations Investigator

This repository will implement a bounded operations workflow that explains why a paid order has not reached shipment creation and can create a persistent human-review escalation.

Current state

Phases 0 and 1 are complete. The PostgreSQL schema proposal was accepted on 2026-07-30 and is now the database implementation source of truth. Phase 2 is the next permitted phase and must start in a separate coding session with its own prompt.

The user removed apps/docs and initialized a Prisma skeleton in packages/db. The Prisma schema remains empty. No accepted Phase 1 entity, migration, application workflow, AI behavior, or MCP implementation exists in code yet.

Related MCP server: Datashift MCP Server

Plan and working instructions

• Final plan

• Workflow contract

• Package graph

• Approved PostgreSQL schema

• Schema acceptance summary

• How to use the phase prompts

• Coding-agent instructions

Phase 1 was a documentation-only client-review gate. Its schema is accepted; no Prisma model or migration was created. Use only the Phase 2 prompt in the next coding session and stop at its review gate.

Implementation status

Verified commands

Phase 0 verified the current workspace with:

• bunx prettier --check AGENTS.md README.md docs/**/*.md

• bun run --filter @repo/ui check-types

• bun run --filter @repo/ui build:components

• bun run check-types

• bun run --filter @repo/ui lint

• bun run lint

The desktop shell required /Users/ritikagupta/.bun/bin on PATH. The first root typecheck exposed a starter prerequisite: @repo/ui must be built before the apps can resolve its generated dist exports. The typecheck passed after that package-level build.

See the Phase 0 evaluation report for expected and actual results. No migrate, seed, reset, development, evaluation-harness, or runtime workflow command exists or was claimed for this documentation-only phase.

Phase 1 checks passed for required schema tokens/ER references, client-summary consistency, Markdown formatting, whitespace, unchanged packages/db, and absence of migrations. Mermaid CLI was unavailable, so the ERD received manual syntax review. Full results are in the Phase 1 evaluation report.

No Prisma model, generation, validation, migration, or database command was run.

Plan-intake checks completed:

• pdfinfo docs/plans/Diligence_AI_Commerce_Operations_Final_Plan_Updated.pdf - 13 pages, PDF 1.7, unencrypted.

• shasum -a 256 docs/plans/Diligence_AI_Commerce_Operations_Final_Plan_Updated.pdf - cccc22a5bf3ffae29364c5be78c8b26ed9a2f89c6501fb9cc3abffcbb741d802, matching the supplied source file.

Demo cases

These are planned synthetic scenarios, not implemented fixtures.

Safety guarantee for this prototype

The intended runtime exposes no commerce-state mutation capability. Operational commerce data is read-only. Allowed writes are limited to investigations, immutable evidence snapshots, human-review escalations, idempotency records, and append-only audit events.

This is currently a documented boundary, not yet an implemented or tested guarantee. Phase reports and guardrail tests must provide the evidence as implementation proceeds.