# 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 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 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: ```text feat(domain): centralize lifecycle statistics and reminder policy ```