diff --git a/docs/superpowers/specs/2026-05-31-go-focus-os-design.md b/docs/superpowers/specs/2026-05-31-go-focus-os-design.md index 3693135..381af27 100644 --- a/docs/superpowers/specs/2026-05-31-go-focus-os-design.md +++ b/docs/superpowers/specs/2026-05-31-go-focus-os-design.md @@ -51,9 +51,10 @@ valuable. **Deferred for v1:** - The AI **reviewer** role (session-end reflection). The three live roles ship - first. + first; the reviewer returns as **M7 — Reflection**, which closes the loop. - Privileged enforcement (guardian, IPC, nftables, delayed admin) — same Stage 2 - boundary as the original spec. + boundary as the original spec. This is the path toward the **entry gate** + (see "Destination" in the Roadmap) and is deliberately the last milestone. ## Process Model @@ -129,7 +130,7 @@ Each port is a small Go interface with one real adapter (and a fake for tests). | Advisor | `ai.Assistant` (`Coach`/`JudgeDrift`/`Nudge`) | What's the smart call here? | `claude`/`codex` CLI | M2–M3 | | Tasks | `tasks.Provider` | What *should* I be doing? | Amazing Marvin (existing `ampy` + marvin MCP) | deferred (M5) | | Knowledge | `knowledge.Source` | Who am I; what are my priorities? | PKM / files | deferred (M6) | -| Enforcement | `enforce.Guard` | Make drift cost something | window-minimize now (legacy `minimize_other`); nftables/guardian later | deferred (M7) | +| Enforcement / Gate | `enforce.Guard` | Make drift cost something — ultimately, gate the machine on a declared intention | window-minimize (legacy `minimize_other`) → nftables/guardian → entry gate | deferred (M8) | | UI | `web` | Show me; take my input | Gin + browser over SSE | M0, ongoing | Persistence (`store`) is infrastructure shared by the orchestrator, not a port. @@ -196,8 +197,19 @@ machine exposes, but never owns a transition. Each milestone is independently shippable and gets its own spec → plan → build cycle. M0–M4 build the core plus the first two ports (activity, advisor) and the -UI; M5–M7 add the remaining ports, each a small interface + adapter following -the pattern M1 establishes. +UI; M5–M8 add the remaining ports and close the loop, each a small interface + +adapter following the pattern M1 establishes. + +**Destination — the gate-first loop.** The end state is an OS-level focus loop: +the **Guard** checks for a declared intention *before* the machine is usable, +the user commits, works under monitoring, and every cycle ends in +**reflection** before returning to the gate (gate → plan → work → reflect → +gate). The earlier milestones build "track and advise"; the later ones turn +that into "you don't drift in the first place." We get there incrementally — the +Guard's privileged entry-gate behavior is deliberately the last and heaviest +step (M8), and everything before it is valuable standalone. The runtime state +machine already mirrors this loop: `locked` is the gate, `planning`/`active` are +declare-and-work, `review` is reflection. - **M0 — Walking skeleton.** Daemon + Gin + minimal browser UI; port `domain` + `statemachine`; snapshot persistence; manual commitment → timebox → end. @@ -214,9 +226,16 @@ the pattern M1 establishes. adapter. Pull the day's commitments from real tasks. - **M6 — Knowledge port.** `knowledge.Source` over personal priorities and about-me context, feeding the advisor richer grounding. -- **M7 — Enforcement port.** `enforce.Guard`: make drift cost something, starting - with window-minimize (porting legacy `minimize_other`) and later the - privileged guardian / nftables path. +- **M7 — Reflection.** The deferred AI **reviewer** role, promoted into the main + loop: a session-end reflection that reads the audit trail and per-window stats + (built in M1) to summarize what happened and feed the next planning cycle. + Closes the "Focus OS Reflection" step and makes the loop self-reinforcing. +- **M8 — Enforcement & gate.** `enforce.Guard`: make drift cost something, + starting with window-minimize (porting legacy `minimize_other`) and the + nftables/DNS path, building toward the **entry gate** — the Guard checking for + a declared intention before the machine is usable. The privileged guardian + process, root-owned IPC, and break-glass keep the original Stage 2 threat + boundary and are the final, heaviest step. The first sub-project to brainstorm and spec in detail is **M0**. @@ -233,12 +252,12 @@ ports + UI). The items below are deferred past it; some are now named ports with their own later milestones (see Roadmap), others remain fully out of scope. - **Tasks, knowledge, and enforcement ports** — named in the architecture and - slotted as M5–M7, but not built in v1. The `enforce.Guard` port starts with - window-minimize; its **privileged** adapters (guardian process, root-owned - Unix socket IPC, nftables/DNS domain blocking, delayed admin, break-glass) - remain out of scope until that milestone and keep the original Stage 2 threat - boundary. -- AI reviewer / session-end reflection. + slotted as M5–M8, but not built in v1. The `enforce.Guard` port starts with + window-minimize and builds toward the entry gate; its **privileged** adapters + (guardian process, root-owned Unix socket IPC, nftables/DNS domain blocking, + delayed admin, break-glass) remain out of scope until M8 and keep the original + Stage 2 threat boundary. +- AI reviewer / session-end reflection — now scheduled as **M7 — Reflection**. - Wayland compositor adapters beyond the existing degraded reporting. - Planner/project model and outcome writeback (beyond the M5 tasks port). - Presence sensing.