Add commitment OS design spec
This commit is contained in:
@@ -0,0 +1,229 @@
|
||||
# Commitment OS Design
|
||||
|
||||
Date: 2026-05-25
|
||||
|
||||
## Purpose
|
||||
|
||||
AntiDrift should evolve from a session timer and window-rating tool into a commitment operating system: a personal agency layer that makes computer use explicit, constrained, observable, and resistant to tampering.
|
||||
|
||||
The system should address distraction as unconscious context switching, not only as access to bad websites. The guiding rule is:
|
||||
|
||||
```text
|
||||
No unchosen transitions.
|
||||
```
|
||||
|
||||
The computer should not silently enter unconstrained use. It should be in an active commitment, a deliberate transition, planning/review, locked state, or delayed administrative override.
|
||||
|
||||
## Architecture
|
||||
|
||||
The system has five layers that share a common commitment model.
|
||||
|
||||
1. Orientation: projects, responsibilities, values, tasks, next actions, energy constraints.
|
||||
2. Commitment: a concrete next action, success condition, allowed context, timebox, and transition policy.
|
||||
3. Live work mode: desktop, browser, terminal, files, ActivityWatch, window tracking, and future presence sensors.
|
||||
4. Containment: a privileged guardian that enforces the selected commitment across the live environment.
|
||||
5. Reflection: session outcomes, drift events, transition reasons, rule adjustments, and planner updates.
|
||||
|
||||
The commitment model sits between planning and enforcement. Planner integration can later create commitments from tasks. Enforcement can already operate on policy snapshots derived from commitments without understanding the entire planner.
|
||||
|
||||
## Domain Model
|
||||
|
||||
The core domain object is `Commitment`.
|
||||
|
||||
```text
|
||||
Commitment
|
||||
id
|
||||
created_at
|
||||
source: manual | planner | recurring | recovery
|
||||
project_id: optional initially, planner-backed later
|
||||
next_action: concrete executable action
|
||||
success_condition: what counts as done or meaningfully advanced
|
||||
allowed_context:
|
||||
apps
|
||||
domains
|
||||
files/repos
|
||||
commands/processes
|
||||
timebox
|
||||
transition_policy:
|
||||
allowed breaks
|
||||
pause reasons
|
||||
max break duration
|
||||
return ritual
|
||||
enforcement_level: observe | warn | block | locked
|
||||
state: draft | active | paused | completed | abandoned | violated
|
||||
```
|
||||
|
||||
This contract is used by all layers:
|
||||
|
||||
- The session UI creates or selects a commitment.
|
||||
- The guardian enforces the active commitment.
|
||||
- ActivityWatch and window tracking evaluate behavior against the commitment.
|
||||
- The planner later generates commitments from project tasks.
|
||||
- Reflection writes outcomes back into history and eventually into the planner.
|
||||
|
||||
## Runtime States
|
||||
|
||||
The runtime state machine is intentionally small.
|
||||
|
||||
```text
|
||||
Locked
|
||||
No valid active commitment. Distracting/default computer use is blocked.
|
||||
|
||||
Planning
|
||||
The user can inspect tasks/projects and create or choose a commitment.
|
||||
|
||||
Active
|
||||
A commitment is running. Allowed context is available; disallowed context is blocked or interrupted.
|
||||
|
||||
Transition
|
||||
The user is intentionally changing state: bathroom, water, reset, task switch, or end session.
|
||||
Requires reason, expected duration, and return target.
|
||||
|
||||
Review
|
||||
Session ended. The user rates relevance, marks outcome, and records drift/avoidance patterns.
|
||||
|
||||
Admin Override
|
||||
Privileged changes only. Requires delayed admin path and leaves audit evidence.
|
||||
```
|
||||
|
||||
The system should record all state changes. Leaving the desk, quitting monitors, changing rules, opening unrelated websites, or switching tasks should become explicit transitions or violations.
|
||||
|
||||
## Enforcement Boundary
|
||||
|
||||
The system has two main runtime processes.
|
||||
|
||||
```text
|
||||
User agent
|
||||
TUI/UI, session flow, window/activity collection, prompts, local status.
|
||||
|
||||
Privileged guardian
|
||||
systemd-managed service, watchdog, block rules, policy application,
|
||||
tamper detection, restart behavior, admin-only config.
|
||||
```
|
||||
|
||||
The user agent owns interaction and local evidence collection. The privileged guardian is narrow and boring: it applies policy snapshots, keeps required monitors alive, records tamper evidence, and refuses easy shutdown.
|
||||
|
||||
The Linux machine can use the existing delayed admin-account mechanism as part of the hardening story. Configuration changes and service shutdown should require delayed privileged access.
|
||||
|
||||
## Data Flow
|
||||
|
||||
```text
|
||||
Planner or manual input
|
||||
-> Commitment draft
|
||||
-> Active commitment
|
||||
-> Guardian policy snapshot
|
||||
-> Live evidence stream
|
||||
windows, ActivityWatch, process health, future sensors
|
||||
-> Violations / transitions / completions
|
||||
-> Review
|
||||
-> Event log + history + planner updates
|
||||
```
|
||||
|
||||
The guardian consumes policy snapshots derived from the active commitment. A snapshot answers:
|
||||
|
||||
- What runtime state is active?
|
||||
- What apps, domains, processes, files, or commands are allowed?
|
||||
- Which monitoring processes must be running?
|
||||
- What should happen on violation?
|
||||
- Which changes require admin override?
|
||||
|
||||
This keeps enforcement independent from planner internals.
|
||||
|
||||
## Staged Implementation
|
||||
|
||||
### Stage 1: Commitment Kernel
|
||||
|
||||
Build the shared commitment model and local runtime loop.
|
||||
|
||||
- Commitment schema.
|
||||
- Runtime state machine.
|
||||
- Local event log.
|
||||
- Session UI using commitment fields.
|
||||
- Activity/window evidence linked to `commitment_id`.
|
||||
- Review flow.
|
||||
|
||||
The current AntiDrift app can become the first client of this model.
|
||||
|
||||
### Stage 2: Linux Hardening
|
||||
|
||||
Move enforcement into system-level mechanisms.
|
||||
|
||||
- systemd user service for the agent.
|
||||
- Privileged guardian service.
|
||||
- Watchdog checks for AntiDrift and ActivityWatch.
|
||||
- Tamper-evident event log.
|
||||
- Admin-only policy config.
|
||||
- Delayed override path.
|
||||
- Basic network, browser, and app blocking.
|
||||
|
||||
### Stage 3: Planner Integration
|
||||
|
||||
Replace ad hoc intentions with a live planning layer.
|
||||
|
||||
- Projects.
|
||||
- Tasks.
|
||||
- Next actions.
|
||||
- Recurring responsibilities.
|
||||
- Task selection during Planning state.
|
||||
- Session outcomes written back to tasks.
|
||||
- Review suggestions based on drift history.
|
||||
|
||||
### Stage 4: Embodied And Presence Sensing
|
||||
|
||||
Add physical-context evidence after the core system is useful.
|
||||
|
||||
- Desk presence detection.
|
||||
- Posture warnings.
|
||||
- Phone pickup or away detection, if feasible.
|
||||
- Transition prompts when leaving unexpectedly.
|
||||
|
||||
Presence sensing should be another evidence source that emits events such as `desk_absence_started`. It should not be a core dependency.
|
||||
|
||||
## Failure Handling
|
||||
|
||||
The system should assume failures and tampering attempts are normal.
|
||||
|
||||
```text
|
||||
Agent crash
|
||||
Guardian restarts it and records the crash.
|
||||
|
||||
ActivityWatch stopped
|
||||
Guardian restarts it; repeated failure escalates to Locked.
|
||||
|
||||
Policy apply failure
|
||||
System refuses Active state and stays Locked or Planning.
|
||||
|
||||
Unknown app/window/domain
|
||||
observe/warn: record and prompt
|
||||
block/locked: interrupt or minimize
|
||||
|
||||
Unexpected desk absence later
|
||||
Emit transition-needed event; if not resolved, mark violation.
|
||||
|
||||
Admin override
|
||||
Allowed only through delayed admin path and always recorded.
|
||||
```
|
||||
|
||||
The primary invariant is:
|
||||
|
||||
```text
|
||||
Without an active valid commitment, the machine cannot silently enter unconstrained use.
|
||||
```
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
Testing should happen at three levels.
|
||||
|
||||
```text
|
||||
Unit tests
|
||||
commitment validation, state transitions, policy snapshot generation, scoring.
|
||||
|
||||
Integration tests
|
||||
user agent writes state; guardian reads policy; simulated ActivityWatch/window events produce expected violations.
|
||||
|
||||
Manual system tests
|
||||
quit agent, quit ActivityWatch, open blocked site, change config, trigger delayed override,
|
||||
verify logs and recovery behavior.
|
||||
```
|
||||
|
||||
The first implementation plan should focus on Stage 1 while preserving the process boundary and data contracts needed for Stage 2 and Stage 3.
|
||||
Reference in New Issue
Block a user