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 casual tampering.

The system addresses 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 one of these explicit modes:

• active commitment;
• deliberate transition;
• constrained planning;
• review;
• locked state;
• delayed administrative override.

Tamper resistance is a friction gradient against the user's impulsive self. It is not a perfect security boundary. The goal is to defeat impulsive and casual bypasses, delay deliberate bypasses, and make drift visible.

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 evidence sources.
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 operates on policy snapshots derived from commitments without understanding planner internals.

Threat Model And Scope

The adversary is the same person in a less reflective state. The system should be honest about what local software can and cannot enforce.

Tier	Bypass effort	Examples	Realistic goal
0: impulse	less than 1 second	Alt-tab, open browser, type URL, leave desk without choosing transition	Defeat with blocking, prompts, overlays, and explicit transitions
1: casual	seconds	Kill process, stop user service, close app, quit ActivityWatch	Defeat with watchdogs, privilege separation, and restart behavior
2: determined	minutes	Use sudo, edit config, disable systemd units, reboot, manipulate clock	Delay and audit through delayed admin path and break-glass flow
3: premeditated	unconstrained	Boot live USB, GRUB recovery, second device, phone, hardware removal	Out of scope for local software

In-scope bypasses:

• opening disallowed domains or apps;
• quitting AntiDrift or ActivityWatch;
• stopping user-level services;
• entering unconstrained planning;
• changing rules without delayed admin access;
• crash-looping the user agent;
• malformed policy snapshots;
• clock manipulation attempts visible to the running system;
• unmonitored desk absence after future presence sensing exists.

Out-of-scope or explicitly limited:

• second phones, tablets, or other computers;
• booting from external media or recovery shell;
• physical tampering;
• fully premeditated bypasses with unlimited time;
• coercive monitoring of another person.

Known edge cases to address or scope per implementation stage:

• switching TTYs or desktop sessions;
• Wayland compositor limitations;
• VMs and nested display servers;
• SSH into the same machine;
• browser profiles and extensions;
• Flatpak/Snap application identity;
• multi-user machines;
• multiple monitors, virtual desktops, and tiling window managers;
• direct modification of ActivityWatch data.

Stage 1 does not need to solve every edge case, but it must not pretend they are solved.

Linux Target Environment

The first target is the user's Linux workstation.

Stage 1 should support the current X11-style active-window model already used by AntiDrift through xdotool, plus ActivityWatch evidence when available. If the session is Wayland and active window metadata cannot be collected reliably, the system must surface that as a degraded evidence mode rather than silently reporting false confidence.

Stage 2 should choose concrete Linux enforcement mechanisms per target environment:

• systemd system service for the privileged guardian;
• systemd user service or normal user process for the agent;
• nftables or DNS-level controls for domain blocking;
• window-class interruption where active window details are available;
• ActivityWatch watchdog where ActivityWatch is installed and expected.

Wayland support should be compositor-specific. GNOME Wayland, KDE Wayland, Sway, and Hyprland may need separate adapters. Unknown or unsupported environments should fail into a conservative mode: planning/review may work, but enforcement claims are limited.

Domain Model

The first-pass Commitment concept should be split into three related records.

Commitment

User-facing intent and planning artifact.

Commitment
  id
  created_at
  source: manual | planner | recurring | recovery | template
  project_id: optional initially, planner-backed later
  template_id: optional
  next_action: concrete executable action
  success_condition: what counts as done or meaningfully advanced
  timebox
  transition_policy_id
  state: draft | active | paused | completed | abandoned | violated

Only one commitment may be active at a time. Task switches go through Transition and either resume the current commitment, abandon it, or create/select a new one.

PolicySnapshot

Versioned enforcement contract consumed by the guardian.

PolicySnapshot
  id
  commitment_id
  schema_version
  created_at
  runtime_state: locked | planning | active | transition | review | admin_override
  enforcement_level: observe | warn | block | locked
  allowed_context
  required_monitors
  violation_actions
  expires_at
  generated_by_agent_version

The guardian consumes PolicySnapshot, not planner internals.

SessionRecord And EventLog

Append-only history of what happened.

SessionRecord
  id
  commitment_id
  started_at
  ended_at
  outcome: completed | partial | abandoned | violated
  review_rating
  review_notes

EventLog
  sequence
  timestamp
  event_type
  commitment_id
  runtime_state
  payload
  previous_hash
  hash

The event log is the source for review, audit, and later planner writeback.

Allowed Context Semantics

Allowed context should be explicit and conservative. Stage 1 may only observe or warn, but the matching rules should be defined early so Stage 2 can enforce the same contract.

allowed_context:
  window_classes:
    match: exact_lowercase
    values:
      - code
      - alacritty
  window_titles:
    match: substring
    values:
      - antidrift
  domains:
    match: exact_or_subdomain
    values:
      - github.com
      - docs.python.org
  repos:
    match: canonical_path_prefix
    values:
      - ~/dev/antidrift
  commands:
    match: executable_basename
    values:
      - cargo
      - git
      - rg

Rules:

• Domains include subdomains unless explicitly marked exact-only.
• Full URLs should not be stored by default; store domain and coarse path only when needed.
• Window classes are preferred over titles because titles can contain private data and change frequently.
• Unknown windows are handled by enforcement_level: record in observe, prompt in warn, interrupt in block, and force Locked on repeated or severe violations in locked.
• Terminals are hard to classify. Stage 1 may treat terminal windows as allowed based on window class and record command evidence later only when a shell integration exists.
• Child process handling is deferred until command/process enforcement is designed. Stage 2 should not claim process-level policy without cgroups, namespaces, AppArmor, seccomp, or equivalent mechanisms.
• Commitments may use per-resource actions. Example: block social domains, warn on unfamiliar apps, observe unknown terminal commands.

Commitment templates and project defaults should reduce manual allowlist construction:

• deep coding;
• writing;
• admin;
• research;
• rest;
• project-specific default repos, apps, and documentation domains.

Time-limited context expansion should be allowed when work legitimately discovers a new need. Expansion must be explicit, audited, and bounded, such as "allow docs.rs for 20 minutes for this commitment."

Runtime State Machine

Runtime state controls what the machine is allowed to do now.

Locked
  No valid active commitment. Distracting/default computer use is blocked.

Planning
  Constrained UI for inspecting tasks/projects and creating or choosing a commitment.

Active
  A commitment is running. Allowed context is available; disallowed context is blocked or interrupted.

Transition
  Intentional state change: bodily break, reset, task switch, or session end.
  Requires reason, expected duration, and return target.

Review
  Session ended. The user rates relevance, marks outcome, and records drift/avoidance patterns.

Admin Override
  Privileged change path. Requires delayed admin access and leaves audit evidence.

Legal transitions:

From	To	Guard	Side effects
Locked	Planning	Planning UI requested	Apply planning policy, start planning timer
Planning	Active	Valid commitment and policy snapshot accepted by guardian	Create session record, apply active policy
Planning	Locked	Cancel, timeout, invalid policy, or idle	Apply locked policy
Active	Transition	Reason, expected duration, and return target provided	Record transition start, apply transition policy
Active	Review	Commitment completed, abandoned, or timebox expired	Stop active policy, collect evidence summary
Active	Locked	Severe violation, policy failure, or monitor failure	Record violation, apply locked policy
Transition	Active	Return before timeout to same commitment	Record return, reapply active policy
Transition	Planning	Task switch requested	Mark current commitment paused/abandoned as chosen, apply planning policy
Transition	Review	End session requested	Collect review data
Transition	Locked	Timeout exceeded or transition policy failure	Record violation, apply locked policy
Review	Planning	Continue working	Store review, apply planning policy
Review	Locked	End work period	Store review, apply locked policy
Any	Admin Override	Delayed admin path completed	Record override, apply requested privileged change
Admin Override	Previous/new state	Override ends	Record result, apply selected policy

Planning must never become unconstrained browsing. It has its own policy:

• only the planning UI, local task data, and approved references are available;
• planning is time-limited;
• evidence collection remains active;
• opening arbitrary browser tabs from Planning is a violation unless explicitly allowed.

Suspend/hibernate and reboot should resume into Locked unless a valid policy can be restored and verified. A violated commitment may be resumed only through Review or Planning; resumption should create a visible event.

Commitment Lifecycle

Commitment state is distinct from runtime state.

From	To	Guard	Notes
draft	active	Runtime enters Active with accepted policy	Only one active commitment at a time
active	paused	Runtime enters Transition with return target	Paused does not imply unconstrained use
paused	active	User returns before transition timeout	Same commitment resumes
active	completed	Success condition met or user completes in review	Requires review
active	abandoned	User chooses task switch/end without completion	Requires reason
active	violated	Severe or unresolved violation	May force runtime Locked
paused	abandoned	Transition becomes task switch/end	Requires reason
violated	active	Explicit recovery flow	Audited; not automatic
violated	abandoned	Review confirms abandonment	Stored in history

Guardian IPC Contract

The user agent and guardian communicate through a narrow local API.

Recommended transport: root-owned Unix domain socket with a small JSON-lines protocol. D-Bus can be reconsidered later if desktop integration requires it, but the first design should avoid unnecessary framework surface.

Authentication and integrity:

• The socket path is owned by root and writable only by the expected user/group.
• The guardian checks peer credentials with SO_PEERCRED.
• Messages include schema_version, monotonic sequence, and request id.
• The guardian rejects malformed, unknown-version, stale, or unauthenticated messages.
• Policy changes are logged before and after application.

Minimal API:

ApplyPolicy(PolicySnapshot) -> Result
ReportEvent(Event) -> Ack
GetStatus() -> SystemState
RequestOverride(OverrideRequest) -> OverrideResult

Failure behavior:

• If the agent disconnects while Active, the guardian keeps the last valid policy for a short grace period, then moves to Locked.
• If the agent sends malformed policy, the guardian rejects it and keeps the previous valid policy; repeated malformed policy escalates to Locked.
• If IPC is unavailable, the agent should show degraded state and the system should not claim enforcement.
• If guardian and agent schema versions are incompatible, the system should enter Locked with an actionable error and break-glass instructions.

Enforcement Mechanism Matrix

Stage 2 enforcement should be explicit about feasibility.

Resource	Stage 1	Stage 2 candidate	Notes
Domain	observe from ActivityWatch/browser data if available	nftables or DNS-level blocking	Prefer domains over full URLs for privacy
App/window	active-window tracking, minimize or overlay	window-class interruption, minimize, SIGSTOP only where safe	Depends on X11/Wayland adapter
Agent health	local process check	systemd restart and guardian watchdog	Casual process killing should fail
ActivityWatch health	observe availability	guardian restart and escalation after repeated failure	Direct DB tampering only audited if detectable
Config changes	local file checks	root-owned config, delayed admin required	Config writes must be audited
Commands/processes	mostly out of scope	future shell integration, cgroups, AppArmor, seccomp, namespaces	Do not overclaim early
Files/repos	local path metadata	future filesystem policy only if needed	Path allowlists are mostly planning/evidence initially
Presence	out of scope	future opt-in sensor events	Requires separate ethics/design review

Stage 1 should include Tier 0 friction even without privileged blocking:

• full-screen or high-priority overlay on violation where feasible;
• dismissal requires entering a reason;
• explicit transition prompts;
• local event logging tied to the active commitment.

Delayed Admin And Break-Glass Recovery

The delayed admin mechanism is load-bearing and must be concrete before Stage 2 hardening.

Initial assumption:

• daily work happens in a non-admin user account;
• admin access exists in a separate admin account or equivalent path;
• admin access already has a delay, currently about 10 minutes, and can be lengthened;
• privileged enforcement changes require that delayed path.

Actions requiring delayed admin:

• disabling guardian service;
• changing locked policy files;
• changing blocklists or allowlists outside explicit time-limited context expansion;
• uninstalling enforcement;
• disabling watchdog behavior;
• emergency break-glass.

Override requests should be logged at request time and completion time:

OverrideRequest
  id
  requested_at
  requester_user
  reason
  requested_action
  earliest_allowed_at
  completed_at
  result

Pre-scheduled instant overrides weaken the system. The guardian should reject override tokens or sentinel files created before the current request window unless they are part of the audited delayed-admin protocol.

Break-glass recovery must be independent of the normal agent UI. Example: a privileged command or root-owned sentinel file disables enforcement for 10 minutes after delayed admin access. It must:

• be simple enough to trust under failure;
• be audited;
• have automatic expiry;
• restore normal policy after expiry unless explicitly uninstalled;
• not depend on the user agent being healthy.

Event Log, Tamper Evidence, And Retention

Events should be append-only and bounded.

Recommended initial format: JSON lines with hash chaining.

event_hash = hash(schema_version, sequence, timestamp, event_type, payload, previous_hash)

The log should include:

• policy applications;
• state transitions;
• violations;
• process/monitor failures;
• override requests and completions;
• review outcomes.

Retention and storage:

• rotate logs by size and time;
• enforce max disk usage;
• define behavior when disk is full;
• support export and deletion through delayed admin if enforcement logs are involved;
• include schema version and migration path.

If logging fails:

• non-critical review notes may be skipped with visible warning;
• enforcement/audit events should fail conservative, usually Locked, unless doing so would create an unsafe machine lockout;
• break-glass must still work even when normal logging is impaired, with best-effort emergency log.

Privacy, Ethics, And Data Retention

This is voluntary self-use software. It must not become bossware, parental control software, or coercive monitoring.

Principles:

• local-first storage by default;
• no network transmission unless explicitly configured;
• minimum necessary observation;
• prefer domain over full URL;
• prefer window class over title where possible;
• treat window titles as sensitive because they can contain private messages, documents, or secrets;
• encrypt logs/history at rest if feasible, especially once planner and presence data exist;
• provide retention, deletion, and export tools;
• make data collection visible to the user;
• include first-class rest and exploration commitments so legitimate openness and recovery are not treated as failure.

The system should increase agency, not create surveillance anxiety. Presence sensing, camera use, posture detection, and phone pickup detection require a separate opt-in design and ethics review after the core system is useful.

Failure Handling

Failures should have explicit fail-open or fail-closed behavior.

Failure	Default behavior
User agent crash	Guardian restarts agent; if repeated, enter Locked
User agent crash loop	Enter Locked, show recovery instructions
Guardian crash	systemd restarts guardian; until restored, user agent shows enforcement degraded
Guardian crash loop	Fail conservative where possible, but keep break-glass available
ActivityWatch stopped	Guardian restarts it; repeated failure escalates to Locked if ActivityWatch is required
ActivityWatch unavailable	Run degraded if policy does not require it; otherwise refuse Active
ActivityWatch data corrupted	Mark evidence degraded, preserve raw error, continue only if policy allows
Policy apply failure	Refuse Active; stay Planning or move Locked
Malformed policy	Reject, keep previous valid policy, escalate after repeated failures
Disk full/log write failure	Warn; fail conservative for enforcement events; keep break-glass available
System reboot	Start in Locked until state is restored and verified
Suspend/hibernate	On resume, revalidate timebox and policy; otherwise enter Locked
Clock manipulation	Prefer monotonic timers for timeboxes; record wall-clock anomalies
OS updates	Require delayed admin or maintenance commitment
Emergency interruption	Use transition or break-glass depending on severity
Schema migration failure	Enter Locked with recovery instructions

The primary invariant is:

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

Locked, Planning, Transition, And Review UX

Locked state should show a small, reliable UI:

• current status;
• reason for lock;
• option to enter constrained Planning;
• option to review last session if pending;
• break-glass instructions that require delayed admin.

Planning should be useful but constrained:

• local project/task list;
• commitment templates;
• recent commitments;
• allowed local notes or references;
• time limit;
• no arbitrary browsing unless a planning policy explicitly allows it.

Transition should force consciousness into state changes:

• reason;
• expected duration;
• return target;
• optional note;
• timeout behavior.

Review should be difficult to skip:

• mark outcome;
• rate relevance;
• record drift or transition failures;
• update commitment/task state;
• generate next suggested commitment where useful.

Staged Implementation

Stage 1a: Commitment Kernel

• Commitment schema.
• PolicySnapshot schema without privileged enforcement.
• Runtime and commitment state machines.
• Append-only local event log.
• Unit tests for legal and illegal transitions.

Stage 1b: Session UI And Evidence

• Session UI using commitment fields.
• Review flow.
• Activity/window evidence linked to commitment_id.
• Degraded evidence reporting when ActivityWatch or window metadata is unavailable.

Stage 1c: Tier 0 Friction

• Full-screen or high-priority overlay on violation where feasible.
• Dismissal requires deliberate reason entry.
• Explicit transition prompts.
• Unknown-window/domain behavior based on enforcement level.

Stage 2a: Guardian Skeleton

• systemd system service for guardian.
• systemd user service or launcher for agent.
• Watchdog restart behavior for user agent and ActivityWatch.
• Minimal status reporting.

Stage 2b: IPC And Policy Delivery

• Root-owned Unix domain socket.
• JSON-lines protocol.
• ApplyPolicy, ReportEvent, GetStatus, RequestOverride.
• Schema versioning and malformed-message handling.

Stage 2c: Domain Blocking

• nftables or DNS-level policy application.
• Domain matching semantics.
• Policy rollback on failure.

Stage 2d: App/Window Interruption

• X11 adapter first if current environment is X11.
• Compositor-specific Wayland adapters only after verification.
• Minimize, overlay, or interrupt based on policy.

Stage 2e: Tamper-Evident Logs And Retention

• Hash-chained events.
• Rotation and max disk usage.
• Export/delete path.
• Log failure handling.

Stage 2f: Delayed Admin And Config Lockdown

• Root-owned policy/config.
• Delayed override protocol.
• Break-glass command.
• Uninstall/rollback tooling.

Stage 3a: Project And Task Model

• Projects.
• Tasks.
• Next actions.
• Recurring responsibilities.

Stage 3b: Commitment Templates From Tasks

• Project defaults.
• Work-mode templates.
• Task selection during Planning state.
• Time-limited context expansion.

Stage 3c: Outcome Writeback

• Session outcomes written back to tasks.
• Review suggestions based on drift history.
• Next commitment suggestions.

Future Direction: Embodied And Presence Sensing

Presence sensing is not part of the core roadmap. It may be considered later only if:

• the core system has proven useful;
• the user explicitly opts in;
• data minimization is defined;
• psychological safety is reviewed;
• retention and deletion behavior are explicit.

Potential future events:

• desk_absence_started;
• desk_absence_resolved;
• posture_warning;
• phone_pickup_detected.

These should be evidence events, not core dependencies.

Uninstall And Rollback

The system must have a clean removal path.

Uninstall should:

• disable guardian service;
• disable user agent service;
• remove nftables or DNS rules;
• remove root-owned policy/config files after delayed admin confirmation;
• export or delete logs;
• restore normal admin behavior if it was modified for AntiDrift;
• verify that no blocking policy remains active.

Rollback should support returning from a failed upgrade to the previous known-good policy and guardian version.

Testing Strategy

Testing must include bypass resistance, not only happy paths.

Unit tests:

• commitment validation;
• legal and illegal runtime transitions;
• legal and illegal commitment transitions;
• PolicySnapshot generation;
• allowed context matching;
• event hash chaining.

Property tests:

• no unconstrained use without valid active commitment;
• illegal transitions do not mutate state;
• expired policy snapshots are rejected.

Integration tests:

• user agent writes state;
• guardian reads policy;
• simulated window/ActivityWatch events produce expected violations;
• malformed policy is rejected;
• agent disconnect triggers grace period then Locked;
• timebox expiry moves to Review or Locked as configured.

Adversarial VM/manual tests:

• kill agent;
• stop ActivityWatch;
• attempt blocked domain;
• malformed policy;
• guardian restart;
• guardian crash loop;
• timebox expiry;
• config change attempt;
• reboot during active commitment;
• suspend/resume during active commitment;
• disk full or log write failure.

Soak and upgrade tests:

• 24-48 hour run with normal use;
• log rotation;
• schema migration;
• downgrade/rollback;
• IPC fuzz tests.

The first implementation plan should target Stage 1a through Stage 1c while preserving the process boundary and data contracts needed for Stage 2 and planner integration.