antidrift/docs/superpowers/specs/2026-05-25-commitment-os-design.md

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:

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.

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.

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.

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

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.

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:

Without an active valid commitment, the machine cannot silently enter unconstrained use.

Testing Strategy

Testing should happen at three levels.

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.