break-it-down/SYSTEMSPEC_v0.2.0.md

# Break It Down (BIT)

# SYSTEM SPECIFICATION

## Version: v0.2.0

## Feature Theme: Campaign Mode + Entropy Engine + Project Wizard

------------------------------------------------------------------------

# 1. Overview

v0.2.0 introduces **Campaign Mode**, an operations layer on top of
Break-It-Down's planning engine.

BIT remains the HQ planning system (tree + kanban). Campaign Mode is the
execution layer focused on:

-   Low-friction session starts
-   Visual progress (photo proof)
-   Entropy-based decay for recurring physical spaces
-   Gentle nudges to trigger action
-   A fast project-building Wizard

The goal is to reduce startup friction and help users act without
overthinking.

------------------------------------------------------------------------

# 2. Core Architectural Principles

1.  Existing planning functionality must remain unchanged for standard
    projects.
2.  Campaign functionality activates only when
    `project_mode == "entropy_space"`.
3.  Planning (HQ) and Execution (Campaign) are separate UI routes.
4.  Session start must require no pre-forms.
5.  Entropy simulation must feel like physics, not guilt.

------------------------------------------------------------------------

# 3. New Core Concepts

## 3.1 Project Modes

Add enum to projects:

-   `standard` (default, existing behavior)
-   `entropy_space` (physical space / territory model)

Future modes may include: - `pipeline_chores` - `deep_work`

------------------------------------------------------------------------

## 3.2 Campaign Types

Only meaningful when `project_mode == "entropy_space"`:

-   `finite` --- one-off liberation (garage purge)
-   `background` --- ongoing maintenance (bathroom, kitchen)

------------------------------------------------------------------------

## 3.3 Zones (v1 Implementation)

In `entropy_space` projects:

-   Top-level tasks (`parent_task_id IS NULL`)
-   `is_zone = true`

No separate zones table in v0.2.0.

------------------------------------------------------------------------

## 3.4 Work Sessions

Generic sessions stored in backend. Campaign UI refers to them as
"Strikes".

Session kinds:

-   `strike`
-   `pomodoro` (future)
-   `run` (future)
-   `freeform`

------------------------------------------------------------------------

# 4. Database Schema Changes

## 4.1 Projects Table Additions

    project_mode TEXT NOT NULL DEFAULT 'standard'
    campaign_type TEXT NULL
    campaign_active BOOLEAN NOT NULL DEFAULT 0

    nudge_enabled BOOLEAN NOT NULL DEFAULT 0
    nudge_window_start TEXT NULL
    nudge_window_end TEXT NULL
    nudge_min_interval_minutes INTEGER NULL
    nudge_max_per_day INTEGER NULL

    photo_proof_enabled BOOLEAN NOT NULL DEFAULT 0
    default_session_kind TEXT NOT NULL DEFAULT 'freeform'
    default_session_minutes INTEGER NOT NULL DEFAULT 12

------------------------------------------------------------------------

## 4.2 Tasks Table Additions (Zones Only)

    is_zone BOOLEAN NOT NULL DEFAULT 0

    stability_base INTEGER NULL
    decay_rate_per_day REAL NULL
    last_stability_update_at DATETIME NULL
    last_strike_at DATETIME NULL

    zone_preset TEXT NULL

------------------------------------------------------------------------

## 4.3 New Table: work_sessions

    id INTEGER PRIMARY KEY
    project_id INTEGER NOT NULL
    task_id INTEGER NULL
    kind TEXT NOT NULL
    started_at DATETIME NOT NULL
    ended_at DATETIME NULL
    duration_seconds INTEGER NULL
    note TEXT NULL

------------------------------------------------------------------------

## 4.4 New Table: session_photos

    id INTEGER PRIMARY KEY
    session_id INTEGER NOT NULL
    phase TEXT NOT NULL   -- 'before' or 'after'
    path TEXT NOT NULL
    taken_at DATETIME NOT NULL

Images stored in Docker volume under:

    /data/photos/{project_id}/{session_id}/...

------------------------------------------------------------------------

# 5. Entropy Engine (v1)

## 5.1 Stability Model

Fields used: - stability_base - last_stability_update_at -
decay_rate_per_day

Derived:

    days_elapsed = (now - last_stability_update_at)
    stability_now = max(0, stability_base - decay_rate_per_day * days_elapsed)

------------------------------------------------------------------------

## 5.2 Strike Effect

On strike completion:

Option A (fixed):

    boost = 20

Option B (duration-based):

    boost = clamp(10, 35, round(duration_minutes * 1.5))

Update:

    stability_base = min(100, stability_now + boost)
    last_stability_update_at = now
    last_strike_at = now

------------------------------------------------------------------------

## 5.3 Stability Color Mapping

-   80--100 → green
-   55--79 → yellow
-   30--54 → orange
-   0--29 → red

------------------------------------------------------------------------

# 6. API Additions

## Campaign

    POST /api/projects/{id}/launch_campaign
    GET  /api/projects/{id}/zones

## Sessions

    POST /api/sessions/start
    POST /api/sessions/{id}/stop
    GET  /api/projects/{id}/sessions

## Photos

    POST /api/sessions/{id}/photos
    GET  /api/sessions/{id}/photos

## Wizard

    POST /api/wizard/build_project

------------------------------------------------------------------------

# 7. Frontend Routes

    /projects
    /projects/:id
    /projects/:id/campaign

------------------------------------------------------------------------

# 8. Build Phases

Phase 0: Core campaign + stability\
Phase 1: Photo proof + compare slider\
Phase 2: Nudges\
Phase 3: Hex grid expansion

------------------------------------------------------------------------

# 9. Success Criteria

-   Wizard creates entropy project in \<30 seconds\
-   Strike starts in 1 tap\
-   Stability increases after strike\
-   Stability decreases over time\
-   No regression in standard projects

------------------------------------------------------------------------

**Break It Down v0.2.0**\
Planning in HQ. Liberation on the front lines.