Phase 1: hexagonal refactor (ports & adapters) + tests

.gitignore

@@ -1,6 +1,5 @@
 # built binary
 /sysmon
-sysmon
 
 # macOS
 .DS_Store

.golangci.yml

@@ -20,6 +20,8 @@ formatters:
     goimports:
       local-prefixes:
         - sysmon
+    gofumpt:
+      module-path: sysmon
 
 linters:
   enable:

.planning/PROJECT.md

@@ -55,7 +55,7 @@ nearly free in resource use.
 ## Constraints
 
 - **Tech stack**: Go 1.26 + cgo, macOS only (arm64) — uses CoreGraphics/ApplicationServices C API.
-- **Dependencies**: standard library only — new third-party deps require justification.
+- **Dependencies**: runtime/production is standard-library only (zero third-party in the binary — reason `log/slog` was chosen). Test-only deps are allowed: `testify` (assertions), `go.uber.org/mock`/mockgen (mocks from interfaces), `testcontainers` (integration tests only).
 - **Platform**: requires Xcode Command Line Tools and macOS Accessibility permission.
 - **Resource use**: must stay lightweight — near-zero idle CPU, tiny memory footprint, battery-friendly (runs for hours in background).
 
@@ -71,6 +71,7 @@ nearly free in resource use.
 | Structured logging via stdlib log/slog | Levels/structure without breaking the zero-dep constraint (vs zerolog/zap) | — Pending |
 | CI on macos-latest (build/lint/test) | cgo + CoreGraphics only compiles on macOS | ✓ Good |
 | golangci-lint v2 (strict golden config, trimmed) | Consistent strict linting, minus project-specific/web linters | ✓ Good |
+| Test stack: testify + mockgen (from interfaces) + testcontainers | Standard Go test tooling; mocks generated, not hand-written (test-only deps, binary stays zero-dep) | — Pending |
 
 ## Evolution
 

.planning/ROADMAP.md

@@ -18,10 +18,11 @@ Milestone: v1 — Hexagonal Refactor
   3. `KeeperService` (in `service`) depends only on `domain` and `port` types, never imports `adapter`, and runs the tick loop via the `Keeper`/`Pointer` interfaces
   4. `CGPointer` adapter implements `Pointer` using cgo/CoreGraphics and is isolated behind a `//go:build darwin` tag
   5. `go build` succeeds, all Makefile targets (build/run/start/stop/status/clean) work unchanged, and `go test ./...` passes a `KeeperService` unit test using a fake `Pointer` that verifies nudges fire on the interval without moving the real mouse and without requiring macOS Accessibility permission
-**Plans**: TBD
+**Plans**: 1 plan
+- [ ] 01-01-PLAN.md — Restructure flat main.go into cmd/sysmon + internal/activity {domain,port,service,adapter}, add mockgen+testify+synctest unit test, inject slog logging, update Makefile, remove root main.go; behavior preserved
 
 ## Progress
 
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
-| 1. Hexagonal Refactor | 0/? | Not started | - |
+| 1. Hexagonal Refactor | 0/1 | Not started | - |

.planning/config.json

@@ -45,7 +45,8 @@
     "post_planning_gaps": true,
     "security_enforcement": true,
     "security_asvs_level": 1,
-    "security_block_on": "high"
+    "security_block_on": "high",
+    "_auto_chain_active": false
   },
   "ship": {
     "pr_body_sections": []

.planning/phases/01-hexagonal-refactor/01-CONTEXT.md

@@ -0,0 +1,96 @@
+# Phase 1 — Hexagonal Refactor — CONTEXT
+
+**Source:** Synthesized from `docs/TASK.md` §10, PROJECT.md Key Decisions, and the
+`log/slog` decision (design already locked earlier; interactive discuss-phase skipped
+as redundant).
+
+## Phase Boundary
+
+Restructure the existing, working flat `main.go` into a hexagonal (ports &
+adapters) layout, add a unit test, and wire in structured logging — **without
+changing observable runtime behavior**. This is a pure refactor + tests +
+logging. No new features.
+
+In scope: ARCH-01..05, TEST-01, BUILD-01, BUILD-02, LOG-01.
+Out of scope: autostart/LaunchAgent, working-hours, key-press mode, non-macOS
+adapters (all v2/deferred).
+
+## Implementation Decisions (locked)
+
+### Structure
+- Layout exactly per `docs/TASK.md` §10:
+  - `cmd/sysmon/main.go` — entry point: flag parsing (`-interval`, `-quiet`),
+    dependency wiring (manual DI), signal handling, startup. No business logic.
+  - `internal/activity/domain/` — pure Go value objects + rules (e.g. an
+    `Interval` that validates `> 0`, an `Offset`). Imports nothing from
+    `port`/`service`/`adapter`; no cgo/os/time-from-outside.
+  - `internal/activity/port/` — interfaces: driven port `Pointer` with
+    `Nudge(dx, dy int) error`; driving port `Keeper` with `Run(ctx) error`.
+  - `internal/activity/service/` — `KeeperService` implements `Keeper`: ticker
+    loop, on each tick `Pointer.Nudge(+1,0)` → pause → `Nudge(-1,0)`; stops
+    cleanly on `ctx` cancellation. Depends only on `domain` + `port`.
+  - `internal/activity/adapter/` — `CGPointer` implements `Pointer` via
+    cgo/CoreGraphics (`CGEventCreateMouseEvent`/`CGEventPost`), behind
+    `//go:build darwin`. All CoreFoundation objects released with `CFRelease`.
+- Remove the flat `main.go` from the repo root.
+- Module path stays `sysmon`; internal import paths are `sysmon/internal/activity/...`.
+
+### Behavior preservation (must not change)
+- Flags `-interval` (default 10s) and `-quiet`; real `kCGEventMouseMoved` event
+  via `CGEventPost(kCGHIDEventTap, …)`; 1px nudge there-and-back with the ~40ms
+  pause; clean exit on SIGINT/SIGTERM (code 0); `time.Ticker` sleep between ticks
+  (near-zero idle CPU — no busy-wait).
+- Makefile targets (build/run/start/stop/status/clean) keep working unchanged.
+
+### Logging (LOG-01)
+- Use stdlib `log/slog`. Inject a `*slog.Logger` into `KeeperService` (constructor
+  param) — no package-global logger, so tests stay clean.
+- `-quiet` raises the level threshold (e.g. warn+ only) rather than redirecting
+  output. Lifecycle events (start with interval, stop) logged with structure.
+- Zero third-party logger — this is the whole reason slog was chosen.
+
+### Testing (TEST-01) — locked test stack
+- **Assertions: `testify`** (`github.com/stretchr/testify`) only.
+- **Mocks: `mockgen`** (`go.uber.org/mock`) generated **from the `Pointer`
+  interface** — NOT a hand-written fake (this overrides the research's
+  hand-written-fake suggestion, per user convention). Use a `//go:generate
+  mockgen ...` directive and commit the generated mock (e.g. a `mocks` package
+  or `port/mock_pointer.go`).
+- **Deterministic time: `testing/synctest`** (stdlib, Go 1.25+) to drive the
+  ticker without real-time flakiness. Composes with testify+mockgen: synctest
+  controls the clock, the mock records `Nudge` calls, testify asserts.
+- Test asserts nudges occur per tick and the loop stops on context cancel. It
+  must NOT move the real mouse and must NOT require macOS Accessibility — it
+  never touches the `CGPointer` adapter.
+- **`testcontainers`** is the convention for integration tests, but sysmon has
+  none — do NOT add it as a dependency.
+- `go test -race ./...` must pass (CI runs it).
+
+### Dependency policy clarification
+- The runtime/production binary stays **stdlib-only** (zero third-party) — this
+  is why `log/slog` was chosen.
+- **Test-only** deps are allowed and expected: `testify`, `go.uber.org/mock`
+  (mockgen). They live in `go.mod` but are not linked into the binary.
+
+## Claude's Discretion
+- Exact domain type shape (`Interval`/`Offset` naming, whether Offset is a
+  domain type or a constant), constructor signatures, and how the tick source is
+  made testable (injected clock/ticker vs short interval) — pick the cleanest
+  idiomatic Go. Keep it small; do not over-engineer a tiny utility.
+- Whether `Keeper.Run` takes the interval/offset via constructor or method.
+
+## Canonical References
+- `docs/TASK.md` §10 — the authoritative architecture spec.
+- `.planning/codebase/ARCHITECTURE.md` — current→target mapping.
+- Current `main.go` — the behavior to preserve (cgo nudge, flags, signals, loop).
+
+## Specific Ideas
+- Keep the cgo C `nudge` helper essentially as-is, just relocated into the
+  `CGPointer` adapter with the `//go:build darwin` tag.
+- `cmd/sysmon/main.go` builds a `slog.Logger`, constructs `CGPointer`, injects
+  both into `KeeperService`, wires SIGINT/SIGTERM to a `context.CancelFunc`, and
+  calls `keeper.Run(ctx)`.
+
+## Deferred Ideas
+- LaunchAgent autostart, working-hours window, key-press mode, Linux/Windows
+  adapters — all out of scope for this phase (tracked in REQUIREMENTS.md v2).