savepoint 1.0.2 → 1.0.4

package/.savepoint/releases/v1.1/epics/_archived/T004-ai-reconcile.md

@@ -0,0 +1,29 @@
+---
+id: E06-audit-command/T004-ai-reconcile
+status: planned
+objective: "Generate AI prompt for semantic review, parse findings"
+depends_on: ["E06-audit-command/T003-snapshot"]
+---
+
+# T004: AI Reconcile (Semantic Review)
+
+## Acceptance Criteria
+
+- Generates a prompt file for human to give to their AI
+- Prompt includes: snapshot, epic E##-Detail.md, changed files list, AGENTS.md Code Style rules
+- Prompt instructs AI to check against 10 Code Style rules
+- After human runs AI, parses findings for "Must Fix Before Close" section
+- Fails audit if "Must Fix Before Close" has any items
+
+## Implementation Plan
+
+- [ ] Add `internal/audit/reconcile.go`
+- [ ] Implement `GeneratePrompt(epic, release) (string, error)`
+- [ ] Embed 10 Code Style rules in prompt template
+- [ ] Include snapshot.md content in prompt
+- [ ] Include epic E##-Detail.md in prompt
+- [ ] Include changed files list in prompt
+- [ ] Implement `ParseFindings(output) (hasIssues bool, err)`
+- [ ] Check for "Must Fix Before Close" header and non-empty content
+- [ ] Test prompt generation and finding parsing
+- [ ] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/_archived/T006-tui-review.md

@@ -0,0 +1,31 @@
+---
+id: E06-audit-command/T006-tui-review
+status: planned
+objective: "Implement TUI review mode for approving/rejecting proposals"
+depends_on: ["E06-audit-command/T005-proposals"]
+---
+
+# T006: TUI Review Mode
+
+## Acceptance Criteria
+
+- Shows each proposal as a side-by-side diff (old vs new)
+- User can Approve, Reject, or Edit each proposal
+- Edit opens inline editor to modify the "With" section
+- High-divergence warning if proposal changes >50% of file
+- Shows progress: X of Y proposals reviewed
+- Keyboard: arrow nav, Enter approve, Backspace reject, e edit, q quit
+
+## Implementation Plan
+
+- [ ] Add `internal/audit/review.go` with Bubble Tea model
+- [ ] Create `ReviewModel` with proposals, current index, decisions
+- [ ] Implement `RenderProposal` showing old/new side-by-side
+- [ ] Add keyboard handlers: Up/Down (nav), Enter (approve), Backspace (reject), e (edit)
+- [ ] Implement edit mode: text area for "With" content
+- [ ] Add high-divergence check (config threshold from config.yml)
+- [ ] Show progress bar: "Proposal 1 of 5"
+- [ ] Track decisions: approved/rejected/edited map
+- [ ] Return decisions to caller for apply step
+- [ ] Test review flow manually
+- [ ] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/_archived/T008-skip-handling.md

@@ -0,0 +1,34 @@
+---
+id: E06-audit-command/T008-skip-handling
+status: planned
+objective: "Implement audit skip with logging"
+depends_on: ["E06-audit-command/T001-cli-entrypoint"]
+---
+
+# T008: Skip Handling
+
+## Acceptance Criteria
+
+- `--skip --reason "..."` flags are required together
+- Missing reason shows error
+- Skipped audit logged to `.savepoint/audit-log.md`
+- Log entry includes: timestamp, epic, release, reason, skipped-by
+- Skipped epic still advances router (no changes to docs)
+
+## Implementation Plan
+
+- [ ] Add `internal/audit/log.go`
+- [ ] Implement `LogSkip(epic, release, reason) error`
+- [ ] Parse existing audit-log.md or create new
+- [ ] Append new entry in format:
+    ```markdown
+    ## {timestamp}
+
+    - **Epic:** {epic}
+    - **Release:** {release}
+    - **Reason:** {user reason}
+    - **Status:** ⚠ skipped
+    ```
+- [ ] Update router to advance past skipped epic
+- [ ] Test skip flow with valid/invalid args
+- [ ] Run `make build && make test`

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

@@ -42,22 +42,82 @@ v1.1 is the "love what you look at" release. It takes the functional board from
    - Existing `E` key dropdown retained
    - 2 tasks planned
 
-5. **Tasking Permissions & Router Updates (E05)** — *Not started*
+5. **Tasking Permissions & Router Updates (E05)** ✅ *Audited and complete*
    - 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`
+   - New TUI `p` priority hotkey explicitly updates router to the focused non-done task
+   - Router task priority decoupled from navigation — browse without side effects
+   - Priority writes keep router in `task-building`; audit handoff remains explicit
+   - All 6 tasks done
+
+6. **Audit Command (E06)** — *Planned*
+   - `savepoint audit <epic-id|release>` runs full pipeline
+   - Quality gates block on failure
+   - AI semantic review checks 10 Code Style rules — blocks if "Must Fix Before Close" has items
+   - TUI review mode for approving/rejecting proposals
+   - Updates Design.md last_audited, marks epic status: audited
+   - 9 tasks planned
+
+7. **Init Command (E07)** — *Planned*
+   - `savepoint init [dir] [--force] [--install]` scaffolds .savepoint/
+   - Target validation (empty/compatible/already-initialized)
+   - Template-based scaffold with project name interpolation
+   - Magic prompt output to stdout + clipboard
+   - Best-effort clipboard (doesn't fail on error)
+   - 7 tasks planned
+
+8. **Board Command (E08)** — *Planned*
+   - `savepoint board [--release <release>] [--epic <epic>]` launches TUI
+   - `savepoint` (no args) defaults to board
+   - Bubble Tea TUI with 3-column Kanban
+   - Detail pane for selected task
+   - Keyboard navigation (arrows, vim-style j/k/h/l)
+   - Status transitions with gate enforcement
+   - Non-TTY plain table fallback
+   - 8 tasks planned
+
+9. **Doctor Command (E09)** — *Planned*
+   - `savepoint doctor [--epic <epic>]` runs diagnostics
+   - Config, router, structure, YAML validation
+   - Dependency checks (missing deps, cycles, duplicates)
+   - Audit state and orphan detection
+   - Ad-hoc quality gate runner
+   - Human-readable diagnostic output with repair suggestions
+   - Exit codes: 0=clean, 1=problems, 2=error
    - 6 tasks planned
 
+10. **Task File Validation & Auto-Fix (E12)** — *In Progress*
+     - Default `phase: build` when `status=in_progress` but phase missing
+     - Default `status: planned` when both status and column missing
+     - Better error hints with suggested fixes
+     - Validate on write with helpful messages
+
+11. **Codebase Audit Remediation (E13)** — *In Progress*
+    - Fix cycle detection bug producing inaccurate error paths
+    - Remove dead code, stdlib reimplementations, hardcoded state maps
+    - Centralize duplicated logic (normalization, frontmatter extraction, shared utilities)
+    - Fix AtomicWrite cross-device fallback and config accent defaults
+    - Add quality gate timeout
+    - Remove committed binaries, add gitignore and linter config
+    - Decompose `update.go` monolith into focused handlers
+    - Extract synchronous I/O from `Update()` into `tea.Cmd` async pattern
+    - Add test coverage for untested packages
+    - 7 tasks planned
+
 ## Epic breakdown
 
 | # | Epic | Status | Tasks |
 |---|------|--------|-------|
 | 01 | TUI Optimisation | Audited | 7/7 done |
-| 02 | Cross-Platform Compatibility | Planned | 0/4 done |
+| 02 | Cross-Platform Compatibility | Audited | 4/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 |
+| 04 | Epic Navigation | Audited | 2/2 done |
+| 05 | Tasking Permissions & Router Updates | Audited | 6/6 done |
+| 06 | Audit Command | Planned | 0/9 done |
+| 07 | Init Command | Planned | 0/7 done |
+| 08 | Board Command | Planned | 0/8 done |
+| 09 | Doctor Command | Planned | 0/6 done |
+| 10 | Task File Validation & Auto-Fix | In Progress | 5/5 done |
+| 13 | Codebase Audit Remediation | In Progress | 0/7 done |
 
 ## Success criteria
 

package/.savepoint/router.md

@@ -12,11 +12,11 @@ Read `.savepoint/PRD.md` only for vision changes. Read `.savepoint/Design.md` on
 ## Current state
 
 ```yaml
-state: task-building
+state: epic-design
 release: v1.1
-epic: E05-tasking-permissions
-task: E05-tasking-permissions/T005-update-help-overlay
-next_action: Build E05-tasking-permissions/T005-update-help-overlay.
+epic: ""
+task: ""
+next_action: Plan next epic.
 ```
 
 ## State → action
@@ -39,26 +39,19 @@ Epic exists, tasks missing.
 
 **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.
 
-### task-planning
-
-Reserved for repair/late tasks.
-
-**Next:** Write implementation plan, set `status: planned`, stop.
-
 ### task-building
 
 Task `in_progress`, depends satisfied.
 
-**Next:** Execute plan, tick checkboxes, run quality gates, set `status: done`, update router to next task or `audit-pending`. Stop.
+**Next:** When starting work, set task `status: in_progress` and press `p` in TUI to mark the focused task as router priority. Execute plan, tick checkboxes, run quality gates, update router to next task or `audit-pending`. Stop.
 
 ### audit-pending
 
 Epic complete, needs audit before next epic.
 
-**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
+**Next:** Fresh audit agent reads epic E##-Detail.md, task files, drift notes, Design.md, AGENTS.md, and scoped changed files. Write one audit file to `.savepoint/releases/{release}/epics/{E##-epic}/E##-Audit.md`:
+- `## Main Findings` user-facing narrative only
+- `## Code Style Review` checklist against AGENTS.md rules
+- `## Proposed Changes` admin/apply blocks using `### Target File`, `### Replace`, `### With`
 
-After user approves: apply proposals, mark epic `status: audited`, update Design.md `last_audited`, advance router.
+After user approves: apply proposals, mark epic `status: audited`, update Design.md `last_audited`, advance router.

package/AGENTS.md

@@ -16,25 +16,29 @@
 | task-building | savepoint-build-task |
 | audit-pending | savepoint-audit |
 
-Use `skill` tool.
+Use the `skill` tool when the listed skill is available. If the agent says the skill is not found, read `agent-skills/{skill}/SKILL.md` directly and follow it as the active skill.
 
 Read `.savepoint/PRD.md` only for vision changes, `.savepoint/Design.md` only for architecture/audit.
 
 ## Task Status
 
 - `status`: only `planned`, `in_progress`, or `done`
-- `phase` (build/test/audit): only when `status: in_progress`
+- `stage` (build/test/audit): **required** when `status: in_progress` — omitting it is a parse error
 - Never: todo, doing, blocked, review, audit
+- Agents may set a task to `status: in_progress` when starting implementation.
+- Only the user may set a task to `status: done` or retreat a task to an earlier status.
 
 ## Implementation
 
-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.**
+1. Read task's `## Context Files` using `Read` tool — one call per file, no explore, no glob
+2. Read task's `## Acceptance Criteria` + `## Implementation Plan`
+3. When starting implementation, set task frontmatter to `status: in_progress` + `stage: build` (both required together)
+4. After setting `in_progress`, press `p` in the TUI to mark the focused task as router priority
+5. Execute in order, tick checkboxes
+6. Verify every AC has passing test/outcome
+7. Run quality gates (build + test)
+8. Update router.md: next task or `audit-pending`
+9. **Stop. Prompt user before continuing.**
 
 ## Drift Check
 
@@ -47,18 +51,26 @@ If yes → append `## Drift Notes` to task file.
 
 The agent that builds an epic **must not audit it**. Start a fresh session.
 
+## Audit File Structure
+
+- Audit is agent-led via `savepoint-audit`, not a `savepoint audit` CLI pipeline.
+- Write exactly one `.savepoint/releases/{release}/epics/{E##-slug}/E##-Audit.md`.
+- The TUI Audit tab renders `## Main Findings` and `## Code Style Review` only.
+- Keep file-specific `### Target File` / `### Replace` / `### With` blocks under `## Proposed Changes` so admin apply details do not appear in the Epic Detail panel.
+- During audit apply/close, update the same `E##-Audit.md` visible sections so `## Main Findings` and `## Code Style Review` describe the applied outcome, not stale pre-apply blockers.
+
 ## Code Style
 
-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
+- **One job per file** — split files when responsibilities mix.
+- **One job per function** — small, named, testable units.
+- **Test branches** — cover meaningful conditionals and edge cases.
+- **Types document intent** — prefer explicit types over comments.
+- **Build only what is needed** — no speculative abstractions.
+- **Handle errors at boundaries** — validate inputs, APIs, IO, and external data.
+- **One source of truth** — no duplicated rules, constants, state, or config.
+- **Comments explain why** — not what the code already says.
+- **Content lives in data** — keep copy/config out of logic.
+- **Small diffs** — minimal, reviewable, behaviour-preserving changes.
 
 ## Build
 
@@ -71,14 +83,17 @@ make build && make test
 | 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 |
+| `cmd/` | CLI command arg parsing and dispatch for init, board, and doctor |
+| `internal/init/` | Target validation, scaffold writing from templates |
+| `internal/board/` | TUI board, overlays, epic sidebar, Next Activity line, router priority key, detail checklist rendering, status glyphs, forced color profile, debug logging hooks, async update I/O commands, shared board utilities |
+| `internal/buildtool/` | Makefile helper, cross-compile including Windows targets, archives, distribution checksums |
+| `internal/doctor/` | Read-only project diagnostics, integrity checks, timed quality gate execution, report formatting, typed repair suggestions |
+| `internal/data/` | Task/router models, frontmatter parsing/splitting, lifecycle validation/defaulting, discovery including root-dir traversal, unified task status constants, canonical write helpers |
+| `internal/testutil/` | Shared Go test fixtures and filesystem helpers for internal package tests |
 | `internal/styles/` | Atari-Noir palette, TUI styles |
-| `cmd/` | CLI subcommands |
 | `templates/` | Scaffold markdown, YAML, prompts |
 | `agent-skills/` | Phase-specific skill guides |
 
 ## CLI Rules
 
-**Never run `savepoint` commands.** The CLI is for the human. Edit files directly.
+**Never run `savepoint` commands.** The CLI is for the human. Edit files directly.

package/Makefile

@@ -1,4 +1,4 @@
-.PHONY: build test run clean build-linux build-darwin build-all dist smoke-test
+.PHONY: build test run clean build-linux build-darwin build-all dist smoke-test ci
 
 VERSION ?=
 
@@ -27,3 +27,5 @@ dist:
 
 smoke-test:
 	go run ./internal/buildtool -version "$(VERSION)" smoke-test
+
+ci: test build

package/README.md

@@ -61,7 +61,6 @@ Built for a cinematic, technical feel without the bloat.
 | :----------------- | :--------------------------------------------------------------------------------------------------- |
 | `savepoint init`   | Scaffold the loop, write your `AGENTS.md` guide, drop the baby gates, and generate the magic prompt. |
 | `savepoint board`  | Launch the Atari-Noir Kanban TUI to track the vibe.                                                  |
-| `savepoint audit`  | Stop the AI. Sync the map with the territory.                                                        |
 | `savepoint doctor` | Check the integrity of the state machine.                                                            |
 
 ---

package/agent-skills/savepoint-audit/SKILL.md

@@ -1,35 +1,87 @@
-# Savepoint Skill: Audit (`audit`)
-
-## Objective
-At the end of an epic, review the implemented code against the Epic objectives and Task Acceptance Criteria, and reconcile any documentation "Drift".
-
-## Context
-The Audit Gate is Savepoint's wedge. It prevents projects from degrading into chaos. The `audit` agent acts as the Quality Assurance and Documentation Lead. It reviews the work of the `build-task` agent with "fresh eyes," ensuring that the `Design.md` and the `AGENTS.md` Codebase Map reflect the actual reality of the codebase before the next Epic begins.
-
-## Trigger
-This skill is activated when the `.savepoint/router.md` state is `audit-pending`.
-
-## Input
-- `.savepoint/audit/{release}/{E##-slug}/snapshot.md` (what changed).
+---
+name: savepoint-audit
+description: Performs Savepoint audit-pending work for a completed epic, reviewing implementation against task acceptance criteria and writing the required E##-Audit.md handoff file.
+---
+
+# Savepoint Skill: Audit (`audit`)
+
+## Objective
+At the end of an epic, review the implemented code against the Epic objectives and Task Acceptance Criteria, and reconcile any documentation "Drift".
+
+## Context
+The Audit Gate is Savepoint's wedge. It prevents projects from degrading into chaos. The `audit` agent acts as the Quality Assurance and Documentation Lead. It reviews the work of the `build-task` agent with "fresh eyes," ensuring that the `Design.md` and the `AGENTS.md` Codebase Map reflect the actual reality of the codebase before the next Epic begins.
+
+## Trigger
+This skill is activated when the `.savepoint/router.md` state is `audit-pending`.
+
+## Input
 - `.savepoint/releases/{release}/epics/{E##-slug}/E##-Detail.md` (the epic design).
-- `.savepoint/Design.md` (project architecture).
-- `AGENTS.md` (agent guide and codebase map).
-- The source and test files modified during the Epic.
-
-## Workflow
-
-1.  **Fresh Eyes Check:** If you are the exact same agent session that just built the `build-task` code for this Epic, you MUST STOP. Tell the user: "Epic complete. Start a new agent session for the audit."
-2.  **Verify ACs:** Review the completed tasks for the Epic. Ensure the Acceptance Criteria were actually met by the committed code.
-3.  **Process Drift Notes (Reconciliation):** Read every task file in the Epic and look for `## Drift Notes`.
-4.  **Draft Proposals:** Based on the code changes and the Drift Notes, write exactly ONE file: `.savepoint/audit/{release}/{E##-slug}/proposals.md`. It must contain:
-    *   **Design.md section:** Propose updates to merge the epic's architectural changes into the project-level `Design.md`.
-    *   **AGENTS.md section:** Propose updates to refresh the Codebase Map table with new or changed modules.
-    *   **Epic-E##-Detail.md section:** Add "Implemented as:" notes showing where reality deviated from the original plan.
-    *   **Quality Review section:** List any minor code-style infractions that must be fixed before the next Epic.
-5.  **Review Format:** Use `## Target File`, `## Replace`, and `## With` formatting in the proposals document so it is easy for a human (or an agent) to apply later.
-6.  **Handoff:** Do not apply the proposals yourself. Do not mark the epic audited. Stop and prompt the user to review `.savepoint/audit/{release}/{E##-slug}/proposals.md` (often via the TUI). Once the user approves, the proposals are applied, and the router moves to the next Epic.
-
-## Constraints
-- **Do not write product code.** You are an auditor.
-- **Do not apply the changes immediately.** Write the proposals document first.
-- **One proposals file.** Do not create multiple proposal files.
+- `.savepoint/Design.md` (project architecture).
+- `AGENTS.md` (agent guide and codebase map).
+- The source and test files modified during the Epic.
+
+## Workflow
+
+1.  **Fresh Eyes Check:** If you are the exact same agent session that just built the `build-task` code for this Epic, you MUST STOP. Tell the user: "Epic complete. Start a new agent session for the audit."
+2.  **Verify ACs:** Review the completed tasks for the Epic. Ensure the Acceptance Criteria were actually met by the committed code. Also confirm each task file has a `## Context Files` section — flag any missing ones under `## Main Findings` as a process gap.
+3.  **Process Drift Notes (Reconciliation):** Read every task file in the Epic and look for `## Drift Notes`.
+4.  **Draft Audit File:** Based on the code changes and the Drift Notes, write exactly ONE file: `.savepoint/releases/{release}/epics/{E##-slug}/E##-Audit.md`. It must use this format:
+    ````md
+    ---
+    type: audit-findings
+    audited: YYYY-MM-DD
+    ---
+    # Audit Findings: E## {Epic Name}
+
+    ## Main Findings
+    [human-readable audit summary only: AC verification, important drift, and notable risks. Do not include per-file replacement blocks here.]
+
+    ## Code Style Review
+    - [ ] One job per file
+    - [ ] One-sentence functions
+    - [ ] Test branches
+    - [ ] Types are documentation
+    - [ ] Build, don't speculate
+    - [ ] Errors at boundaries
+    - [ ] One source of truth
+    - [ ] Comments explain WHY
+    - [ ] Content in data files
+    - [ ] Small diffs
+
+    ## Proposed Changes
+    ### Target File
+    path/to/file.md
+
+    ### Replace
+    ```
+    exact old text
+    ```
+
+    ### With
+    ```
+    replacement text
+    ```
+    ````
+    The TUI Audit tab renders only `## Main Findings` and `## Code Style Review`. Keep `## Proposed Changes` as admin/apply metadata so the Epic Detail panel does not show stale file-change blocks.
+5.  **Review Format:** Use `### Target File`, `### Replace`, and `### With` formatting only inside `## Proposed Changes`. Include proposals for:
+    *   **Design.md:** Merge the epic's architectural changes into the project-level `Design.md`.
+    *   **AGENTS.md:** Refresh the Codebase Map table with new or changed modules.
+    *   **Epic E##-Detail.md:** Add "Implemented as:" notes showing where reality deviated from the original plan.
+    *   **Implementation fixes:** Include any must-fix code or test changes found during audit.
+6.  **Handoff:** Do not apply the proposals yourself. Do not mark the epic audited. Stop and prompt the user to review `.savepoint/releases/{release}/epics/{E##-slug}/E##-Audit.md` (via the TUI Audit tab). Tell them: "Review the audit tab. When ready, say 'apply audit' to apply proposals and close the epic."
+7.  **Apply + Close** (only when the user approves by saying "apply audit" or equivalent):
+    1.  Read `E##-Audit.md` — extract every `### Target File` / `### Replace` / `### With` block from `## Proposed Changes`.
+    2.  For each pair, apply the replacement to the target file named in the preceding `### Target File` line.
+    3.  Update `E##-Audit.md` visible sections: rewrite `## Main Findings` and `## Code Style Review` so the TUI Audit tab reflects the applied outcome, resolved findings, remaining risks if any, and final code-style status. Keep `## Proposed Changes` intact as admin/apply trace unless the user asks to remove it.
+    4.  Update `E##-Detail.md` frontmatter: set `status: audited`.
+    5.  Update `.savepoint/Design.md` frontmatter: set `last_audited: {release}/{E##-slug}`.
+    6.  Read `.savepoint/router.md` current state. Advance:
+        - If more epics remain in the release: set `state: epic-design`, `epic: {next-epic-slug}`, `task: ""`, `next_action: "Draft epic design"`.
+        - If no more epics: set `state: epic-design`, `epic: ""`, `next_action: "Plan next epic"`.
+    7.  Print apply summary: "Applied X proposals. Updated audit findings. Epic {E##} closed as audited. Router → {new state}."
+
+## Constraints
+- **Do not write product code.** You are an auditor.
+- **Do not apply the changes immediately.** Write the proposals document first.
+- **One proposals file.** Do not create multiple proposal files.
+- **No CLI audit pipeline.** Savepoint audit is agent-led and skill-driven; do not invoke or design around a `savepoint audit` command.

package/agent-skills/savepoint-build-task/SKILL.md

@@ -1,4 +1,9 @@
-# Savepoint Skill: Build Task (`build-task`)
+---
+name: savepoint-build-task
+description: Executes Savepoint task-building work when .savepoint/router.md state is task-building, including implementing one active task, checking acceptance criteria, running quality gates, and stopping for user review.
+---
+
+# Savepoint Skill: Build Task (`build-task`)
 
 ## Objective
 Act as a disciplined coding agent that strictly follows Savepoint's implementation loop.
@@ -36,4 +41,4 @@ This skill is activated when the `.savepoint/router.md` state is `task-building`
 
 ## Constraints
 - **Stay in scope:** Do not touch files outside of what is required for the Acceptance Criteria.
-- **Do not edit architecture documents.** If you must deviate from the plan, write the code and log a "Drift Note" in the task file.
+- **Do not edit architecture documents.** If you must deviate from the plan, write the code and log a "Drift Note" in the task file.

package/agent-skills/savepoint-create-plan/SKILL.md

@@ -1,4 +1,9 @@
-# Savepoint Skill: Create Plan (`create-plan`)
+---
+name: savepoint-create-plan
+description: Creates Savepoint release epics from the PRD and Design documents when the router is in pre-implementation planning.
+---
+
+# Savepoint Skill: Create Plan (`create-plan`)
 
 ## Objective
 Turn the Product Requirements Document (PRD) and the architectural `Design.md` into Epics (logical slices of work) and high-level tasks that can be implemented independently.
@@ -25,4 +30,4 @@ This skill is activated when the `.savepoint/router.md` state is `pre-implementa
 
 ## Constraints
 - **Do not write code.**
-- **Do not write detailed implementation steps.** That is the job of the `create-task` skill. Keep the task outlines high-level at this stage.
+- **Do not write detailed implementation steps.** That is the job of the `create-task` skill. Keep the task outlines high-level at this stage.

package/agent-skills/savepoint-create-task/SKILL.md

@@ -1,31 +1,44 @@
-# Savepoint Skill: Create Task (`create-task`)
-
-## Objective
-Take high-level tasks identified during the planning phase and build detailed, actionable task plans with strict Acceptance Criteria.
-
-## Context
-A task plan is a contract between the planner and the builder. If the task plan is vague, the resulting code will be buggy. The `create-task` skill acts as a Senior Engineer writing tickets for a Junior Developer (the `build-task` agent). It must define exactly *what* constitutes success and *how* to achieve it, without actually writing the code.
-
-## Trigger
-This skill is activated when the `.savepoint/router.md` state is `epic-task-breakdown` and the router points to a specific epic.
-
-## Input
-- `.savepoint/releases/v1/epics/{E##-epic}/E##-Detail.md` (The active Epic's design).
-- The high-level task markdown file (e.g., `.savepoint/releases/v1/epics/{E##-epic}/tasks/T001-slug.md`).
-
-## Workflow
-
-1.  **Read Context:** Understand the goal of the specific task within the context of its parent Epic.
-2.  **Define Acceptance Criteria (ACs):** This is the most critical step. Write explicit, observable outcomes. (e.g., "Running `npm test` passes 5 tests for the auth module" or "The `/login` route returns a 200 OK with a valid JWT"). Do not use subjective language like "looks good."
-3.  **Draft Implementation Plan:** Create a step-by-step checklist for the `build-task` agent to follow.
-    *   List which files need to be created or modified.
-    *   Specify which functions or components need to be written.
-    *   Include instructions to write tests *first* if applicable.
-4.  **Add Context Log Shell:** Ensure the bottom of the task file includes a `## Context Log` section with placeholders for `Files read:`, `Estimated input tokens:`, and `Notes:`.
-5.  **Define Dependencies:** If this task relies on another task being completed first, explicitly declare it in the YAML frontmatter (e.g., `depends_on: [T001-setup]`).
-6.  **Status Update:** Change the task frontmatter to `status: planned`.
-7.  **Handoff:** Update `.savepoint/router.md` to `state: in-progress` and ensure it points to the newly planned task. Prompt the user to approve the task plan before building begins.
-
-## Constraints
-- **Do not write code.** Your job is to plan the work, not execute it.
-- **Keep it isolated:** The task plan should touch as few files as possible. If a task plan requires modifying 15 files, it is too large and should be broken down further.
+---
+name: savepoint-create-task
+description: Plans Savepoint task files during epic-task-breakdown by writing acceptance criteria, implementation checklists, dependencies, and context-log shells.
+---
+
+# Savepoint Skill: Create Task (`create-task`)
+
+## Objective
+Take high-level tasks identified during the planning phase and build detailed, actionable task plans with strict Acceptance Criteria.
+
+## Context
+A task plan is a contract between the planner and the builder. If the task plan is vague, the resulting code will be buggy. The `create-task` skill acts as a Senior Engineer writing tickets for a Junior Developer (the `build-task` agent). It must define exactly *what* constitutes success and *how* to achieve it, without actually writing the code.
+
+## Trigger
+This skill is activated when the `.savepoint/router.md` state is `epic-task-breakdown` and the router points to a specific epic.
+
+## Input
+- `.savepoint/releases/v1/epics/{E##-epic}/E##-Detail.md` (The active Epic's design).
+- The high-level task markdown file (e.g., `.savepoint/releases/v1/epics/{E##-epic}/tasks/T001-slug.md`).
+
+## Workflow
+
+1.  **Read Context:** Understand the goal of the specific task within the context of its parent Epic.
+2.  **Define Acceptance Criteria (ACs):** This is the most critical step. Write explicit, observable outcomes. (e.g., "Running `npm test` passes 5 tests for the auth module" or "The `/login` route returns a 200 OK with a valid JWT"). Do not use subjective language like "looks good."
+3.  **Draft Implementation Plan:** Create a step-by-step checklist for the `build-task` agent to follow.
+    *   List which files need to be created or modified.
+    *   Specify which functions or components need to be written.
+    *   Include instructions to write tests *first* if applicable.
+4.  **Populate Context Files:** Add a `## Context Files` section listing the exact file paths the build agent must read before coding. Pull these from the epic's Components table — only the files this task actually touches or depends on. Example:
+    ```markdown
+    ## Context Files
+    - `internal/board/board.go`
+    - `internal/board/model.go`
+    - `internal/data/config.go`
+    ```
+    No globs. No directories. Exact paths only.
+5.  **Add Context Log Shell:** Ensure the bottom of the task file includes a `## Context Log` section with placeholders for `Files read:`, `Estimated input tokens:`, and `Notes:`.
+5.  **Define Dependencies:** If this task relies on another task being completed first, explicitly declare it in the YAML frontmatter (e.g., `depends_on: [T001-setup]`).
+6.  **Status Update:** Change the task frontmatter to `status: planned`.
+7.  **Handoff:** Update `.savepoint/router.md` to `state: in-progress` and ensure it points to the newly planned task. Prompt the user to approve the task plan before building begins.
+
+## Constraints
+- **Do not write code.** Your job is to plan the work, not execute it.
+- **Keep it isolated:** The task plan should touch as few files as possible. If a task plan requires modifying 15 files, it is too large and should be broken down further.

package/agent-skills/savepoint-draft-prd/SKILL.md

@@ -1,4 +1,9 @@
-# Savepoint Skill: Draft PRD (`draft-prd`)
+---
+name: savepoint-draft-prd
+description: Guides Savepoint PRD drafting and refinement before implementation, interviewing the user until the product scope is clear enough for design.
+---
+
+# Savepoint Skill: Draft PRD (`draft-prd`)
 
 ## Objective
 Help the user write a structured, sufficiently detailed Product Requirements Document (PRD) before any design or planning occurs.
@@ -29,4 +34,4 @@ This skill is activated when the `.savepoint/router.md` state is `pre-implementa
 ## Constraints
 - **Do not write code.**
 - **Do not plan Epics.** That is the job of the `create-plan` skill.
-- **Do not make technical architectural decisions.** That is the job of the `system-design` skill. Your focus is strictly on *what* and *why*, not *how*.
+- **Do not make technical architectural decisions.** That is the job of the `system-design` skill. Your focus is strictly on *what* and *why*, not *how*.

package/agent-skills/savepoint-system-design/SKILL.md

@@ -1,4 +1,9 @@
-# Savepoint Skill: System Design (`system-design`)
+---
+name: savepoint-system-design
+description: Produces Savepoint system or epic design documents from the PRD when the router is in epic-design or the user asks for architectural design.
+---
+
+# Savepoint Skill: System Design (`system-design`)
 
 ## Objective
 Translate the Product Requirements Document (PRD) into the initial architectural blueprint (`Design.md`) before the planning phase breaks the work down into Epics.
@@ -30,4 +35,4 @@ This skill is activated when the `.savepoint/router.md` state is `epic-design` o
 ## Constraints
 - **Do not write code.**
 - **Do not break down tasks.** That is the job of the `create-plan` skill.
-- **Maintain Token Discipline:** Keep the `Design.md` concise. It is meant to be read by AI agents on every turn. Rambling design docs destroy context windows.
+- **Maintain Token Discipline:** Keep the `Design.md` concise. It is meant to be read by AI agents on every turn. Rambling design docs destroy context windows.