# V1 Block 13 — Lifecycle, Statistics, Project Defaults, and Reminder Policy

Status: Complete on 2026-06-25.

Purpose: Centralize task transitions, update internal statistics exactly once,
add project-level learned suggestions, and expose reminder-policy decisions
without implementing V2 history UI or platform notification delivery.

## Chunk 13.1 — Canonical transitions and internal activity records

Recommended Codex level: high

Status: Complete on 2026-06-25.

Tasks:

- Introduce one canonical transition service for completion, miss, cancel,
  no-longer-relevant, push, move to backlog, restore from backlog, and activation.
- Route existing flexible and required action services through that transition
  contract or deprecate their duplicated transition logic.
- Add immutable internal activity records with stable IDs, operation IDs,
  activity codes, task/project references, occurred-at time, and the minimum
  structured metadata needed for statistics and idempotency.
- Add explicit completion time and optional actual interval to the task/completion
  model defined in Block 11.
- Enforce allowed transitions and idempotent terminal-state behavior.
- Preserve critical-missed-to-backlog and inflexible-missed-in-place semantics.
- Record push and backlog movement as activities without turning them into task
  statuses.
- Keep activity records internal/application-facing; do not add a visible task
  history feature.

Rules:

- A repeated command with the same operation ID must not create another activity
  or apply the transition twice.
- Terminal transitions must not silently reopen tasks.
- Every transition returns a typed result, not an exception for expected user
  states.
- Unexpected programmer misuse may still assert/throw at an internal boundary,
  but application input must receive typed failures.
- Do not add overwhelm-shield or burnout-catch-up transitions.

Acceptance criteria:

- All V1 lifecycle actions pass through one transition rule set.
- Activity records distinguish manual push, automatic push, backlog movement,
  completion, miss, cancellation, and no-longer-relevant.
- Duplicate operation IDs are exactly-once.
- Required-task missed behavior matches the product specification.
- Existing action tests are migrated without losing coverage.

Verification on 2026-06-25:

- `dart format lib test`: passed, 0 files changed
- `dart analyze`: passed, no issues found
- `dart test`: passed, 211 tests
- `git diff --check`: passed

BREAKPOINT: Stop here. Confirm `extra high` mode before implementing completion
accounting and locked-hour statistics.

## Chunk 13.2 — Completion accounting and exactly-once task statistics

Recommended Codex level: extra high

Status: Complete on 2026-06-25.

Tasks:

- Update manual-push, auto-push, moved-to-backlog, restored-from-backlog, missed,
  and cancelled counters from canonical activities exactly once.
- Calculate `completedLateCount` from completion time versus the applicable
  planned end under the documented policy.
- Expand locked occurrences for the completion/actual interval and calculate:
  - completed during locked hours count
  - completed during locked hours known overlap minutes
- Define the conservative fallback when a completion has a timestamp but no
  actual interval; do not fabricate minutes.
- Apply the same completion accounting to surprise tasks.
- Capture the push count present at completion so average pushes before
  completion can be derived at project/report level later.
- Preserve skipped-during-burnout and completed-after-shield fields as dormant
  schema-compatible counters without implementing their V2 workflows.
- Add boundary tests for exact locked start/end, multiple locked occurrences,
  partially overlapping work, late-by-zero, and idempotent retries.

Rules:

- Statistics updates and task transition/activity persistence must be one atomic
  application operation in Block 14.
- Count/minute semantics must be documented separately when exact actual duration
  is unavailable.
- Never increment a counter by replaying a read model or rebuilding Today state.
- Do not infer completion time from `updatedAt` for migrated records unless a
  migration rule explicitly labels it as an approximation.
- Statistics remain quiet backend metadata.

Acceptance criteria:

- Every implemented V1 counter has a single authoritative update path.
- Duplicate commands cannot double-increment statistics.
- Late and locked-hour calculations are deterministic and boundary-tested.
- Surprise completions participate in the same accounting policy.
- The task-statistics document contract can represent all resulting values.

Verification on 2026-06-25:

- `dart format lib test`: passed, 0 files changed
- `dart analyze`: passed, no issues found
- `dart test`: passed, 218 tests
- `git diff --check`: passed

BREAKPOINT: Stop here. Confirm `high` mode before implementing child-task
orchestration.

## Chunk 13.3 — Child-task break-up and completion orchestration

Recommended Codex level: high

Status: Complete on 2026-06-25.

Tasks:

- Add a pure domain command/result for breaking one parent into an ordered set of
  direct child tasks.
- Validate non-empty child titles, positive optional durations, unique IDs, and
  direct ownership.
- Reject self-parenting and parent/child cycles; keep V1 ownership direct rather
  than implementing a dependency graph.
- Preserve entry order when child priorities are equal or not explicitly set.
- Return all task/activity/stat mutations needed for one atomic application
  transaction.
- Support completing the parent from the parent or any child and force-complete
  remaining direct children exactly once.
- Auto-complete the parent when the last incomplete direct child completes.
- Record lightweight parent/child completion-pattern aggregates or activity
  metadata required by the human specification.
- Add tests for empty sets, duplicate IDs, partial completion, last-child
  completion, force completion, retries, and already-terminal children.

Rules:

- Do not add arbitrary dependency graphs or nested project management.
- Child tasks remain independently schedulable.
- Parent completion propagation must not erase child completion times already
  recorded.
- Forced completion must use one operation context and deterministic timestamp.
- Persistence/transaction wiring is implemented in Block 14/15.

Acceptance criteria:

- Break-up produces deterministic ordered children owned by the parent.
- Last-child completion completes the parent once.
- Parent/child force completion is idempotent and preserves prior child facts.
- Direct-child/cycle constraints are tested.
- Result objects contain enough mutation data for atomic persistence.

Verification on 2026-06-25:

- `dart format lib test`: passed, 0 files changed after final format
- `dart analyze`: passed, no issues found
- `dart test`: passed, 225 tests
- `git diff --check`: passed

BREAKPOINT: Stop here. Confirm `extra high` mode before adding learned project
statistics and suggestions.

## Chunk 13.4 — Project usage statistics and learned-default suggestions

Recommended Codex level: extra high

Status: Complete on 2026-06-25.

Tasks:

- Add a persistence-friendly `ProjectStatistics` model for V1 observations,
  including completion count, known duration samples, completion-time buckets,
  push totals, completions-after-push totals, and reward/difficulty distributions.
- Update project aggregates from canonical task activities/completions exactly
  once.
- Expose derived values such as average push count before completion and a usual
  completion-time bucket without storing lossy floating-point state where avoidable.
- Add a deterministic suggestion service for duration, completion-time window,
  reward, difficulty, and reminder behavior where the available observations are
  meaningful.
- Require a documented minimum sample threshold and expose sample size/confidence
  with every learned suggestion.
- Keep configured project defaults authoritative; suggestions are optional and
  never silently written back as configuration.
- Add tests for insufficient samples, ties, outliers, stable recomputation, and
  configured-default precedence.

Rules:

- Do not add machine learning, remote analytics, or opaque scoring.
- Do not infer sensitive capacity/health conclusions.
- Use explicit deterministic aggregation that can be migrated and reproduced.
- A project with no history must still resolve neutral configured/fallback
  defaults.
- Project statistics are not a V1 reports screen.

Acceptance criteria:

- Project aggregates update exactly once from activities.
- Learned suggestions include provenance, sample size, and confidence/strength.
- Configured defaults are never overwritten automatically.
- Average pushes before completion and usual completion time are derivable.
- Mapping requirements for Block 15 are documented and tested in memory.

Verification on 2026-06-25:

- `dart format lib test`: passed, 0 files changed after final format
- `dart analyze`: passed, no issues found
- `dart test`: passed, 233 tests
- `git diff --check`: passed

BREAKPOINT: Stop here. Confirm `high` mode before implementing reminder-policy
resolution.

## Chunk 13.5 — Effective reminder and protected-rest policy

Recommended Codex level: high

Status: Complete on 2026-06-25.

Tasks:

- Add an optional task-level reminder-profile override.
- Implement an effective-profile resolver using task override, project configured
  default, and documented application fallback in that order.
- Add a UI/platform-independent reminder directive model that can say deliver,
  suppress, defer, or require explicit acknowledgement, with stable reason codes.
- Suppress normal flexible-task reminder directives while a protected Free Slot
  is active.
- Allow critical and inflexible reminder directives to interrupt a Free Slot
  according to the effective profile and required-task policy.
- Ensure `silent` produces no normal reminder directive.
- Expose enough structured data for a later platform notification scheduler
  without scheduling notifications inside the core.
- Add tests across task types, all four reminder profiles, task override,
  project fallback, Free Slot protection, and exact boundary times.

Rules:

- Do not implement OS notifications, background execution, escalation timers,
  accounts, or sync in this chunk.
- Reminder policy must not move tasks.
- Do not let a project suggestion silently replace the configured reminder
  profile.
- Use calm presentation codes; UI copy is outside the domain contract.
- Locked blocks remain hidden and are not normal reminder targets.

Acceptance criteria:

- Effective reminder resolution is deterministic and fully tested.
- Flexible reminders are suppressed during protected Free Slots.
- Required reminders may pass the protection boundary only through explicit
  typed policy.
- Silent reminders produce no delivery directive.
- The core remains Flutter/platform independent.

Verification on 2026-06-25:

- `dart format lib test`: passed, 0 files changed after final format
- `dart analyze`: passed, no issues found
- `dart test`: passed, 243 tests
- `git diff --check`: passed

Commit suggestion:

```text
feat(domain): centralize lifecycle statistics and reminder policy
```
