Circuit-Forge/focus-flow
6
0
Fork 0
forked from eva/focus-flow
Code Pull requests Activity
focus-flow/archive/Archived plans/V1_BLOCK_17_Backend_Acceptance_Handoff.md

7.5 KiB
Raw Blame History

V1 Block 17 — Backend Acceptance and Handoff

Status: Planned

Purpose: Prove the V1 backend as an integrated product surface, synchronize the documentation with actual behavior, and establish a hard gate before any UI foundation work begins.

Chunk 17.1 — End-to-end V1 scenario suite

Recommended Codex level: extra high

Tasks:

Create application-level scenarios that execute against both the in-memory composition root and MongoDB-backed composition root for:

  • title-only quick capture to Inbox/Backlog with neutral defaults
  • scheduled quick capture requiring duration
  • backlog filtering/sorting/staleness and restore to next available slot
  • flexible insertion/push with stable order
  • protected Free Slot avoidance and required interrupt reporting
  • recurring hidden locked blocks and one-day remove/replace/add overrides
  • manual compact Today plus full timeline and temporary locked reveal
  • critical miss to backlog and inflexible miss retained in history
  • push to tomorrow/top of queue
  • once-per-day end-of-day rollover and notice acknowledgement
  • surprise work with flexible repair, required/locked overlap reporting, and persistent actual occupancy
  • break-up, child scheduling, last-child parent completion, and force completion
  • late and locked-hour completion statistics
  • project learned suggestions without configured-default overwrite
  • task reminder override and Free Slot reminder suppression
  • restart/reload persistence of every authoritative result

Rules:

  • Scenarios must use public application use cases, not reach into repositories to simulate success.
  • Run each applicable scenario against both backends through the conformance harness.
  • Assert business outcomes and invariants, not only serialized snapshots.
  • Do not add V2 features to make a scenario pass.
  • MongoDB scenarios require an actual disposable supported deployment.

Acceptance criteria:

  • Every human-document MVP acceptance criterion maps to a passing scenario or an explicitly approved out-of-scope note.
  • In-memory and Mongo-backed results are behaviorally equivalent.
  • Restart/reload preserves tasks, time semantics, statistics, settings, and operation idempotency.
  • No locked/inflexible placement moves automatically.
  • The V1 traceability matrix is fully updated.

BREAKPOINT: Stop here. Confirm high mode before resilience and performance acceptance.

Chunk 17.2 — Resilience, concurrency, and performance acceptance

Recommended Codex level: high

Tasks:

  • Run deterministic property/invariant suites at expanded seeds/case counts.
  • Test concurrent pushes/inserts against the same queue and confirm revision conflicts or serialized success without lost updates.
  • Test interrupted/retried application commands before and after transaction commit.
  • Test migration of the checked-in legacy fixtures in a disposable MongoDB database.
  • Test DST, leap-day, midnight, and local-date rollover end to end.
  • Test practical Today/Backlog query and scheduling performance at documented V1 data volumes.
  • Test operation/activity retention and document-size guards.
  • Test adapter startup with missing/invalid configuration and verify safe failure.
  • Run static analysis, all unit/contract/integration tests, and diff checks.

Rules:

  • Performance thresholds must reflect product-scale V1 use, not arbitrary benchmark theater.
  • Do not waive a correctness failure to meet a timing target.
  • A flaky concurrent test must be fixed or made deterministic, not retried until green.
  • Integration tests may be separately tagged but are mandatory for backend gate completion.
  • Record exact commands and environment requirements.

Acceptance criteria:

  • No lost-update or partial-commit case remains in the tested command set.
  • Migration, time-zone, and retry scenarios pass.
  • Documented V1 data-volume performance stays within the accepted guardrails.
  • All verification commands pass.
  • The acceptance report contains reproducible commands and results.

BREAKPOINT: Stop here. Confirm medium mode before documentation and API handoff.

Chunk 17.3 — Documentation, schema, and application API handoff

Recommended Codex level: medium

Tasks:

  • Update the root README to describe the completed backend rather than the former “persistence preparation only” state.
  • Update architecture notes with the selected runtime topology, application layer, transaction model, time semantics, and remaining production boundary.
  • Update human documentation only where implemented V1 behavior resolved a contradiction; preserve V2/wishlist boundaries.
  • Publish application-use-case examples for Today, Backlog, quick capture, rollover, locked overrides, surprise logging, child tasks, and reminders.
  • Publish the V1 document schema, stable codes, indexes, migration procedure, and repository conformance command.
  • Document local in-memory and Mongo-backed startup/test commands.
  • Document known limitations and release blockers, especially any unresolved production auth/deployment decision.
  • Synchronize the V1 coverage/traceability matrix with actual test file names and scenario identifiers.

Rules:

  • Do not claim production readiness for unresolved auth, deployment, or platform notification delivery.
  • Do not claim V2 features are implemented.
  • Examples must call public application interfaces.
  • Do not expose real credentials or connection strings.
  • Use calm product language in any sample notices.

Acceptance criteria:

  • A new developer can identify the backend entry point and run both test modes.
  • Schema/migration/runtime requirements are documented.
  • API examples match compiled public interfaces.
  • Known limitations are explicit.
  • Documentation and traceability agree with tests.

BREAKPOINT: Stop here. Confirm low mode before closing and archiving the backend plans.

Chunk 17.4 — Backend completion gate and plan archive

Recommended Codex level: low

Tasks:

  • Run the final documented verification command set, including mandatory MongoDB integration acceptance.
  • Confirm every Block 11–17 acceptance criterion is complete or has an explicitly approved documented exception.
  • Confirm every V1 user intent is available through an application use case and every authoritative entity has a versioned persistence codec.
  • Confirm the pure core has no Flutter or MongoDB client dependency.
  • Confirm no UI/client bundle contains database credentials.
  • Mark completed Block 11–17 plans Complete and move them to Codex Documentation/Archived plans/ in bounded archive commits.
  • Leave Block 18 in Current Software Plan/ as the next active plan.
  • Update Current Software Plan/README.md to state the backend gate result and next required Codex level.

Rules:

  • Do not mark the gate complete with skipped MongoDB integration tests.
  • Do not archive an incomplete block.
  • Do not hide release blockers in commit messages only; keep them in repository documentation.
  • Use conventional commits for completion and archive moves.
  • Stop before creating Flutter files.

Acceptance criteria:

  • Final format/analyze/unit/contract/integration/diff checks pass.
  • Blocks 11–17 are accurately marked and archived.
  • Block 18 is the only active numbered implementation plan.
  • Backend limitations/release blockers are visible in the README/architecture docs.
  • The repository is at a clean, committed backend handoff point.

BREAKPOINT: Backend gate. Stop here. Confirm high mode and explicit approval to start Block 18; the UI design is still intentionally provisional.

Commit suggestion:

docs(plan): archive completed v1 backend blocks