Pi Deployment & Git-Sync Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Turn wiki-browser from a local-only server into a participant on a shared master — pulling commits to serve them, pushing incorporations back — deployable on a Raspberry Pi.

Architecture: A new in-binary internal/gitsync package owns one mutex that serializes every git mutation (webhook-triggered fetch, incorporation commit + push, startup catch-up, background retry). A new internal/alert package posts Slack notifications on diverged state, sustained sync/push failure, and sustained Agent-job failure. The webhook is a public HMAC-verified route; incorporation is wrapped so a fetch happens before its stale-check and a push after its commit. All git sync is optional — absent a git: config block the server behaves exactly as today (local dev, dev mode).

Tech Stack: Go 1.x, os/exec git, SQLite (existing collab DB), gopkg.in/yaml.v3, standard net/http, the existing internal/walker / internal/index / internal/realtime packages.

Spec: docs/superpowers/specs/2026-05-21-deployment-git-sync-design.html

File Structure

New files:

• internal/alert/alert.go — Notifier interface, Slack notifier, Nop notifier.
• internal/alert/alert_test.go — notifier tests.
• internal/gitsync/git.go — low-level git exec helper.
• internal/gitsync/gitsync.go — Repo, Config, New, State, Status, SyncResult, DivergedError, reconcile, Sync, Push, Incorporate, status tracking + alert edges.
• internal/gitsync/run.go — background maintenance loop (Run, retry push, poll, failure-threshold alert).
• internal/gitsync/helpers_test.go — newTestRepo and git test helpers.
• internal/gitsync/gitsync_test.go — engine tests.
• internal/gitsync/run_test.go — background-loop tests.
• internal/server/handler_webhook.go — handleGitHubWebhook.
• internal/server/handler_webhook_test.go — webhook tests.
• internal/server/handler_sync_status.go — handleSyncStatus.
• internal/server/handler_sync_status_test.go — sync-status tests.

Modified files:

• internal/config/config.go — add Git/Alert blocks, defaults, validation.
• internal/walker/walker.go — add Rescan(); refactor scan() into scanInto().
• internal/server/server.go — Deps.GitSync, Deps.WebhookSecret; register webhook + sync-status routes.
• internal/server/handler_proposals.go — wrap collab.Incorporate in gitSync.Incorporate.
• internal/agent/service.go — ServiceConfig.Alerter; consecutive-failure alert.
• cmd/wiki-browser/main.go — construct alert notifier + gitsync.Repo; startup catch-up; wire Deps; start Run.
• internal/server/templates/shell.html — diverged banner element.
• internal/server/static/chrome.js — poll /api/sync-status.
• internal/server/static/chrome.css — banner styling.
• deploy/wiki-browser.service — User=karn, env, network ordering.
• Makefile — deploy target.
• wiki-browser.example.yaml — git: / alert: blocks.

Decomposition note: gitsync is split across git.go (exec), gitsync.go (engine + state), and run.go (background loop) so each file holds one responsibility and stays readable. The engine is one package because the mutex, the state fields, and the operations are a single cohesive unit.

Spec deviation (carry into review): The spec's Operations section says sync-state transitions are broadcast over the realtime hub. The hub (internal/realtime/hub.go) fans out per source_path and has no global channel; a global broadcast would be a hub redesign. This plan instead drives the diverged banner by polling /api/sync-status (Task 14). The Slack alert (Task 8/12) remains the primary, push-based discoverability mechanism, so this is a minor UI-freshness trade-off, not a functional gap.

Task 1: Config — git: and alert: blocks

Files:

• Modify: internal/config/config.go

• Test: internal/config/config_test.go

• Step 1: Write the failing tests

Add to internal/config/config_test.go. These assume the existing test helpers in that file (writeConfig/temp-file pattern) — if the file builds configs inline, mirror whatever the existing tests do; the assertions below are what matters.

func TestGitBlockDefaultsAndValidation(t *testing.T) {
	dir := t.TempDir()
	secret := filepath.Join(dir, "wh-secret")
	if err := os.WriteFile(secret, []byte("s3cr3t"), 0o600); err != nil {
		t.Fatal(err)
	}
	base := minimalValidConfigYAML(t, dir) // existing helper or inline string
	yaml := base + "\ngit:\n  webhook_secret_file: " + secret + "\n"
	c := mustLoadConfigFromString(t, yaml)

	if c.Git == nil {
		t.Fatal("Git block should be non-nil when present")
	}
	if c.Git.Remote != "origin" {
		t.Errorf("Remote default = %q, want origin", c.Git.Remote)
	}
	if c.Git.Branch != "master" {
		t.Errorf("Branch default = %q, want master", c.Git.Branch)
	}
	if c.Git.PollInterval != 0 {
		t.Errorf("PollInterval default = %v, want 0", c.Git.PollInterval)
	}
}

func TestGitBlockRequiresWebhookSecretFile(t *testing.T) {
	dir := t.TempDir()
	yaml := minimalValidConfigYAML(t, dir) + "\ngit:\n  remote: origin\n"
	if _, err := loadConfigFromString(t, yaml); err == nil {
		t.Fatal("expected error: git.webhook_secret_file required")
	}
}

func TestGitBlockRejectsMissingSecretFile(t *testing.T) {
	dir := t.TempDir()
	yaml := minimalValidConfigYAML(t, dir) +
		"\ngit:\n  webhook_secret_file: " + filepath.Join(dir, "nope") + "\n"
	if _, err := loadConfigFromString(t, yaml); err == nil {
		t.Fatal("expected error: webhook_secret_file does not exist")
	}
}

func TestAlertBlockValidation(t *testing.T) {
	dir := t.TempDir()
	url := filepath.Join(dir, "slack-url")
	if err := os.WriteFile(url, []byte("https://hooks.slack.com/x"), 0o600); err != nil {
		t.Fatal(err)
	}
	yaml := minimalValidConfigYAML(t, dir) +
		"\nalert:\n  slack_webhook_url_file: " + url + "\n"
	c := mustLoadConfigFromString(t, yaml)
	if c.Alert == nil || c.Alert.SlackWebhookURLFile != url {
		t.Fatalf("Alert block not parsed: %+v", c.Alert)
	}
	if c.Alert.FailThreshold != 15*time.Minute {
		t.Errorf("FailThreshold default = %v, want 15m", c.Alert.FailThreshold)
	}
}

func TestNoGitBlockMeansNilGit(t *testing.T) {
	dir := t.TempDir()
	c := mustLoadConfigFromString(t, minimalValidConfigYAML(t, dir))
	if c.Git != nil {
		t.Errorf("Git should be nil when no git: block present")
	}
	if c.Alert != nil {
		t.Errorf("Alert should be nil when no alert: block present")
	}
}

If minimalValidConfigYAML / mustLoadConfigFromString / loadConfigFromString do not already exist in config_test.go, add them as thin wrappers: write the YAML to a temp file and call config.Load. minimalValidConfigYAML must produce a config that already passes validate() (valid root, auth, agent — copy the shape from an existing passing test in that file).

• Step 2: Run tests to verify they fail

Run: go test ./internal/config/ -run 'TestGitBlock|TestAlertBlock|TestNoGitBlock' -v Expected: FAIL — c.Git undefined / compilation error.

• Step 3: Add the structs

In internal/config/config.go, add to the Config struct (after Agent):

	Git   *Git   `yaml:"git"`
	Alert *Alert `yaml:"alert"`

Add the two new types after the Auth type:

// Git configures the gitsync engine. Presence of a `git:` block (Git != nil)
// enables sync; its absence leaves wiki-browser in local-only mode (dev, tests).
type Git struct {
	Remote            string        `yaml:"remote"`
	Branch            string        `yaml:"branch"`
	WebhookSecretFile string        `yaml:"webhook_secret_file"`
	PollInterval      time.Duration `yaml:"poll_interval"`
}

// Alert configures the Slack notifier. Optional and independent of Git: when
// absent, gitsync and the Agent service use a no-op notifier.
type Alert struct {
	SlackWebhookURLFile string        `yaml:"slack_webhook_url_file"`
	FailThreshold       time.Duration `yaml:"fail_threshold"`
}

• Step 4: Add defaults and validation

In applyDefaults(), append:

	if c.Git != nil {
		if c.Git.Remote == "" {
			c.Git.Remote = "origin"
		}
		if c.Git.Branch == "" {
			c.Git.Branch = "master"
		}
	}
	if c.Alert != nil && c.Alert.FailThreshold == 0 {
		c.Alert.FailThreshold = 15 * time.Minute
	}

In validate(), before the final return nil, append:

	if c.Git != nil {
		if c.Git.WebhookSecretFile == "" {
			return fmt.Errorf("git.webhook_secret_file is required when a git: block is present")
		}
		if _, err := os.Stat(c.Git.WebhookSecretFile); err != nil {
			return fmt.Errorf("git.webhook_secret_file %s: %w", c.Git.WebhookSecretFile, err)
		}
		if c.Git.PollInterval < 0 {
			return fmt.Errorf("git.poll_interval must not be negative")
		}
	}
	if c.Alert != nil {
		if c.Alert.SlackWebhookURLFile == "" {
			return fmt.Errorf("alert.slack_webhook_url_file is required when an alert: block is present")
		}
		if _, err := os.Stat(c.Alert.SlackWebhookURLFile); err != nil {
			return fmt.Errorf("alert.slack_webhook_url_file %s: %w", c.Alert.SlackWebhookURLFile, err)
		}
		if c.Alert.FailThreshold < 0 {
			return fmt.Errorf("alert.fail_threshold must not be negative")
		}
	}

• Step 5: Run tests to verify they pass

Run: go test ./internal/config/ -v Expected: PASS (all existing config tests plus the five new ones).

• Step 6: Commit

git add internal/config/config.go internal/config/config_test.go
git commit -m "config: add optional git: and alert: blocks"

Task 2: internal/alert — Slack notifier

Files:

• Create: internal/alert/alert.go

• Test: internal/alert/alert_test.go

• Step 1: Write the failing tests

package alert

import (
	"encoding/json"
	"io"
	"net/http"
	"net/http/httptest"
	"sync"
	"testing"
	"time"
)

func TestSlackSendPostsTextPayload(t *testing.T) {
	var (
		mu   sync.Mutex
		body []byte
	)
	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		b, _ := io.ReadAll(r.Body)
		mu.Lock()
		body = b
		mu.Unlock()
		w.WriteHeader(http.StatusOK)
	}))
	defer srv.Close()

	NewSlack(srv.URL).Send("hello world")

	deadline := time.After(2 * time.Second)
	for {
		mu.Lock()
		got := body
		mu.Unlock()
		if got != nil {
			var payload map[string]string
			if err := json.Unmarshal(got, &payload); err != nil {
				t.Fatalf("payload not JSON: %v", err)
			}
			if payload["text"] != "hello world" {
				t.Fatalf("text = %q, want %q", payload["text"], "hello world")
			}
			return
		}
		select {
		case <-deadline:
			t.Fatal("Slack notifier never POSTed")
		case <-time.After(10 * time.Millisecond):
		}
	}
}

func TestSlackSendDoesNotBlockOnBadURL(t *testing.T) {
	done := make(chan struct{})
	go func() {
		NewSlack("http://127.0.0.1:0/definitely-not-listening").Send("x")
		close(done)
	}()
	select {
	case <-done:
	case <-time.After(time.Second):
		t.Fatal("Send blocked the caller")
	}
}

func TestNopSendIsSafe(t *testing.T) {
	Nop{}.Send("anything") // must not panic
}

• Step 2: Run tests to verify they fail

Run: go test ./internal/alert/ -v Expected: FAIL — package does not exist.

• Step 3: Write the implementation

Create internal/alert/alert.go:

// Package alert delivers operator notifications to a Slack incoming webhook.
// Sends are best-effort and asynchronous — a notification must never block or
// fail the operation that triggered it.
package alert

import (
	"bytes"
	"encoding/json"
	"log/slog"
	"net/http"
	"time"
)

// Notifier is the narrow surface gitsync and the Agent service depend on.
type Notifier interface {
	// Send delivers msg. It must return promptly and never panic.
	Send(msg string)
}

// Nop discards every message. Used when no alert webhook is configured.
type Nop struct{}

func (Nop) Send(string) {}

// Slack posts {"text": msg} to a Slack incoming webhook URL.
type Slack struct {
	url    string
	client *http.Client
}

// NewSlack returns a Slack notifier for the given incoming-webhook URL.
func NewSlack(webhookURL string) *Slack {
	return &Slack{
		url:    webhookURL,
		client: &http.Client{Timeout: 10 * time.Second},
	}
}

// Send POSTs msg asynchronously. A failed delivery is logged and dropped.
func (s *Slack) Send(msg string) {
	go func() {
		body, err := json.Marshal(map[string]string{"text": msg})
		if err != nil {
			slog.Warn("alert: marshal failed", "err", err)
			return
		}
		resp, err := s.client.Post(s.url, "application/json", bytes.NewReader(body))
		if err != nil {
			slog.Warn("alert: slack POST failed", "err", err)
			return
		}
		defer resp.Body.Close()
		if resp.StatusCode >= 300 {
			slog.Warn("alert: slack POST non-2xx", "status", resp.StatusCode)
		}
	}()
}

• Step 4: Run tests to verify they pass

Run: go test ./internal/alert/ -v Expected: PASS.

• Step 5: Commit

git add internal/alert/
git commit -m "alert: add Slack and no-op notifiers"

Task 3: walker.Rescan()

Files:

• Modify: internal/walker/walker.go

• Test: internal/walker/walker_test.go

• Step 1: Write the failing test

Add to internal/walker/walker_test.go:

func TestRescanPicksUpAddedAndRemovedFiles(t *testing.T) {
	root := t.TempDir()
	if err := os.WriteFile(filepath.Join(root, "a.md"), []byte("a"), 0o644); err != nil {
		t.Fatal(err)
	}
	w, err := New(Options{Root: root, Extensions: []string{".md"}})
	if err != nil {
		t.Fatal(err)
	}
	if len(w.Files()) != 1 {
		t.Fatalf("initial Files() = %v, want [a.md]", w.Files())
	}

	// Mutate the tree the way a git fast-forward would: add one, remove one.
	if err := os.WriteFile(filepath.Join(root, "b.md"), []byte("b"), 0o644); err != nil {
		t.Fatal(err)
	}
	if err := os.Remove(filepath.Join(root, "a.md")); err != nil {
		t.Fatal(err)
	}

	if err := w.Rescan(); err != nil {
		t.Fatalf("Rescan: %v", err)
	}
	got := w.Files()
	if len(got) != 1 || got[0] != "b.md" {
		t.Fatalf("after Rescan Files() = %v, want [b.md]", got)
	}
	if w.Has("a.md") {
		t.Error("Has(a.md) should be false after Rescan")
	}
}

• Step 2: Run the test to verify it fails

Run: go test ./internal/walker/ -run TestRescan -v Expected: FAIL — w.Rescan undefined.

• Step 3: Refactor scan and add Rescan

In internal/walker/walker.go, replace the scan method so the walk logic targets a caller-supplied map:

func (w *Walker) scan() error {
	files := make(map[string]struct{})
	if err := w.scanInto(files); err != nil {
		return err
	}
	w.files = files
	return nil
}

// scanInto walks the tree and records every matching repo-relative path into m.
func (w *Walker) scanInto(m map[string]struct{}) error {
	return filepath.WalkDir(w.opts.Root, func(p string, d fs.DirEntry, err error) error {
		if err != nil {
			if d != nil && d.IsDir() && (errors.Is(err, fs.ErrPermission) || errors.Is(err, fs.ErrNotExist)) {
				slog.Warn("walker: skipping unreadable dir", "path", p, "err", err)
				return fs.SkipDir
			}
			return err
		}
		rel, rerr := filepath.Rel(w.opts.Root, p)
		if rerr != nil {
			return rerr
		}
		rel = filepath.ToSlash(rel)
		if rel == "." {
			return nil
		}
		if w.exclude.Match(rel) {
			if d.IsDir() {
				return fs.SkipDir
			}
			return nil
		}
		if d.IsDir() {
			return nil
		}
		if !w.matchesExt(rel) {
			return nil
		}
		m[rel] = struct{}{}
		return nil
	})
}

// Rescan re-walks the tree and atomically replaces the file set. Used after a
// git operation changes many files at once, so the served view is correct
// without depending on fsnotify delivery timing.
func (w *Walker) Rescan() error {
	fresh := make(map[string]struct{})
	if err := w.scanInto(fresh); err != nil {
		return err
	}
	w.mu.Lock()
	w.files = fresh
	w.mu.Unlock()
	return nil
}

Note: New already calls w.scan(); that path is preserved. scan() keeps writing w.files directly (it runs before any concurrency, inside New). Rescan swaps under the lock.

• Step 4: Run tests to verify they pass

Run: go test ./internal/walker/ -v Expected: PASS (all existing walker tests plus TestRescan...).

• Step 5: Commit

git add internal/walker/walker.go internal/walker/walker_test.go
git commit -m "walker: add Rescan for deterministic post-git-op refresh"

Task 4: gitsync — git exec helper + test scaffolding + New

Files:

• Create: internal/gitsync/git.go

• Create: internal/gitsync/gitsync.go (partial — Config, Repo, New only)

• Create: internal/gitsync/helpers_test.go

• Test: internal/gitsync/gitsync_test.go

• Step 1: Write the test helpers

Create internal/gitsync/helpers_test.go:

package gitsync

import (
	"os"
	"os/exec"
	"path/filepath"
	"strings"
	"testing"
)

// mustGit runs git in dir and fails the test on error.
func mustGit(t *testing.T, dir string, args ...string) string {
	t.Helper()
	cmd := exec.Command("git", append([]string{"-C", dir}, args...)...)
	cmd.Env = append(os.Environ(),
		"GIT_AUTHOR_NAME=test", "GIT_AUTHOR_EMAIL=test@test",
		"GIT_COMMITTER_NAME=test", "GIT_COMMITTER_EMAIL=test@test",
	)
	out, err := cmd.CombinedOutput()
	if err != nil {
		t.Fatalf("git %s: %v\n%s", strings.Join(args, " "), err, out)
	}
	return strings.TrimSpace(string(out))
}

// newTestRepo builds a bare origin plus a working clone checked out on master,
// with one initial commit pushed. Returns the working-tree path and the origin
// path.
func newTestRepo(t *testing.T) (root, origin string) {
	t.Helper()
	dir := t.TempDir()
	origin = filepath.Join(dir, "origin.git")
	root = filepath.Join(dir, "work")
	mustGit(t, dir, "init", "--bare", "-b", "master", origin)
	mustGit(t, dir, "clone", origin, root)
	mustGit(t, root, "config", "user.name", "test")
	mustGit(t, root, "config", "user.email", "test@test")
	if err := os.WriteFile(filepath.Join(root, "README.md"), []byte("hello\n"), 0o644); err != nil {
		t.Fatal(err)
	}
	mustGit(t, root, "add", "README.md")
	mustGit(t, root, "commit", "-m", "init")
	mustGit(t, root, "push", "-u", "origin", "master")
	return root, origin
}

// commitInOrigin makes a commit directly on origin (simulating a teammate's
// push) by cloning origin to a scratch dir, committing, and pushing.
func commitInOrigin(t *testing.T, origin, relPath, content string) {
	t.Helper()
	scratch := t.TempDir()
	mustGit(t, scratch, "clone", origin, "clone")
	clone := filepath.Join(scratch, "clone")
	mustGit(t, clone, "config", "user.name", "test")
	mustGit(t, clone, "config", "user.email", "test@test")
	full := filepath.Join(clone, relPath)
	if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
		t.Fatal(err)
	}
	if err := os.WriteFile(full, []byte(content), 0o644); err != nil {
		t.Fatal(err)
	}
	mustGit(t, clone, "add", relPath)
	mustGit(t, clone, "commit", "-m", "origin: "+relPath)
	mustGit(t, clone, "push", "origin", "master")
}

func defaultConfig(root string) Config {
	return Config{
		Root: root, Remote: "origin", Branch: "master",
		FailThreshold: time.Minute,
	}
}

(The time import in defaultConfig requires "time" in the helper file's import block — add it.)

• Step 2: Write the failing New tests

Create internal/gitsync/gitsync_test.go:

package gitsync

import (
	"os"
	"path/filepath"
	"testing"
	"time"

	"github.com/getorcha/wiki-browser/internal/alert"
)

func TestNewValidatesRepo(t *testing.T) {
	root, _ := newTestRepo(t)
	r, err := New(defaultConfig(root), alert.Nop{}, "https://wiki.example.com")
	if err != nil {
		t.Fatalf("New: %v", err)
	}
	if got := r.Status().State; got != StateSynced {
		t.Errorf("initial state = %q, want synced", got)
	}
	if r.Status().Head == "" {
		t.Error("initial Head is empty")
	}
}

func TestNewRejectsNonRepo(t *testing.T) {
	if _, err := New(defaultConfig(t.TempDir()), alert.Nop{}, ""); err == nil {
		t.Fatal("expected error for non-git directory")
	}
}

func TestNewRejectsWrongBranch(t *testing.T) {
	root, _ := newTestRepo(t)
	mustGit(t, root, "checkout", "-b", "feature")
	if _, err := New(defaultConfig(root), alert.Nop{}, ""); err == nil {
		t.Fatal("expected error: HEAD not on configured branch")
	}
}

• Step 3: Run tests to verify they fail

Run: go test ./internal/gitsync/ -run TestNew -v Expected: FAIL — package incomplete.

• Step 4: Write git.go

package gitsync

import (
	"fmt"
	"os/exec"
	"strings"
)

// git runs a git subcommand in repoRoot and returns its trimmed combined
// output. On failure the error includes the command and output for diagnosis.
func git(repoRoot string, args ...string) (string, error) {
	cmd := exec.Command("git", append([]string{"-C", repoRoot}, args...)...)
	out, err := cmd.CombinedOutput()
	if err != nil {
		return "", fmt.Errorf("git %s: %w\n%s", strings.Join(args, " "), err, string(out))
	}
	return strings.TrimSpace(string(out)), nil
}

• Step 5: Write gitsync.go (Config, Repo, New, Status)

// Package gitsync keeps a working clone in step with a shared remote branch:
// it fast-forwards in commits that land upstream and pushes the commits the
// wiki-browser process makes locally. One mutex serializes every git mutation.
package gitsync

import (
	"fmt"
	"strings"
	"sync"
	"time"

	"github.com/getorcha/wiki-browser/internal/alert"
)

// Config is the fully-specified input to New.
type Config struct {
	Root          string        // working-tree path (cfg.Root)
	Remote        string        // e.g. "origin"
	Branch        string        // e.g. "master"
	PollInterval  time.Duration // 0 disables the safety-net poll
	FailThreshold time.Duration // sustained-failure alert threshold
	Extensions    []string      // file extensions worth reindexing (e.g. .md .html)
}

// State is the coarse sync status surfaced to operators.
type State string

const (
	StateSynced      State = "synced"
	StateSyncing     State = "syncing"
	StatePushPending State = "push-pending"
	StateDiverged    State = "diverged"
)

// Status is the JSON-serializable snapshot returned by /api/sync-status.
type Status struct {
	State      State     `json:"state"`
	Head       string    `json:"head"`
	Ahead      int       `json:"ahead"`
	LastSyncAt time.Time `json:"last_sync_at"`
	LastError  string    `json:"last_error,omitempty"`
}

// SyncResult describes what a single reconcile changed.
type SyncResult struct {
	OldHead      string
	NewHead      string
	ChangedPaths []string // repo-relative, filtered to Config.Extensions
	Rebased      bool
}

// Repo is the git-sync engine for one clone.
type Repo struct {
	cfg       Config
	notifier  alert.Notifier
	publicURL string // public_base_url, for diverged-alert doc links

	gitMu sync.Mutex // serializes ALL git mutations

	onSync func(SyncResult) // runtime reindex hook; set via SetOnSync

	syncReq chan struct{} // coalesced sync requests from the webhook

	stMu         sync.Mutex // guards every field below
	state        State
	head         string
	lastSyncAt   time.Time
	lastErr      string
	ahead        int
	failingSince time.Time // zero ⇒ not currently failing
	failAlerted  bool      // threshold alert already sent for this failure run
}

// New validates the clone and returns an engine in the synced state.
func New(cfg Config, notifier alert.Notifier, publicBaseURL string) (*Repo, error) {
	if cfg.Root == "" || cfg.Remote == "" || cfg.Branch == "" {
		return nil, fmt.Errorf("gitsync: Root, Remote and Branch are required")
	}
	if notifier == nil {
		notifier = alert.Nop{}
	}
	if out, err := git(cfg.Root, "rev-parse", "--is-inside-work-tree"); err != nil || out != "true" {
		return nil, fmt.Errorf("gitsync: %s is not a git work tree", cfg.Root)
	}
	branch, err := git(cfg.Root, "symbolic-ref", "--short", "HEAD")
	if err != nil {
		return nil, fmt.Errorf("gitsync: read current branch: %w", err)
	}
	if branch != cfg.Branch {
		return nil, fmt.Errorf("gitsync: HEAD is on %q, want %q", branch, cfg.Branch)
	}
	if _, err := git(cfg.Root, "remote", "get-url", cfg.Remote); err != nil {
		return nil, fmt.Errorf("gitsync: remote %q: %w", cfg.Remote, err)
	}
	head, err := git(cfg.Root, "rev-parse", "HEAD")
	if err != nil {
		return nil, fmt.Errorf("gitsync: rev-parse HEAD: %w", err)
	}
	return &Repo{
		cfg:       cfg,
		notifier:  notifier,
		publicURL: strings.TrimRight(publicBaseURL, "/"),
		syncReq:   make(chan struct{}, 1),
		state:     StateSynced,
		head:      head,
	}, nil
}

// Branch returns the configured branch name.
func (r *Repo) Branch() string { return r.cfg.Branch }

// SetOnSync registers the callback invoked after a reconcile changes files.
// Set once, before Run starts.
func (r *Repo) SetOnSync(fn func(SyncResult)) { r.onSync = fn }

// Status returns a snapshot of the current sync status.
func (r *Repo) Status() Status {
	r.stMu.Lock()
	defer r.stMu.Unlock()
	return Status{
		State:      r.state,
		Head:       r.head,
		Ahead:      r.ahead,
		LastSyncAt: r.lastSyncAt,
		LastError:  r.lastErr,
	}
}

• Step 6: Run tests to verify they pass

Run: go test ./internal/gitsync/ -run TestNew -v Expected: PASS.

• Step 7: Commit

git add internal/gitsync/
git commit -m "gitsync: repo validation, config, status types"

Task 5: gitsync — reconcile and DivergedError

Files:

• Modify: internal/gitsync/gitsync.go

• Test: internal/gitsync/gitsync_test.go

• Step 1: Write the failing tests

Add to internal/gitsync/gitsync_test.go:

func TestReconcileFastForwards(t *testing.T) {
	root, origin := newTestRepo(t)
	r, _ := New(Config{Root: root, Remote: "origin", Branch: "master",
		FailThreshold: time.Minute, Extensions: []string{".md"}}, alert.Nop{}, "")
	commitInOrigin(t, origin, "docs/new.md", "fresh\n")

	res, err := r.reconcileLocked()
	if err != nil {
		t.Fatalf("reconcileLocked: %v", err)
	}
	if res.OldHead == res.NewHead {
		t.Fatal("HEAD did not advance")
	}
	if len(res.ChangedPaths) != 1 || res.ChangedPaths[0] != "docs/new.md" {
		t.Fatalf("ChangedPaths = %v, want [docs/new.md]", res.ChangedPaths)
	}
	if _, err := os.Stat(filepath.Join(root, "docs/new.md")); err != nil {
		t.Errorf("file not on disk after ff: %v", err)
	}
}

func TestReconcileFiltersChangedPathsByExtension(t *testing.T) {
	root, origin := newTestRepo(t)
	r, _ := New(Config{Root: root, Remote: "origin", Branch: "master",
		FailThreshold: time.Minute, Extensions: []string{".md"}}, alert.Nop{}, "")
	commitInOrigin(t, origin, "main.go", "package x\n")

	res, err := r.reconcileLocked()
	if err != nil {
		t.Fatalf("reconcileLocked: %v", err)
	}
	if len(res.ChangedPaths) != 0 {
		t.Fatalf("ChangedPaths = %v, want [] (non-.md filtered out)", res.ChangedPaths)
	}
}

func TestReconcileRebasesLocalCommits(t *testing.T) {
	root, origin := newTestRepo(t)
	r, _ := New(defaultConfig(root), alert.Nop{}, "")
	// Local commit not yet pushed.
	if err := os.WriteFile(filepath.Join(root, "local.md"), []byte("local\n"), 0o644); err != nil {
		t.Fatal(err)
	}
	mustGit(t, root, "add", "local.md")
	mustGit(t, root, "commit", "-m", "local work")
	// Divergent commit upstream, on a different file.
	commitInOrigin(t, origin, "remote.md", "remote\n")

	res, err := r.reconcileLocked()
	if err != nil {
		t.Fatalf("reconcileLocked: %v", err)
	}
	if !res.Rebased {
		t.Error("expected Rebased=true")
	}
	// Local commit must survive the rebase.
	if _, err := os.Stat(filepath.Join(root, "local.md")); err != nil {
		t.Errorf("local commit lost after rebase: %v", err)
	}
}

func TestReconcileReportsDivergedOnConflict(t *testing.T) {
	root, origin := newTestRepo(t)
	r, _ := New(defaultConfig(root), alert.Nop{}, "")
	// Both sides edit README.md → guaranteed rebase conflict.
	if err := os.WriteFile(filepath.Join(root, "README.md"), []byte("local edit\n"), 0o644); err != nil {
		t.Fatal(err)
	}
	mustGit(t, root, "add", "README.md")
	mustGit(t, root, "commit", "-m", "local readme")
	commitInOrigin(t, origin, "README.md", "remote edit\n")

	_, err := r.reconcileLocked()
	var de *DivergedError
	if !errorAs(err, &de) {
		t.Fatalf("err = %v, want *DivergedError", err)
	}
	if len(de.Paths) == 0 {
		t.Error("DivergedError.Paths is empty")
	}
	// Rebase must have been aborted — tree is clean, local commit intact.
	if out := mustGit(t, root, "status", "--porcelain"); out != "" {
		t.Errorf("tree not clean after abort: %q", out)
	}
}

Add a tiny errorAs helper to the test file (or use errors.As directly — import "errors"):

func errorAs(err error, target any) bool { return errors.As(err, target) }

• Step 2: Run tests to verify they fail

Run: go test ./internal/gitsync/ -run TestReconcile -v Expected: FAIL — reconcileLocked / DivergedError undefined.

• Step 3: Implement DivergedError and reconcileLocked

Add to internal/gitsync/gitsync.go:

// DivergedError reports that local and remote both changed the same file(s),
// so a rebase could not complete automatically. The local commit is preserved;
// a human must resolve the merge on the host.
type DivergedError struct {
	Paths []string
}

func (e *DivergedError) Error() string {
	return "gitsync: diverged on " + strings.Join(e.Paths, ", ")
}

// reconcileLocked fetches the remote branch and brings the local branch in
// line: fast-forward when possible, rebase when local commits exist, and a
// *DivergedError when the rebase cannot complete. The caller MUST hold gitMu.
//
// On a successful change it invokes the onSync callback (if set) so the served
// view is refreshed deterministically.
func (r *Repo) reconcileLocked() (SyncResult, error) {
	remoteRef := r.cfg.Remote + "/" + r.cfg.Branch

	oldHead, err := git(r.cfg.Root, "rev-parse", "HEAD")
	if err != nil {
		return SyncResult{}, err
	}
	if _, err := git(r.cfg.Root, "fetch", r.cfg.Remote, r.cfg.Branch); err != nil {
		return SyncResult{}, err
	}
	behind, err := countCommits(r.cfg.Root, "HEAD.."+remoteRef)
	if err != nil {
		return SyncResult{}, err
	}
	ahead, err := countCommits(r.cfg.Root, remoteRef+"..HEAD")
	if err != nil {
		return SyncResult{}, err
	}

	res := SyncResult{OldHead: oldHead}
	if behind > 0 {
		if ahead == 0 {
			if _, err := git(r.cfg.Root, "merge", "--ff-only", remoteRef); err != nil {
				return SyncResult{}, err
			}
		} else {
			if _, err := git(r.cfg.Root, "rebase", remoteRef); err != nil {
				conflicted, _ := git(r.cfg.Root, "diff", "--name-only", "--diff-filter=U")
				_, _ = git(r.cfg.Root, "rebase", "--abort")
				paths := splitLines(conflicted)
				if len(paths) == 0 {
					paths = []string{"(unknown)"}
				}
				return SyncResult{}, &DivergedError{Paths: paths}
			}
			res.Rebased = true
		}
	}

	newHead, err := git(r.cfg.Root, "rev-parse", "HEAD")
	if err != nil {
		return SyncResult{}, err
	}
	res.NewHead = newHead
	if oldHead != newHead {
		raw, err := git(r.cfg.Root, "diff", "--name-only", oldHead, newHead)
		if err != nil {
			return SyncResult{}, err
		}
		res.ChangedPaths = r.filterByExtension(splitLines(raw))
		if r.onSync != nil {
			r.onSync(res)
		}
	}
	return res, nil
}

// countCommits returns the number of commits in the given rev range.
func countCommits(root, revRange string) (int, error) {
	out, err := git(root, "rev-list", "--count", revRange)
	if err != nil {
		return 0, err
	}
	n := 0
	if _, err := fmt.Sscanf(out, "%d", &n); err != nil {
		return 0, fmt.Errorf("gitsync: parse commit count %q: %w", out, err)
	}
	return n, nil
}

// filterByExtension keeps only paths whose extension is in Config.Extensions.
// An empty Extensions list keeps everything.
func (r *Repo) filterByExtension(paths []string) []string {
	if len(r.cfg.Extensions) == 0 {
		return paths
	}
	out := make([]string, 0, len(paths))
	for _, p := range paths {
		for _, ext := range r.cfg.Extensions {
			if strings.HasSuffix(strings.ToLower(p), strings.ToLower(ext)) {
				out = append(out, p)
				break
			}
		}
	}
	return out
}

// splitLines splits git output into non-empty trimmed lines.
func splitLines(s string) []string {
	var out []string
	for _, ln := range strings.Split(s, "\n") {
		if ln = strings.TrimSpace(ln); ln != "" {
			out = append(out, ln)
		}
	}
	return out
}

• Step 4: Run tests to verify they pass

Run: go test ./internal/gitsync/ -run TestReconcile -v Expected: PASS.

• Step 5: Commit

git add internal/gitsync/gitsync.go internal/gitsync/gitsync_test.go
git commit -m "gitsync: reconcile (fetch, ff/rebase, diverged detection)"

Task 6: gitsync — state transitions, alerts, and Sync

Files:

• Modify: internal/gitsync/gitsync.go

• Test: internal/gitsync/gitsync_test.go

• Step 1: Write the failing tests

Add to internal/gitsync/gitsync_test.go. Use a recording notifier:

type recordingNotifier struct {
	mu   sync.Mutex
	msgs []string
}

func (n *recordingNotifier) Send(msg string) {
	n.mu.Lock()
	defer n.mu.Unlock()
	n.msgs = append(n.msgs, msg)
}

func (n *recordingNotifier) all() []string {
	n.mu.Lock()
	defer n.mu.Unlock()
	return append([]string(nil), n.msgs...)
}

func TestSyncFastForwardUpdatesStatus(t *testing.T) {
	root, origin := newTestRepo(t)
	r, _ := New(Config{Root: root, Remote: "origin", Branch: "master",
		FailThreshold: time.Minute, Extensions: []string{".md"}}, alert.Nop{}, "")
	commitInOrigin(t, origin, "docs/x.md", "x\n")

	res, err := r.Sync(context.Background())
	if err != nil {
		t.Fatalf("Sync: %v", err)
	}
	if len(res.ChangedPaths) != 1 {
		t.Errorf("ChangedPaths = %v", res.ChangedPaths)
	}
	st := r.Status()
	if st.State != StateSynced {
		t.Errorf("state = %q, want synced", st.State)
	}
	if st.LastSyncAt.IsZero() {
		t.Error("LastSyncAt not set")
	}
}

func TestSyncInvokesOnSyncCallback(t *testing.T) {
	root, origin := newTestRepo(t)
	r, _ := New(Config{Root: root, Remote: "origin", Branch: "master",
		FailThreshold: time.Minute, Extensions: []string{".md"}}, alert.Nop{}, "")
	var got []string
	r.SetOnSync(func(res SyncResult) { got = res.ChangedPaths })
	commitInOrigin(t, origin, "docs/cb.md", "cb\n")

	if _, err := r.Sync(context.Background()); err != nil {
		t.Fatalf("Sync: %v", err)
	}
	if len(got) != 1 || got[0] != "docs/cb.md" {
		t.Fatalf("onSync got %v, want [docs/cb.md]", got)
	}
}

func TestSyncDivergedSetsStateAndAlertsWithDocLink(t *testing.T) {
	root, origin := newTestRepo(t)
	n := &recordingNotifier{}
	r, _ := New(defaultConfig(root), n, "https://wiki.example.com")
	if err := os.WriteFile(filepath.Join(root, "README.md"), []byte("local\n"), 0o644); err != nil {
		t.Fatal(err)
	}
	mustGit(t, root, "add", "README.md")
	mustGit(t, root, "commit", "-m", "local")
	commitInOrigin(t, origin, "README.md", "remote\n")

	_, err := r.Sync(context.Background())
	if err == nil {
		t.Fatal("expected diverged error")
	}
	if r.Status().State != StateDiverged {
		t.Errorf("state = %q, want diverged", r.Status().State)
	}
	msgs := n.all()
	if len(msgs) != 1 {
		t.Fatalf("alerts = %v, want exactly one", msgs)
	}
	if !strings.Contains(msgs[0], "https://wiki.example.com/doc/README.md") {
		t.Errorf("alert missing doc link: %q", msgs[0])
	}
}

(Imports needed in the test file: context, strings, sync, time, errors, os, path/filepath, testing, and internal/alert.)

• Step 2: Run tests to verify they fail

Run: go test ./internal/gitsync/ -run TestSync -v Expected: FAIL — Sync undefined.

• Step 3: Implement state helpers and Sync

Add to internal/gitsync/gitsync.go:

import "context" // add to the existing import block

// setState records a new coarse state and fires the edge-triggered alerts:
// entering diverged alerts immediately; returning to synced from a bad state
// fires a single recovery alert. Caller must NOT hold stMu.
func (r *Repo) setState(s State, divergedPaths []string) {
	r.stMu.Lock()
	old := r.state
	r.state = s
	wasAlerted := r.failAlerted
	r.stMu.Unlock()

	switch {
	case s == StateDiverged && old != StateDiverged:
		r.notifier.Send("wiki-browser: git sync DIVERGED — manual resolution needed on the host.\n" +
			r.alertContext("diverged") +
			r.docLinks(divergedPaths))
	case s == StateSynced && (old == StateDiverged || wasAlerted):
		r.notifier.Send("wiki-browser: git sync RECOVERED — back in sync.\n" +
			r.alertContext("recovered"))
		r.stMu.Lock()
		r.failAlerted = false
		r.stMu.Unlock()
	}
}

// docLinks renders one public-base-URL deep link per path.
func (r *Repo) docLinks(paths []string) string {
	var b strings.Builder
	for _, p := range paths {
		if r.publicURL != "" {
			fmt.Fprintf(&b, "%s/doc/%s\n", r.publicURL, p)
		} else {
			fmt.Fprintf(&b, "%s\n", p)
		}
	}
	return b.String()
}

// alertContext returns the operator context every alert must carry.
func (r *Repo) alertContext(condition string) string {
	st := r.Status()
	lastErr := st.LastError
	if lastErr == "" {
		lastErr = "(none)"
	}
	head := st.Head
	if head == "" {
		head = "(unknown)"
	}
	return fmt.Sprintf("condition: %s\nstate: %s\nhead: %s\nlast_error: %s\n",
		condition, st.State, head, lastErr)
}

// recordOK clears failure tracking and refreshes head/ahead/lastSyncAt.
func (r *Repo) recordOK() {
	head, _ := git(r.cfg.Root, "rev-parse", "HEAD")
	ahead, _ := countCommits(r.cfg.Root, r.cfg.Remote+"/"+r.cfg.Branch+"..HEAD")
	r.stMu.Lock()
	r.head = head
	r.ahead = ahead
	r.lastSyncAt = time.Now()
	r.lastErr = ""
	r.failingSince = time.Time{}
	r.stMu.Unlock()
}

// recordFailure stamps failingSince (once per failure run) and the last error.
func (r *Repo) recordFailure(err error) {
	head, _ := git(r.cfg.Root, "rev-parse", "HEAD")
	r.stMu.Lock()
	if r.failingSince.IsZero() {
		r.failingSince = time.Now()
	}
	if head != "" {
		r.head = head
	}
	r.lastErr = err.Error()
	r.stMu.Unlock()
}

// Sync fetches and reconciles under the git lock. Webhook- and startup-driven.
func (r *Repo) Sync(ctx context.Context) (SyncResult, error) {
	_ = ctx // reserved for future cancellation; git calls are short
	r.gitMu.Lock()
	defer r.gitMu.Unlock()

	r.setState(StateSyncing, nil)
	res, err := r.reconcileLocked()
	if err != nil {
		var de *DivergedError
		if errors.As(err, &de) {
			r.recordFailure(err)
			r.setState(StateDiverged, de.Paths)
			return SyncResult{}, err
		}
		r.recordFailure(err)
		r.setState(StatePushPending, nil) // unknown push state; retried by Run
		return SyncResult{}, err
	}
	r.recordOK()
	if r.statusAhead() > 0 {
		r.setState(StatePushPending, nil)
	} else {
		r.setState(StateSynced, nil)
	}
	return res, nil
}

// statusAhead returns the cached ahead count.
func (r *Repo) statusAhead() int {
	r.stMu.Lock()
	defer r.stMu.Unlock()
	return r.ahead
}

Add "errors" to the import block if not present.

• Step 4: Run tests to verify they pass

Run: go test ./internal/gitsync/ -run TestSync -v Expected: PASS.

• Step 5: Commit

git add internal/gitsync/gitsync.go internal/gitsync/gitsync_test.go
git commit -m "gitsync: Sync, state transitions, diverged alerting"

Task 7: gitsync — Push and Incorporate

Files:

• Modify: internal/gitsync/gitsync.go

• Test: internal/gitsync/gitsync_test.go

• Step 1: Write the failing tests

func TestPushSendsLocalCommitToOrigin(t *testing.T) {
	root, origin := newTestRepo(t)
	r, _ := New(defaultConfig(root), alert.Nop{}, "")
	if err := os.WriteFile(filepath.Join(root, "p.md"), []byte("p\n"), 0o644); err != nil {
		t.Fatal(err)
	}
	mustGit(t, root, "add", "p.md")
	mustGit(t, root, "commit", "-m", "local")

	if err := r.Push(context.Background()); err != nil {
		t.Fatalf("Push: %v", err)
	}
	if r.Status().State != StateSynced {
		t.Errorf("state = %q, want synced", r.Status().State)
	}
	// origin now has the commit.
	scratch := t.TempDir()
	mustGit(t, scratch, "clone", origin, "verify")
	if _, err := os.Stat(filepath.Join(scratch, "verify", "p.md")); err != nil {
		t.Errorf("commit not on origin: %v", err)
	}
}

func TestPushRebasesWhenOriginMoved(t *testing.T) {
	root, origin := newTestRepo(t)
	r, _ := New(defaultConfig(root), alert.Nop{}, "")
	if err := os.WriteFile(filepath.Join(root, "mine.md"), []byte("mine\n"), 0o644); err != nil {
		t.Fatal(err)
	}
	mustGit(t, root, "add", "mine.md")
	mustGit(t, root, "commit", "-m", "mine")
	commitInOrigin(t, origin, "theirs.md", "theirs\n")

	if err := r.Push(context.Background()); err != nil {
		t.Fatalf("Push: %v", err)
	}
	if r.Status().State != StateSynced {
		t.Errorf("state = %q, want synced", r.Status().State)
	}
}

func TestIncorporateReconcilesThenRunsFnThenPushes(t *testing.T) {
	root, origin := newTestRepo(t)
	r, _ := New(defaultConfig(root), alert.Nop{}, "")
	commitInOrigin(t, origin, "upstream.md", "up\n")

	sawUpstream := false
	sha, err := r.Incorporate(context.Background(), func() (string, error) {
		// fn runs AFTER reconcile — the upstream file must already be present.
		_, statErr := os.Stat(filepath.Join(root, "upstream.md"))
		sawUpstream = statErr == nil
		if err := os.WriteFile(filepath.Join(root, "inc.md"), []byte("inc\n"), 0o644); err != nil {
			return "", err
		}
		mustGit(t, root, "add", "inc.md")
		mustGit(t, root, "commit", "-m", "incorporated")
		out := mustGit(t, root, "rev-parse", "HEAD")
		return out, nil
	})
	if err != nil {
		t.Fatalf("Incorporate: %v", err)
	}
	if !sawUpstream {
		t.Error("fn ran before reconcile — upstream file was not present")
	}
	if sha == "" {
		t.Error("Incorporate returned empty sha")
	}
	scratch := t.TempDir()
	mustGit(t, scratch, "clone", origin, "v")
	if _, err := os.Stat(filepath.Join(scratch, "v", "inc.md")); err != nil {
		t.Errorf("incorporation not pushed to origin: %v", err)
	}
}

func TestIncorporateReturnsFnError(t *testing.T) {
	root, _ := newTestRepo(t)
	r, _ := New(defaultConfig(root), alert.Nop{}, "")
	want := errors.New("stale proposal")
	_, err := r.Incorporate(context.Background(), func() (string, error) {
		return "", want
	})
	if !errors.Is(err, want) {
		t.Fatalf("err = %v, want %v", err, want)
	}
}

func TestIncorporatePreReconcileFailureDoesNotRunFn(t *testing.T) {
	root, _ := newTestRepo(t)
	// Break fetch before constructing the Repo. remote get-url still succeeds,
	// but the mandatory pre-incorporation reconcile will fail.
	mustGit(t, root, "remote", "set-url", "origin", "file:///nonexistent/repo.git")
	r, _ := New(defaultConfig(root), alert.Nop{}, "")

	ran := false
	_, err := r.Incorporate(context.Background(), func() (string, error) {
		ran = true
		return "should-not-happen", nil
	})
	if err == nil {
		t.Fatal("expected pre-reconcile error")
	}
	if ran {
		t.Fatal("Incorporate ran fn after failed pre-reconcile")
	}
	if got := r.Status().State; got != StatePushPending {
		t.Fatalf("state = %q, want push-pending", got)
	}
}