focus-flow/Codex Documentation/Current Software Plan/V1_BLOCK_13_Lifecycle_Statistics_Project_Reminders.md

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

Status: In progress

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

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.

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

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.

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

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.

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

Chunk 13.5 — Effective reminder and protected-rest policy

Recommended Codex level: high

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.

Commit suggestion:

feat(domain): centralize lifecycle statistics and reminder policy