savepoint 1.0.1 → 1.0.2

package/.savepoint/releases/v1.1/epics/E05-tasking-permissions/tasks/T004-implement-m-hotkey.md

@@ -0,0 +1,88 @@
+---
+id: E05-tasking-permissions/T004-implement-m-hotkey
+status: done
+objective: "Implement TUI `m` hotkey that explicitly sets the router's task from the currently focused task"
+depends_on: ["E05-tasking-permissions/T002-update-router-md", "E05-tasking-permissions/T005-add-help-entry"]
+---
+
+# T004: Implement TUI `m` hotkey
+
+## Acceptance Criteria
+
+- Pressing `m` in the TUI board (when no overlay is open) reads the currently focused task and updates `router.md` with:
+  - `release`: from focused task
+  - `epic`: from focused task
+  - `task`: full task ID
+  - `state`: `task-building` (or `audit-pending` if last uncompleted task in epic)
+- Pressing `m` when no task is focused does nothing
+- Pressing `m` when focused on a `done` task does nothing (or shows status message)
+- Router `task` field in `writeRouterReleaseEpic` is now set explicitly (currently it writes release+epic only)
+- The `m` key does NOT work when any overlay is open (consistent with other board keys)
+- The `m` key displays a status message confirming the router update: "Router set to {release} {epic}/{task}" or "Audit pending for {epic}" if last task
+
+## Implementation Plan
+
+- [x] Add `writeRouterTask(task data.Task)` method to `model.go`: reads current router, sets release/epic/task/state fields, writes via `data.WriteRouterState`
+- [x] Add `m` key handler in `update.go` main switch (before epic panel routing, like `q`/`e`/`r`/`?`)
+- [x] Handler: calls `focusedTask()` to get current task, calls `m.writeRouterTask()`, sets `m.StatusMessage` on success/error
+- [x] Detect "last uncompleted task in epic" logic: scan `m.AllTasks` for the same epic, check if any are not done
+- [x] Update `writeRouterReleaseEpic()` is unchanged (still only writes release+epic, used by navigation)
+- [x] Run `make build && make test` to verify
+
+## Strategic Visual Rework Plan
+
+This task is reopened because the `m` hotkey work exposed router-priority and board rendering paths where terminal color fallback behavior still makes the TUI look patchy between black and gray. Do not continue with incremental one-widget fixes. Apply one bottom-up rendering policy.
+
+- [x] Force Lipgloss to a deterministic 256-color profile before board rendering starts.
+- [x] Change black 256-color fallbacks for Background, Surface, and Surface 2 to the same actual ANSI256 black value.
+- [x] Centralize the background policy in `internal/styles/styles.go`: TUI surfaces emit no explicit background escapes; terminal default background remains the single source of truth.
+- [x] Remove or avoid explicit background fills from nested panels/cards where they create padded gray bars.
+- [x] Normalize focus borders across task columns, task cards, overlays, and epic sidebar. Prefer single-line box borders if rounded borders continue rendering as dash bars in Warp.
+- [x] Add regression tests that fail if rendered board/card/router-priority output emits explicit background escapes.
+- [x] Verify representative board states in both Windows Terminal and Warp after code tests pass.
+
+## Context Log
+
+Files read:
+- .savepoint/router.md
+- .savepoint/releases/v1.1/epics/E05-tasking-permissions/E05-Detail.md
+- .savepoint/releases/v1.1/epics/E05-tasking-permissions/tasks/T004-implement-m-hotkey.md
+- internal/board/model.go
+- internal/board/update.go
+- internal/board/update_test.go
+- internal/board/board.go
+- internal/board/view.go
+- internal/board/column_test.go
+- internal/board/view_test.go
+- internal/board/render_policy_test.go
+- internal/styles/palette.go
+- internal/styles/styles.go
+- internal/data/router.go
+- internal/data/write.go
+
+Estimated input tokens: 12000
+
+Notes:
+- Focused task comes from `m.Tasks[m.FocusedColumn][m.FocusedTask]`
+- Router state derivation: if all other tasks in the same epic+release are `done`, set `state: audit-pending` and clear `task`; otherwise `state: task-building` with the task ID
+- Focused test: `go test ./internal/board` passed
+- Quality gate: `make build` could not run because `make` is unavailable in this shell
+- Quality gate equivalent: `go run ./internal/buildtool build` passed
+- Quality gate equivalent: `go test ./...` passed
+- Strategic color rework: `lipgloss.SetColorProfile(termenv.ANSI256)` is set before board rendering.
+- Strategic color rework: Background, Surface, and Surface 2 ANSI256 fallbacks now all use `16`.
+- Strategic color rework: nested task/card/panel text no longer paints gray background fills; root-level full-width lines also avoid explicit background escapes.
+- Strategic border rework: rounded borders replaced with single-line borders to avoid Warp dash-bar artifacts.
+- Regression scan: no `RoundedBorder`, rounded border glyphs, or ANSI256 gray background fallback codes (`232`/`233`) remain under `internal/`.
+- Remaining manual check: visually compare representative board states in Windows Terminal and Warp.
+- Follow-up color consistency pass: removed explicit background painting from `Divider`, `HeaderFrame`, `BoardFrame`, and `RootLine`; this avoids mixing terminal-default cells with `48;5;16` cells after nested style resets.
+- Regression tightened: `internal/board/render_policy_test.go` now fails on any `48;` background escape or basic black `40m` escape across board, card, detail, release/epic dropdown, and help render paths.
+- Focused test: `go test ./internal/board` passed after the no-background policy change.
+- Quality gate: `make build` still cannot run because `make` is unavailable in this shell.
+- Quality gate equivalent: `go run ./internal/buildtool build` passed after the no-background policy change.
+- Quality gate equivalent: `go test ./...` passed after the no-background policy change.
+- Manual verification: user confirmed closeout after the PowerShell/Warp color consistency pass.
+- Closeout focused test: `go test ./internal/board` passed.
+- Closeout quality gate: `make build` failed because `make` is unavailable in this shell.
+- Closeout quality gate equivalent: `go run ./internal/buildtool build` passed.
+- Closeout quality gate equivalent: `go test ./...` passed.

package/.savepoint/releases/v1.1/epics/E05-tasking-permissions/tasks/T005-update-help-overlay.md

@@ -0,0 +1,30 @@
+---
+id: E05-tasking-permissions/T005-update-help-overlay
+status: planned
+objective: "Add `m` key binding to the TUI help overlay"
+depends_on: ["E05-tasking-permissions/T004-implement-m-hotkey"]
+---
+
+# T005: Update Help Overlay
+
+## Acceptance Criteria
+
+- Help overlay (`?` key) shows `m` key binding: "m: update router"
+- Key binding appears with consistent styling in the shortcuts list
+- No other help entries modified
+
+## Implementation Plan
+
+- [ ] Add `helpRow("m", "update router")` to `RenderHelp` in `help.go`
+- [ ] Run `make build && make test` to verify
+
+## Context Log
+
+Files read:
+- .savepoint/releases/v1.1/epics/E05-tasking-permissions/E05-Detail.md
+- .savepoint/releases/v1.1/epics/E05-tasking-permissions/tasks/T005-update-help-overlay.md
+- internal/board/help.go
+
+Estimated input tokens: 2000
+
+Notes:

package/.savepoint/releases/v1.1/epics/E05-tasking-permissions/tasks/T006-tests-and-quality-gates.md

@@ -0,0 +1,46 @@
+---
+id: E05-tasking-permissions/T006-tests-and-quality-gates
+status: planned
+objective: "Write unit tests for the `m` hotkey router update logic and verify quality gates pass"
+depends_on: ["E05-tasking-permissions/T004-implement-m-hotkey", "E05-tasking-permissions/T005-update-help-overlay"]
+---
+
+# T006: Tests & Quality Gates
+
+## Acceptance Criteria
+
+- Unit tests for `writeRouterTask()` covering:
+  - Focused task → router updated with release/epic/task/state
+  - Last uncompleted task → router shows `audit-pending`
+  - Focused `done` task → no-op
+- Unit test for `m` key handler in update_test.go:
+  - Pressing `m` updates the model's StatusMessage
+- Unit test for help overlay:
+  - `RenderHelp` output contains `m: update router`
+- `go build -o savepoint main.go` passes
+- `go test ./...` passes
+
+## Implementation Plan
+
+- [ ] Add `writeRouterTask_test.go` (or add to model_test.go) for router state derivation
+- [ ] Add `m` key test to update_test.go
+- [ ] Add help overlay test to help_test.go (if none exists, add basic test)
+- [ ] Run `go build -o savepoint main.go`
+- [ ] Run `go test ./...`
+- [ ] Fix any failures
+
+## Context Log
+
+Files read:
+- .savepoint/releases/v1.1/epics/E05-tasking-permissions/E05-Detail.md
+- .savepoint/releases/v1.1/epics/E05-tasking-permissions/tasks/T006-tests-and-quality-gates.md
+- internal/board/model.go
+- internal/board/update.go
+- internal/board/help.go
+- internal/board/update_test.go
+- internal/board/model_test.go
+- internal/board/help_test.go
+
+Estimated input tokens: 4000
+
+Notes:

package/.savepoint/releases/v1.1/v1.1-PRD.md

@@ -0,0 +1,79 @@
+---
+version: 1.1
+name: "Board Polish & Navigation"
+status: in_progress
+---
+
+# Release v1.1 — Board Polish & Navigation
+
+## Overview
+
+v1.1 is the "love what you look at" release. It takes the functional board from v1 and makes it polished, reliable, and pleasant to navigate. The four epics cover layout robustness, multi-platform tooling, visual refinement, and a new epic navigation paradigm.
+
+**v1 delivered:** a working Kanban board with phase transitions.
+**v1.1 delivers:** a board that doesn't flicker on resize, builds everywhere, looks intentional, and treats epics as first-class navigable objects.
+
+## What ships in v1.1
+
+1. **TUI Optimisation (E01)** ✅ *Audited and complete*
+   - Next Activity indicator in header
+   - Naming conventions reconciled (Design.md → E##-Detail.md, PRD.md → v1-PRD.md)
+   - Virtual viewport scrolling for columns and detail overlay
+   - Column focus border stability — no content shift when switching columns
+   - All 7 tasks done
+
+2. **Cross-Platform Compatibility (E02)** — *Not started*
+   - `make build`, `test`, `clean` work on Windows, Linux, macOS
+   - Linux amd64 + arm64 and macOS amd64 + arm64 build targets
+   - Smoke tests and versioned release artifacts
+   - 4 tasks planned
+
+3. **UI Visual Refinement (E03)** — *Not started*
+   - Right-border clipping fixed on terminal resize
+   - Next Activity as a dedicated line below header with phase-aligned styling
+   - Checkbox rendering at sentence boundaries
+   - Width arithmetic audit — content fills available space exactly
+   - 4 tasks planned
+
+4. **Epic Navigation (E04)** — *Not started*
+   - Epic sidebar becomes a focusable, navigable component
+   - ↑/↓ to navigate epics, ←/→ to enter/exit sidebar
+   - Enter opens an "Epic Detail" overlay showing E##-Detail.md content
+   - Existing `E` key dropdown retained
+   - 2 tasks planned
+
+5. **Tasking Permissions & Router Updates (E05)** — *Not started*
+   - Agents can only set `status: in_progress`; user alone sets `done` or retreats
+   - New TUI `m` hotkey explicitly updates router to the focused task
+   - Router update decoupled from navigation — browse without side effects
+   - Last task in epic detected → router shows `audit-pending`
+   - 6 tasks planned
+
+## Epic breakdown
+
+| # | Epic | Status | Tasks |
+|---|------|--------|-------|
+| 01 | TUI Optimisation | Audited | 7/7 done |
+| 02 | Cross-Platform Compatibility | Planned | 0/4 done |
+| 03 | UI Visual Refinement | Planned | 0/4 done |
+| 04 | Epic Navigation | Designing | 0/2 done |
+| 05 | Tasking Permissions & Router Updates | Planned | 0/6 done |
+
+## Success criteria
+
+- `make build` and `make test` pass on Windows, Linux, and macOS
+- Terminal resize at any width ≥ 40 produces no visual corruption
+- Content fills the available terminal width exactly at every breakpoint
+- Epic sidebar is navigable with ↑/↓, and Enter shows a detail overlay
+- All existing v1 functionality is preserved unchanged
+- `go build ./...` and `go test ./...` pass
+
+## Known issues
+
+- E03 has `Design.md` instead of the expected `E03-Detail.md` — rename to match convention (tracked in E01/T002 scope, may need a follow-up task)
+
+## Risks
+
+- **Build tooling scope creep.** E02 is pure Makefile work, but smoke-testing on non-Windows requires either CI or manual verification on actual Linux/macOS.
+- **Naming convention holdout.** E03's `Design.md` may cause discovery or rendering issues if the board ever reads `E##-Detail.md` by pattern. Low priority — handled as a rename task if needed.
+- **Epic panel is ≥120 only.** E04's features require a wide terminal — users on narrow terminals still use the `E` key dropdown.

package/.savepoint/router.md

@@ -1,136 +1,64 @@
 # Agent State Machine
 
-This file routes the agent based on the project's current state. Read this whenever you start a session.
+## Read order
 
-## Read order on every session
+1. This file (router.md)
+2. Current state → next action
+3. Active epic E##-Detail.md
+4. Active task file
 
-1. This file (you are here)
-2. The current state below to know what to do next
-3. The active epic Design
-4. The active task file, when a task is selected
-
-Read `.savepoint/PRD.md` only for project vision changes. Read `.savepoint/Design.md` only for architecture changes or audit closeout. Read `.savepoint/releases/v1/PRD.md` only for release planning or epic-order questions.
-
-**Conditional read (token discipline):** if your active task touches **TUI rendering, theme, or visual design**, also read `.savepoint/visual-identity.md` after Design.md. Otherwise skip it — it's ~1.8K tokens you don't need.
+Read `.savepoint/PRD.md` only for vision changes. Read `.savepoint/Design.md` only for architecture/audit.
 
 ## Current state
 
 ```yaml
 state: task-building
 release: v1.1
-epic: E01-tui-optimisation
-task: E01-tui-optimisation/T001-border-resize-fix
-next_action: Build v1.1 E01 T001 border resize fix.
+epic: E05-tasking-permissions
+task: E05-tasking-permissions/T005-update-help-overlay
+next_action: Build E05-tasking-permissions/T005-update-help-overlay.
 ```
 
-## State → next action
-
-<!-- AGENT: Read the state above. Find the matching block below. Follow it. -->
-
-### `state: pre-implementation`
-
-The project has its PRD and Design locked but no epics defined yet.
-
-**Next action:**
-
-1. Read `.savepoint/releases/v1/PRD.md` — the v1 release scope (epic list lives there).
-2. Help the user define the epics list and confirm priority.
-3. For each epic in order, create the directory `.savepoint/releases/v1/epics/E##-{epic-name}/` with a `Design.md` stub.
-4. When epic E01 (scaffolding) is created, transition to `state: epic-design` for that epic.
-
-**Do not** start writing code. We are still in planning.
-
-### `state: epic-design`
-
-An epic exists but its `Design.md` is empty or a stub.
-
-**Next action:** Walk the user through filling out the epic's `Design.md`:
-
-- What is this epic adding to the system?
-- What components / files does it touch?
-- What's the architectural delta vs the current state?
-
-When complete, transition to `state: epic-task-breakdown` for this epic.
-
-### `state: epic-task-breakdown`
+## State → action
 
-Epic Design exists but tasks are missing or not fully planned.
+### pre-implementation
 
-**Next action:**
+PRD + Design locked, no epics yet.
 
-1. Re-read the epic Design.
-2. Create or update the full epic task list — each task **independently buildable**, **objective-led**, with declared `depends_on`.
-3. Each task file lives at `.savepoint/releases/v1/epics/{E##-epic}/tasks/TNNN-slug.md` with frontmatter:
-   ```yaml
-   ---
-   id: {E##-epic}/TNNN-slug
-   status: planned
-   objective: "<one sentence>"
-   depends_on: []
-   ---
-   ```
-4. In the same pass, write each task's `## Implementation Plan` as inline `- [ ]` checkboxes.
-5. When every task is planned, transition to `state: task-building` for the first unblocked task.
+**Next:** 1) Read release PRD for epic list, 2) Define + confirm epic order, 3) Create epic stubs. Transition to `epic-design` for E01.
 
-### `state: task-planning`
+### epic-design
 
-Reserved for repair or late-added tasks. Normal epic planning happens during `state: epic-task-breakdown`.
+Epic E##-Detail.md is empty/stub.
 
-**Next action:** Read the task's `objective`. Write the implementation plan as inline `- [ ]` checkboxes under a `## Implementation Plan` heading. Set `status: planned`. Stop.
+**Next:** Define what this epic adds, files it touches, and architectural delta. Then transition to `epic-task-breakdown`.
 
-### `state: task-building`
+### epic-task-breakdown
 
-Task is `in_progress`. All `depends_on` are `done`.
+Epic exists, tasks missing.
 
-**Next action:** Execute the plan. Tick checkboxes as you complete them. Edit code per the **Code Style** rules in `AGENTS.md`. When all checkboxes tick, set `status: review` and stop.
+**Next:** 1) Re-read epic, 2) Create task files at `tasks/TNNN-slug.md` with `status: planned`, `objective`, `depends_on`, 3) Add `## Implementation Plan` checkboxes per task. When all planned → first unblocked task.
 
-### `state: audit-pending`
+### task-planning
 
-The last task in an epic is `done`. Audit must run before the next epic starts.
+Reserved for repair/late tasks.
 
-**Next action:** Confirm `.savepoint/audit/{E##-epic}/snapshot.md` exists. If it is missing while the audit CLI is still unavailable, create one manual snapshot from the known epic scope once; do not search broadly for replacement inputs. Then read the snapshot, read the epic's `Design.md`, and read only the files listed as changed. Write one patch-shaped proposal bundle to `.savepoint/audit/{E##-epic}/proposals.md`:
+**Next:** Write implementation plan, set `status: planned`, stop.
 
-- `Design.md` section — merge only the epic delta into project architecture.
-- `AGENTS.md` section — refresh Codebase Map entries from changed-module metadata; preserve existing rows.
-- `epic-Design.md` section — add "implemented as:" notes and deltas from the original plan.
-- `Quality Review` section — semantic-review findings against the 10 Code Style rules (advisory only).
-
-Prefer delta-only edits (`Insert After`, `Replace`, `Delete`) anchored to exact text. Do not quote and replace entire large sections unless the whole section genuinely changed.
-
-Proposal format:
-
-```md
-## Target File
-
-`path/to/file.md`
-
-## Replace
-
-<exact old heading, marker, or section>
-
-## With
-
-<new content>
-```
-
-Quality review section format:
-
-```md
-## Must Fix Before Close
-
-## Carry Forward
-
-## Already Fixed
-```
+### task-building
 
-After proposals are approved, apply approved proposals to live files, mark the epic `Design.md` as `status: audited`, update project `Design.md` `last_audited`, refresh `AGENTS.md` Codebase Map, and advance this router to the next epic state.
+Task `in_progress`, depends satisfied.
 
-Stop. The user reviews proposals in the TUI before commit actions.
+**Next:** Execute plan, tick checkboxes, run quality gates, set `status: done`, update router to next task or `audit-pending`. Stop.
 
-## Capability check
+### audit-pending
 
-If you are not Claude Opus / Gemini 2.5 Pro / GPT-5.5 / equivalent, surface a warning to the user:
+Epic complete, needs audit before next epic.
 
-> _"Heads up — I'm running on a lighter model. Savepoint's planning steps work best with top-tier models because the embedded prompts are detailed. I'll do my best, but consider switching the model for PRD/Design/Task-breakdown steps."_
+**Next:** Read snapshot + epic E##-Detail.md + changed files. Write proposals to `.savepoint/audit/{release}/{E##-epic}/proposals.md`:
+- Design.md delta
+- AGENTS.md Codebase Map refresh
+- Epic detail "implemented as" notes
+- Quality review against Code Style rules
 
-Then proceed.
+After user approves: apply proposals, mark epic `status: audited`, update Design.md `last_audited`, advance router.

package/AGENTS.md

@@ -1,141 +1,84 @@
 # Agents Guide
 
-Welcome, AI agent. This project (`savepoint`) uses its own conventions to manage its own build. You are about to dogfood the workflow.
-
 ## Workflow
 
-Before doing anything, read `.savepoint/router.md`. That file routes you to the next file based on the project's current state.
-
-**Available Custom Skills:**
-Savepoint ships with skills that define your role at each stage.
-- `draft-prd`: Acts as a strict Product Manager to interrogate the user and write the PRD.
-- `system-design`: Acts as a Staff Engineer mapping the architecture.
-- `create-plan` / `create-task`: Acts as a Technical PM breaking work into Epics and ACs.
-- `build-task`: Acts as the disciplined execution engine writing code and logging drift.
-- `audit`: Acts as the QA Lead reconciling code with documentation.
-
-**Skill Activation (CRITICAL):**
-When you read `.savepoint/router.md`, you MUST activate the corresponding agent skill for the current state before taking any action. Use the `activate_skill` tool (or equivalent) for the appropriate phase:
-- `state: draft-prd` -> Activate the `draft-prd` skill.
-- `state: design` -> Activate the `system-design` skill.
-- `state: planning` -> Activate the `create-plan` skill.
-- `state: task-breakdown` -> Activate the `create-task` skill.
-- `state: in-progress` -> Activate the `build-task` skill.
-- `state: audit-pending` -> Activate the `audit` skill.
-
-When you are about to write code, you must first read, in order:
-
-1. `.savepoint/router.md` — current state and next action
-2. The active epic Design: `.savepoint/releases/v1/epics/{E##-epic}/Design.md`
-3. The active task file: `.savepoint/releases/v1/epics/{E##-epic}/tasks/{T###}-*.md`
-4. Directly touched source/test files
-
-Read `.savepoint/PRD.md` only for project vision changes, major scope questions, or when the router explicitly asks for it.
-Read `.savepoint/Design.md` only when the task changes architecture or audit state. Read `.savepoint/releases/v1/PRD.md` only when planning epics, changing release scope, or resolving epic order.
-
-**Conditional read:** if the active task touches TUI implementation, also read `agent-skills/ink-tui-design/SKILL.md` as the execution guide. If it touches TUI rendering, theme, or visual design, also read `.savepoint/visual-identity.md` as the visual guardrails. Otherwise skip the extra files — they are tokens you do not need.
-
-**Do not load files outside the current task scope** unless the task requires it. Token discipline is the wedge of this product; we honor it on ourselves.
-
-Planning and implementation are separate handoffs:
-
-- Epic task breakdown and detailed task planning happen together in one pass by one planning agent.
-- Each task file must be independently buildable, objective-led, include explicit `depends_on` IDs, contain `## Acceptance Criteria` (observable outcomes) before `## Implementation Plan` (build checklist), and include a `## Context Log` for files read, estimated input tokens, and notes.
-- Implementation happens one task at a time and may be handed to any agent. Clear context between tasks by default; rehydrate only from the router, active epic Design, active task file, and directly touched source/test files.
-- During implementation, run focused tests for the touched behavior first; reserve the full quality-gate suite for task closeout.
+1. Read `.savepoint/router.md` — state + next action
+2. Activate skill per table below
+3. Read: router → epic → task → source files
 
-- After all tasks in an epic are `done`, hand the epic back for audit.
-- Any explicit audit request overrides the normal handoff timing for that epic. Persist the audit to `.savepoint/audit/{E##-epic}/snapshot.md` and `.savepoint/audit/{E##-epic}/proposals.md` before replying; do not stop at chat-only findings.
+## Skill Activation
 
-## Task Status Canon
+| State | Skill |
+|-------|-------|
+| pre-implementation | savepoint-draft-prd |
+| epic-design | savepoint-system-design |
+| epic-task-breakdown | savepoint-create-task |
+| task-building | savepoint-build-task |
+| audit-pending | savepoint-audit |
 
-Task frontmatter `status` must be exactly one of `planned`, `in_progress`, or `done`.
+Use `skill` tool.
 
-Active task phase is represented separately with `phase: build`, `phase: test`, or `phase: audit`, and `phase` is only valid when `status: in_progress`.
+Read `.savepoint/PRD.md` only for vision changes, `.savepoint/Design.md` only for architecture/audit.
 
-Never write `todo`, `doing`, `blocked`, `review`, `audit`, or phase names into `status`. If a task is blocked, keep its canonical status and document the blocker in the body.
+## Task Status
 
-## Task Completion Protocol
+- `status`: only `planned`, `in_progress`, or `done`
+- `phase` (build/test/audit): only when `status: in_progress`
+- Never: todo, doing, blocked, review, audit
 
-When a task reaches `status: done`, you MUST:
+## Implementation
 
-1. Verify every `## Acceptance Criteria` line has a passing test or verified manual outcome. A task is not done until its acceptance criteria are satisfied, not merely its implementation checkboxes ticked.
-2. Tick all checkboxes in the `## Implementation Plan`.
-3. Fill the `## Context Log` (files read, estimated input tokens, notes).
-4. Run the full quality-gate suite (`make build && make test`). Record the result in the Context Log.
-5. If any gate fails, fix it or document the blocker in the task file before setting `status: done`.
-6. Set the task frontmatter to `status: done`.
-7. Update `router.md` with the next action (next unblocked task, or `audit-pending` if all tasks done).
-8. **Stop. Prompt the user:**
-   > "Task {id} is done. Quality gates: {pass/fail list}. Router updated to {next_action}. Review the changes, then tell me to continue."
+1. Read task's `## Acceptance Criteria` + `## Implementation Plan`
+2. Execute in order, tick checkboxes
+3. Verify every AC has passing test/outcome
+4. Run quality gates (build + test)
+5. Update task: tick boxes, fill `## Context Log`, set `status: done`
+6. Update router.md: next task or `audit-pending`
+7. **Stop. Prompt user before continuing.**
 
-**Do not start the next task. Do not advance past this point without user acknowledgment.**
+## Drift Check
 
-## Task Closeout Meta-Check
+- New files/modules not in Codebase Map?
+- Architecture changed from Design.md?
 
-After marking a task `done` and before prompting the user, ask yourself:
+If yes → append `## Drift Notes` to task file.
 
-- Did this task add new source files, modules, or exports not in the Codebase Map?
-- Did this task change the architecture from what `.savepoint/Design.md` describes?
+## Audit Handoff
 
-If yes, append a `## Drift Notes` section to the task file:
-  - `Drift: {file} added, not yet in Codebase Map.`
-  - `Drift: {section} in Design.md may need update.`
+The agent that builds an epic **must not audit it**. Start a fresh session.
 
-Drift notes are lightweight annotations. They do **not** replace the epic audit. They flag what the next audit should reconcile.
-
-## Audit Handoff Rule
-
-The agent session that builds an epic **must not** run its audit. Audit requires fresh eyes.
-
-When all tasks in an epic are `done`:
-1. Update `router.md` to `state: audit-pending` for that epic.
-2. Stop. Tell the user: "Epic {id} is complete. Start a new agent session for the audit."
-3. The user starts a fresh session. The new agent reads `router.md`, sees `audit-pending`, and follows the audit-reconciliation instructions.
+## Code Style
 
-**If you are in the same session that built the epic, you must not audit it.**
+1. One job per file
+2. One-sentence functions
+3. Test branches
+4. Types are documentation
+5. Build, don't speculate
+6. Errors at boundaries
+7. One source of truth
+8. Comments explain WHY
+9. Content in data files
+10. Small diffs
 
-## Build / Test / Run
+## Build
 
 ```bash
-make build # go build -o savepoint main.go
-make test  # go test ./...
-make run   # go run main.go
-make clean # rm -f savepoint
+make build && make test
 ```
 
-## Code Style
-
-1. **One job per file.** If a file does two things, split it.
-2. **One-sentence rule.** If you can't describe a function in one sentence, refactor.
-3. **Test what branches.** Logic with if/else/switch gets a test. Pure rendering: skip.
-4. **Types are documentation.** No `any`. Let the compiler help.
-5. **Build, don't speculate.** No code for hypothetical futures.
-6. **Errors at boundaries.** Handle failure where data enters or leaves the system.
-7. **One source of truth.** State lives in one place. No syncing copies.
-8. **Comments explain WHY,** not what. If removing the comment wouldn't confuse a future reader, delete it.
-9. **Content in data files.** Markdown/JSON/YAML, not strings in code.
-10. **Small diffs.** Each task touches as few files as possible.
-
 ## Codebase Map
 
-| Module                               | Purpose                                                                                              |
-| ------------------------------------ | ---------------------------------------------------------------------------------------------------- |
-| `main.go`                            | CLI Entrypoint and root command wiring                                                               |
-| `internal/board/`                    | TUI board models, layout, rendering, overlays, task transitions, router priority markers, and fsnotify refresh |
-| `internal/data/`                     | Task/router/config models, frontmatter parsing, checklist state parsing, mtime-guarded writes, discovery, and generic file readers |
-| `internal/styles/`                   | Atari-Noir palette constants, terminal color fallbacks, shared TUI styles, semantic glyph/tag styles, and footer/header styling |
-| `cmd/`                               | Additional CLI subcommands (if any)                                                                  |
-| `templates/`                         | Default project scaffold markdown, YAML assets, and agent prompt templates                           |
-| `agent-skills/`                      | Custom skill guides for different agent phases (`draft-prd`, `audit`, etc.)                          |
-
-## CLI rules for agents
-
-**Never run `savepoint` commands.** The CLI is for the human. Edit files directly.
-
-(For this repo specifically: `savepoint` doesn't exist yet — we're building it. Even once it exists, this rule stands.)
+| Module | Purpose |
+|--------|---------|
+| `main.go` | CLI entrypoint, --version |
+| `internal/board/` | TUI board, overlays, epic sidebar, status glyphs |
+| `internal/buildtool/` | Makefile helper, cross-compile, archives |
+| `internal/data/` | Task/router models, frontmatter parsing, discovery |
+| `internal/styles/` | Atari-Noir palette, TUI styles |
+| `cmd/` | CLI subcommands |
+| `templates/` | Scaffold markdown, YAML, prompts |
+| `agent-skills/` | Phase-specific skill guides |
 
-## Recommended planning models
+## CLI Rules
 
-For PRD/Design/Task planning, this workflow assumes a top-tier model: Claude Opus, Gemini 2.5 Pro, GPT-5.5, or equivalent. Lighter models may not follow embedded prompt instructions reliably. If you are not one of those, advise the user before proceeding with planning steps.
- instructions reliably. If you are not one of those, advise the user before proceeding with planning steps.
+**Never run `savepoint` commands.** The CLI is for the human. Edit files directly.

package/Makefile

@@ -1,7 +1,9 @@
-.PHONY: build test run clean
+.PHONY: build test run clean build-linux build-darwin build-all dist smoke-test
+
+VERSION ?=
 
 build:
-	go build -o savepoint main.go
+	go run ./internal/buildtool -version "$(VERSION)" build
 
 test:
 	go test ./...
@@ -10,4 +12,18 @@ run:
 	go run main.go
 
 clean:
-	rm -f savepoint
+	go run ./internal/buildtool -version "$(VERSION)" clean
+
+build-linux:
+	go run ./internal/buildtool -version "$(VERSION)" build-linux
+
+build-darwin:
+	go run ./internal/buildtool -version "$(VERSION)" build-darwin
+
+build-all: build-linux build-darwin
+
+dist:
+	go run ./internal/buildtool -version "$(VERSION)" dist
+
+smoke-test:
+	go run ./internal/buildtool -version "$(VERSION)" smoke-test