# 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:

```text
docs(plan): archive completed v1 backend blocks
```