savepoint 1.0.2 → 1.0.4

package/.savepoint/releases/v1.1/epics/E07-init-command/E07-Audit.md

@@ -0,0 +1,336 @@
+---
+type: audit-findings
+audited: 2026-05-03
+---
+
+# Audit Findings: E07 Init Command
+
+## Main Findings
+
+E07 is implemented and the Go baseline passes: `go test ./internal/init ./cmd`, `go build ./...`, and `go test ./...` all succeeded. The command parser, target validation, scaffold copy, prompt rendering, clipboard best-effort path, and integration coverage are present.
+
+Audit apply resolved the generated-template drift. New Savepoint projects now receive `stage` task-status instructions, `make build && make test` quality-gate guidance, and the current epic-local `E##-Audit.md` audit workflow instead of the archived `.savepoint/audit/.../proposals.md` pipeline.
+
+Audit apply also tightened scaffold safety. Init validation now treats an existing root `agent-skills/` directory as a conflict unless `--force` is set, and `AtomicWrite` uses a portable replace helper that falls back to backup/restore when a platform cannot rename over an existing target.
+
+The clipboard task record was reconciled: `T006-clipboard.md` now reflects the implemented `ClipboardResult` API, best-effort status handling, current-platform tests, and completed Go quality gates.
+
+## Code Style Review
+
+- [x] One job per file
+- [x] One-sentence functions
+- [x] Test branches
+- [x] Types are documentation
+- [x] Build, don't speculate
+- [x] Errors at boundaries
+- [x] One source of truth
+- [x] Comments explain WHY
+- [x] Content in data files
+- [x] Small diffs
+
+The audit-close patch brought generated workflow content back in line with the live root instructions, added tests that guard template freshness, and kept the scaffold conflict/overwrite fixes scoped to `internal/init`.
+
+## Proposed Changes
+
+### Target File
+templates/project/AGENTS.md
+
+### Replace
+```
+- `phase` (build/test/audit): only when `status: in_progress`
+```
+
+### With
+```
+- `stage` (build/test/audit): **required** when `status: in_progress` — omitting it is a parse error
+```
+
+### Target File
+templates/project/AGENTS.md
+
+### Replace
+```
+2. When starting implementation, set task frontmatter to `status: in_progress`
+```
+
+### With
+```
+2. When starting implementation, set task frontmatter to `status: in_progress` + `stage: build` (both required together)
+```
+
+### Target File
+templates/project/AGENTS.md
+
+### Replace
+```
+npm run build && npm run test
+```
+
+### With
+```
+make build && make test
+```
+
+### Target File
+templates/project/.savepoint/router.md
+
+### Replace
+```
+## Manual audit override
+
+If the user explicitly asks you to audit an epic, perform the audit for that epic even if the router has not reached `state: audit-pending` yet.
+
+Persist the audit artifacts before replying:
+
+- Ensure `.savepoint/audit/{E##-epic}/snapshot.md` exists. Create a manual snapshot once if needed.
+- Write the proposal bundle to `.savepoint/audit/{release}/{E##-epic}/proposals.md`.
+- Do not stop at chat-only findings. The filesystem artifact is part of the task output.
+```
+
+### With
+```
+## Manual audit override
+
+If the user explicitly asks you to audit an epic, perform the audit for that epic even if the router has not reached `state: audit-pending` yet.
+
+Persist the audit artifact before replying:
+
+- Write exactly one `.savepoint/releases/{release}/epics/{E##-epic}/E##-Audit.md`.
+- Include `## Main Findings`, `## Code Style Review`, and `## Proposed Changes`.
+- Keep file-specific `### Target File` / `### Replace` / `### With` blocks under `## Proposed Changes`.
+- Do not apply proposals or mark the epic audited until the user says `apply audit`.
+```
+
+### Target File
+templates/project/.savepoint/router.md
+
+### Replace
+```
+**Next action (fresh session only):** 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`:
+```
+
+### With
+```
+**Next action (fresh session only):** Read the epic's `E##-Detail.md`, task files, drift notes, `.savepoint/Design.md`, `AGENTS.md`, and scoped changed files. Write one epic-local audit file to `.savepoint/releases/{release}/epics/{E##-epic}/E##-Audit.md`:
+```
+
+### Target File
+templates/project/.savepoint/router.md
+
+### Replace
+```
+- `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.
+```
+
+### With
+```
+- `## Main Findings` — user-facing AC verification, important drift, and notable risks.
+- `## Code Style Review` — checklist against the 10 AGENTS.md code style rules.
+- `## Proposed Changes` — admin/apply metadata using `### Target File`, `### Replace`, and `### With`.
+```
+
+### Target File
+templates/project/.savepoint/router.md
+
+### Replace
+```
+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.
+```
+
+### With
+```
+After proposals are approved, apply approved proposals to live files, mark the epic `E##-Detail.md` as `status: audited`, update project `Design.md` `last_audited`, refresh `AGENTS.md` Codebase Map if needed, and advance this router to the next epic state.
+```
+
+### Target File
+internal/init/validate.go
+
+### Replace
+```
+var conflictingFiles = []string{
+	"AGENTS.md",
+}
+```
+
+### With
+```
+var conflictingFiles = []string{
+	"AGENTS.md",
+	"agent-skills",
+}
+```
+
+### Target File
+internal/init/scaffold_test.go
+
+### Replace
+```
+func TestScaffold_preservesExistingWithoutForce(t *testing.T) {
+```
+
+### With
+```
+func TestScaffold_overwritesExistingAfterValidation(t *testing.T) {
+```
+
+### Target File
+internal/init/validate_test.go
+
+### Replace
+```
+func TestValidateTarget_conflictingFileWithForce(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "AGENTS.md"), []byte("existing"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	err := ValidateTarget(dir, true)
+	if err != nil {
+		t.Fatalf("ValidateTarget() with --force error = %v, want nil", err)
+	}
+}
+```
+
+### With
+```
+func TestValidateTarget_conflictingFileWithForce(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "AGENTS.md"), []byte("existing"), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	err := ValidateTarget(dir, true)
+	if err != nil {
+		t.Fatalf("ValidateTarget() with --force error = %v, want nil", err)
+	}
+}
+
+func TestValidateTarget_conflictingAgentSkillsDirectory(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.Mkdir(filepath.Join(dir, "agent-skills"), 0755); err != nil {
+		t.Fatal(err)
+	}
+
+	err := ValidateTarget(dir, false)
+	if err == nil {
+		t.Fatal("ValidateTarget() expected error for conflicting agent-skills directory")
+	}
+	if !errors.Is(err, ErrConflict) {
+		t.Fatalf("ValidateTarget() error type = %v, want ErrConflict", err)
+	}
+}
+```
+
+### Target File
+internal/init/write.go
+
+### Replace
+```
+	if err := os.Rename(tmpName, target); err != nil {
+		return fmt.Errorf("rename temp to target: %w", err)
+	}
+```
+
+### With
+```
+	if err := replaceFile(tmpName, target); err != nil {
+		return fmt.Errorf("replace target with temp file: %w", err)
+	}
+```
+
+### Target File
+internal/init/write.go
+
+### Replace
+```
+	return nil
+}
+```
+
+### With
+```
+	return nil
+}
+
+func replaceFile(tmpName, target string) error {
+	if err := os.Rename(tmpName, target); err == nil {
+		return nil
+	}
+
+	if _, statErr := os.Stat(target); statErr != nil {
+		return os.Rename(tmpName, target)
+	}
+
+	backup := target + ".savepoint-bak"
+	_ = os.Remove(backup)
+	if err := os.Rename(target, backup); err != nil {
+		return err
+	}
+	if err := os.Rename(tmpName, target); err != nil {
+		_ = os.Rename(backup, target)
+		return err
+	}
+	return os.Remove(backup)
+}
+```
+
+### Target File
+.savepoint/Design.md
+
+### Replace
+```
+- **Init command** (`savepoint init`) validates, scaffolds, prints prompt, clipboard, optional install (epic E05).
+```
+
+### With
+```
+- **Init command** (`savepoint init`) validates target directories, scaffolds rendered copies of `templates/project/`, prints the rendered magic prompt, attempts best-effort clipboard copy, and optionally runs `npm install` after scaffolding (v1.1 E07).
+```
+
+### Target File
+.savepoint/releases/v1.1/epics/E07-init-command/E07-Detail.md
+
+### Replace
+```
+## Boundaries
+```
+
+### With
+```
+## Implemented As
+
+- `cmd/init.go` owns init argument parsing and delegates execution through `InitRunner`.
+- `main.go` embeds `templates/project/` and `templates/prompts/`, then wires validation, scaffold, prompt rendering, clipboard copy, and optional install in sequence.
+- `internal/init/` owns validation, scaffold interpolation, atomic writes, prompt rendering, clipboard copy, dependency install, and integration tests.
+- Audit found that generated workflow templates need reconciliation with the current epic-local audit workflow before closing.
+
+## Boundaries
+```
+
+### Target File
+.savepoint/releases/v1.1/epics/E07-init-command/tasks/T006-clipboard.md
+
+### Replace
+```
+- [ ] Add `internal/init/clipboard.go`
+- [ ] Implement `CopyToClipboard(text) error`
+- [ ] Detect platform: Windows (clip.exe), macOS (pbcopy), Linux (xclip/xsel)
+- [ ] Fall back gracefully if clipboard tools unavailable
+- [ ] Log skip or failure without failing init
+- [ ] Test clipboard on each platform
+- [ ] Run `make build && make test`
+```
+
+### With
+```
+- [x] Add `internal/init/clipboard.go`
+- [x] Implement `CopyToClipboard(text) ClipboardResult`
+- [x] Detect platform: Windows (clip.exe), macOS (pbcopy), Linux (xclip/xsel)
+- [x] Fall back gracefully if clipboard tools unavailable
+- [x] Log skip or failure without failing init
+- [x] Test clipboard status handling on the current platform
+- [x] Run quality gates (`go test ./internal/init ./cmd`, `go build ./...`, `go test ./...`)
+```

package/.savepoint/releases/v1.1/epics/E07-init-command/E07-Detail.md

@@ -0,0 +1,61 @@
+---
+type: epic-design
+status: audited
+---
+
+# E07: Init Command
+
+## Purpose
+
+Implement `savepoint init`, the first-run command that creates a Savepoint workflow in an empty or compatible project directory and prints the magic prompt the user gives to an AI agent.
+
+## Interface
+
+```bash
+savepoint init [dir]           # scaffold .savepoint/ in target directory
+savepoint init [dir] --force   # overwrite existing
+savepoint init [dir] --install  # run npm install after scaffold
+```
+
+## What this epic adds
+
+- Target directory validation (missing, empty, compatible, already-initialized, conflicting, boundary-error)
+- Scaffold writing from `templates/project/`
+- Project name interpolation
+- Safe handling (refuse conflicts by default, temp-file-plus-rename)
+- Magic prompt output to stdout (from `templates/prompts/magic-prompt.prompt.md`)
+- Best-effort clipboard copy (doesn't fail if unavailable)
+- Optional `--install` flag for dev dependencies
+- Integration tests using temporary directories
+
+## Components
+
+| Module | Purpose |
+|--------|---------|
+| `cmd/init.go` | CLI registration, arg parsing |
+| `internal/init/validate.go` | Target directory checks |
+| `internal/init/scaffold.go` | Template copy, project name interpolation |
+| `internal/init/write.go` | Atomic writes with temp-file-plus-rename |
+| `internal/init/prompt.go` | Magic prompt rendering from template |
+| `internal/init/clipboard.go` | Platform clipboard detection and copy |
+
+## Implemented As
+
+- `cmd/init.go` owns init argument parsing and delegates execution through `InitRunner`.
+- `main.go` embeds `templates/project/` and `templates/prompts/`, then wires validation, scaffold, prompt rendering, clipboard copy, and optional install in sequence.
+- `internal/init/` owns validation, scaffold interpolation, atomic writes, prompt rendering, clipboard copy, dependency install, and integration tests.
+- Audit reconciled generated workflow templates with the current epic-local audit workflow before closing.
+
+## Boundaries
+
+**In scope:**
+- Create `.savepoint/` and root `AGENTS.md`
+- Print the initial agent prompt
+- Avoid overwriting user files unless explicitly allowed by flags
+- Support Windows, macOS, and Linux filesystem behavior
+
+**Out of scope:**
+- Creating epics/tasks interactively
+- Running the board after init
+- Implementing audit or doctor
+- Managing package installation beyond the optional one-shot path

package/.savepoint/releases/v1.1/epics/E07-init-command/tasks/T001-cli-entrypoint.md

@@ -0,0 +1,37 @@
+---
+id: E07-init-command/T001-cli-entrypoint
+status: done
+objective: "Create CLI entrypoint for savepoint init command"
+depends_on: []
+---
+
+# T001: CLI Entrypoint
+
+## Acceptance Criteria
+
+- `savepoint init --help` shows usage: `init [dir] [--force] [--install]`
+- `savepoint init` uses current directory
+- `savepoint init <dir>` uses specified directory
+- `--force` flag allows overwriting existing .savepoint
+- `--install` flag triggers dev dependency install after scaffold
+- Unknown flags show error and exit non-zero
+
+## Implementation Plan
+
+- [x] Add `cmd/init.go` with CLI arg parsing
+- [x] Wire init command into main.go dispatch
+- [x] Implement arg validation (dir, --force, --install)
+- [x] Default to current directory if no dir specified
+- [x] Test `savepoint init --help` output
+- [x] Run quality gates (`make` unavailable; used direct Go build/test)
+
+## Context Log
+
+- Files read: `.savepoint/router.md`, `E07-Detail.md`, this task file, E07 task files T002-T007, `main.go`, `go.mod`, `Makefile`, `internal/board/board.go`, archived E05 init task.
+- Files edited: `cmd/init.go`, `cmd/init_test.go`, `main.go`, this task file, `.savepoint/router.md`.
+- Estimated input tokens: ~18k.
+- Quality gates: `go test ./cmd` passed; `make build` could not run because `make` is not installed; `go build ./...` passed with a Go module cache warning; `go test ./...` passed; `go run . init --help` printed `Usage: init [dir] [--force] [--install]`; `go run . init --bogus` exited non-zero with an unknown flag error.
+
+## Drift Notes
+
+- Added new `cmd/` package for CLI command parsing and dispatch. This module is listed in the E07 epic design but is not yet listed in the AGENTS.md Codebase Map.

package/.savepoint/releases/v1.1/epics/E07-init-command/tasks/T002-target-validation.md

@@ -0,0 +1,28 @@
+---
+id: E07-init-command/T002-target-validation
+status: done
+objective: "Implement target directory validation"
+depends_on: ["E07-init-command/T001-cli-entrypoint"]
+---
+
+# T002: Target Validation
+
+## Acceptance Criteria
+
+- Target missing → error with helpful message
+- Target empty → proceed with init
+- Target has compatible files (package.json, .git, etc.) → proceed
+- Target already has .savepoint → error unless --force
+- Target has conflicting files → error unless --force
+- Boundary errors (permission denied) → clear error message
+
+## Implementation Plan
+
+- [x] Add `internal/init/validate.go`
+- [x] Implement `ValidateTarget(path, force) error`
+- [x] Check directory exists, is writable
+- [x] Check for existing .savepoint (conflict)
+- [x] Check for compatible project files
+- [x] Handle permission errors with clear messages
+- [x] Test all validation scenarios
+- [x] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/E07-init-command/tasks/T003-scaffold-writer.md

@@ -0,0 +1,46 @@
+---
+id: E07-init-command/T003-scaffold-writer
+status: done
+objective: "Implement scaffold writing from templates"
+depends_on: ["E07-init-command/T002-target-validation"]
+---
+
+# T003: Scaffold Writer
+
+## Acceptance Criteria
+
+- Reads templates from `templates/project/` directory
+- Interpolates project name into template files (AGENTS.md, config.yml)
+- Creates parent directories as needed
+- Excludes conflicting files unless --force
+- Copies all .savepoint/ contents
+- Creates root AGENTS.md from template
+
+## Implementation Plan
+
+- [x] Add `internal/init/scaffold.go`
+- [x] Implement `Scaffold(targetDir, projectName, force) error`
+- [x] Load templates from embedded or filesystem path
+- [x] Implement template variable interpolation (project name)
+- [x] Create .savepoint/ directory structure
+- [x] Copy all template files to target
+- [x] Create root AGENTS.md from template
+- [x] Test scaffold output in temp directory
+- [x] Run `make build && make test`
+
+## Context Log
+
+- Files read: router.md, E07-Detail.md, T002-target-validation.md, T001-cli-entrypoint.md, cmd/init.go, cmd/init_test.go, main.go, internal/init/validate.go, internal/init/validate_test.go, Makefile, templates/project/**/*
+- Files created: internal/init/scaffold.go, internal/init/scaffold_test.go
+- Files modified: main.go, T003-scaffold-writer.md
+- Estimated input tokens: ~14k
+- Key decisions:
+  - Used Go `embed.FS` with `fs.Sub` to embed `templates/project/` recursively.
+  - Explicit `//go:embed templates/project/.savepoint` needed because Go's embed excludes dotfile-prefixed directories from recursive directory embedding.
+  - Scaffold accepts `fs.FS` for testability; tested with `testing/fstest.MapFS`.
+  - Init runner in `main.go` validates first (reuses T002), then scaffolds.
+  - Template variables: `{{PROJECT_NAME}}` and `{{RELEASE_NUMBER}}` replaced via `strings.ReplaceAll`.
+
+## Drift Notes
+
+- `cmd/` and `internal/init/` modules were not in AGENTS.md Codebase Map. Updated AGENTS.md to include both.

package/.savepoint/releases/v1.1/epics/E07-init-command/tasks/T004-atomic-writes.md

@@ -0,0 +1,27 @@
+---
+id: E07-init-command/T004-atomic-writes
+status: done
+objective: "Implement atomic file writes with temp-file-plus-rename"
+depends_on: ["E07-init-command/T003-scaffold-writer"]
+---
+
+# T004: Atomic Writes
+
+## Acceptance Criteria
+
+- Writes use temp file + rename pattern
+- Existing files not corrupted on write failure
+- Atomic operation prevents partial writes
+- Handles conflicts gracefully
+- Works on Windows, Linux, macOS
+
+## Implementation Plan
+
+- [x] Add `internal/init/write.go`
+- [x] Implement `AtomicWrite(target, content) error`
+- [x] Create temp file in same directory (atomic on POSIX)
+- [x] Write content to temp file
+- [x] Rename temp to target (atomic on success)
+- [x] Clean up temp file on failure
+- [x] Test atomic write behavior
+- [x] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/E07-init-command/tasks/T005-magic-prompt.md

@@ -0,0 +1,25 @@
+---
+id: E07-init-command/T005-magic-prompt
+status: done
+objective: "Render and output magic prompt to stdout"
+depends_on: ["E07-init-command/T004-atomic-writes"]
+---
+
+# T005: Magic Prompt
+
+## Acceptance Criteria
+
+- Reads `templates/prompts/magic-prompt.prompt.md` template
+- Renders template with project context
+- Outputs rendered prompt to stdout
+- Prompt is copy-paste ready for AI agent
+
+## Implementation Plan
+
+- [x] Add `internal/init/prompt.go`
+- [x] Implement `RenderMagicPrompt(projectName) (string, error)`
+- [x] Load magic-prompt.prompt.md template
+- [x] Interpolate project name into prompt
+- [x] Output to stdout after scaffold completes
+- [x] Test prompt rendering
+- [x] Run `make build && make test`

package/.savepoint/releases/v1.1/epics/E07-init-command/tasks/T006-clipboard.md

@@ -0,0 +1,26 @@
+---
+id: E07-init-command/T006-clipboard
+status: done
+objective: "Implement best-effort clipboard copy"
+depends_on: ["E07-init-command/T005-magic-prompt"]
+---
+
+# T006: Clipboard
+
+## Acceptance Criteria
+
+- Detects platform (Windows/macOS/Linux)
+- Copies magic prompt to clipboard
+- Does NOT fail if clipboard unavailable (best-effort)
+- Returns success/skipped/failed status without throwing on error
+- Works on PowerShell, iTerm2, terminal emulators
+
+## Implementation Plan
+
+- [x] Add `internal/init/clipboard.go`
+- [x] Implement `CopyToClipboard(text) ClipboardResult`
+- [x] Detect platform: Windows (clip.exe), macOS (pbcopy), Linux (xclip/xsel)
+- [x] Fall back gracefully if clipboard tools unavailable
+- [x] Log skip or failure without failing init
+- [x] Test clipboard status handling on the current platform
+- [x] Run quality gates (`go test ./internal/init ./cmd`, `go build ./...`, `go test ./...`)

package/.savepoint/releases/v1.1/epics/E07-init-command/tasks/T007-integration-test.md

@@ -0,0 +1,26 @@
+---
+id: E07-init-command/T007-integration-test
+status: done
+objective: "End-to-end integration test of init flow"
+depends_on: ["E07-init-command/T006-clipboard"]
+---
+
+# T007: Integration Test
+
+## Acceptance Criteria
+
+- Full init pipeline runs end-to-end in temp directory
+- Validates: empty dir, existing project, already-initialized, --force, --install
+- Tests pass on Windows, Linux, macOS
+- Output includes magic prompt to stdout
+
+## Implementation Plan
+
+- [x] Add `internal/init/integration_test.go`
+- [x] Test: init in empty directory
+- [x] Test: init in compatible project
+- [x] Test: init fails without --force on existing .savepoint
+- [x] Test: init with --force overwrites
+- [x] Test: init with --install triggers npm install
+- [x] Verify magic prompt in stdout
+- [x] Run full test suite: `make build && make test`