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.