AGENTS.md

1# src/features/boulder-state/ — Active Work Plan Tracker
2 
3**Generated:** 2026-07-17 / 7d664b96b
4 
5## OVERVIEW
6 
710 files (~1k LOC excl. tests). Tracks Sisyphus's "boulder" — the active work plan being rolled across sessions, worktrees, and subagent task delegations. Named after the Sisyphus myth: the boulder must keep rolling until the plan is complete.
8 
9Inspected interactively via `bunx oh-my-opencode boulder` (see [`src/cli/boulder/`](../../cli/boulder)).
10 
11## SCHEMA (v2)
12 
13```typescript
14interface BoulderState {
15  schema_version?: 2
16  active_work_id?: string
17  works?: Record<string, BoulderWorkState>
18  active_plan: string                            // absolute path to active .md plan
19  started_at: string                             // ISO timestamp
20  ended_at?: string
21  elapsed_ms?: number
22  status?: "active" | "completed" | "paused" | "abandoned"
23  session_ids: string[]                          // every session that has rolled the boulder
24  session_origins?: Record<string, "direct" | "appended">
25  plan_name: string                              // filename of active_plan
26  agent?: string                                 // resume agent (atlas | sisyphus | ...)
27  worktree_path?: string                         // git worktree root
28  task_sessions?: Record<string, TaskSessionState>  // reusable subagent sessions per top-level task
29}
30```
31 
32## FILES
33 
34| File | Purpose |
35|------|---------|
36| `types.ts` | `BoulderState`, `BoulderWorkState`, `TaskSessionState`, status enums |
37| `storage.ts` | Atomic CRUD on `.omo/boulder.json`. Writes via temp file + rename; file lock per work_id |
38| `constants.ts` | Path resolution + schema version constant |
39| `top-level-task.ts` | Helpers to identify the current top-level plan task and resolve its reusable subagent session |
40| `format-duration.ts` | `formatDurationHuman(ms)` — "1h 23m 5s" formatting for boulder duration |
41| `index.ts` | Barrel exports |
42 
43## LIFECYCLE
44 
45```
46session.startWork(plan)
47  → BoulderState created with active_plan, started_at, plan_name
48  → atlas-hook reads BoulderState + `task_sessions` on session.idle (boulder continuation + subagent resume)
49session.idle (incomplete plan)
50  → todoContinuationEnforcer + atlasHook inspect state
51  → Inject CONTINUATION_PROMPT or BOULDER_COMPLETE_PROMPT
52session.completed
53  → BoulderState status="completed", ended_at, elapsed_ms recorded
54```
55 
56## INTEGRATION POINTS
57 
58| Where | What |
59|-------|------|
60| [`src/cli/boulder/`](../../cli/boulder) | CLI inspector formats this state |
61| [`src/hooks/atlas/`](../../hooks/atlas) | Reads work state + `task_sessions` (subagent resume); drives boulder-complete and parallel-delegation prompts |
62| [`src/hooks/start-work/`](../../hooks/start-work) | Creates the BoulderState on `/start-work` invocation |
63| [`src/hooks/todo-continuation-enforcer/`](../../hooks/todo-continuation-enforcer) | Session-idle continuation when boulder incomplete |
64 
65## STORAGE
66 
67```
68<worktree-root>/.omo/boulder.json   # gitignored; one file per worktree
69```
70 
71Atomic writes: temp file → fsync (where supported) → rename. File lock prevents concurrent corruption. Schema migrations between versions handled inline in `storage.ts`.
72 
73## NOTES
74 
75- **task_sessions reuse**: same subagent session is reused across iterations for the same top-level task to preserve context.
76- **Multi-work**: `works` map allows tracking multiple concurrent plans; `active_work_id` selects the current one.
77- **Worktree-scoped**: state lives in the worktree, not user-global; ensures parallel work plans across worktrees stay isolated.
78