feat(schedule): add Temporal schedule for periodic scanning (#4)

## Summary

- Adds Temporal Schedule API support so the OrchestratorWorkflow runs
automatically on a configurable cron (default: daily at 06:00 UTC per
the design doc)
- Schedule manager uses a create-or-update pattern to handle server
restarts gracefully (if schedule already exists, updates it if cron
changed)
- Disabled by default via `SCHEDULE_ENABLED=false` for backwards
compatibility
- Wires `SCHEDULE_*` env vars through `docker-compose.yaml` so the
feature can be toggled for local end-to-end testing

## Configuration

| Env Var | Default | Purpose |
|---------|---------|---------|
| `SCHEDULE_ENABLED` | `false` | Opt-in to scheduled scanning |
| `SCHEDULE_CRON` | `0 6 * * *` | Cron expression (daily at 06:00 UTC) |
| `SCHEDULE_ID` | `version-guard-scan` | Stable schedule ID for
idempotent restarts |
| `SCHEDULE_JITTER` | `5m` | Random jitter to prevent thundering herd |

## Changes

**New:**
- `pkg/schedule/schedule.go` — Schedule manager with create-or-update
logic
- `pkg/schedule/schedule_test.go` — 8 unit tests covering all paths

**Modified:**
- `cmd/server/main.go` — Config fields, schedule wiring with graceful
failure
- `pkg/workflow/orchestrator/workflow.go` — ScanID fallback from
workflow execution ID for scheduled runs
- `docker-compose.yaml` — `SCHEDULE_*` env var passthrough

## Bug fixed during review

Initial implementation mutated only `CronExpressions` on the update
path. Temporal parses `CronExpressions` into structured `Calendars`
server-side on create, so subsequent describes return the cron inside
`Calendars` with `CronExpressions` empty. Mutating only
`CronExpressions` left the stale calendar in place, causing the schedule
to fire on both the old and new crons after every restart with a changed
cron.

Fixed by replacing the entire `Spec` on update. Regression test
`TestEnsureSchedule_Update_ReplacesStaleCalendars` simulates the real
Temporal describe response and asserts `Calendars` is cleared.

## Test plan

- [x] `go build ./...` compiles
- [x] `go test ./pkg/schedule/...` — 8/8 tests pass
- [x] `go test ./...` — full suite passes
- [x] `golangci-lint run ./pkg/schedule/...` clean
- [x] Manual end-to-end against `temporal server start-dev`:
- Start 1: `SCHEDULE_ENABLED=true SCHEDULE_CRON="0 6 * * *"` → `temporal
schedule describe` shows one calendar entry for 06:00
- Start 2: restart with `SCHEDULE_CRON="*/30 * * * *"` → server logs
`Schedule updated`, `temporal schedule describe` shows a single calendar
entry matching `*/30` (stale entry correctly cleared)
- `temporal workflow list --query 'WorkflowType =
"OrchestratorWorkflow"'` confirms scheduled runs fire on cron boundaries

### Reproducing locally

```bash
# Terminal 1: start Temporal dev server
temporal server start-dev --namespace version-guard-dev

# Terminal 2: run the server with scheduling enabled
SCHEDULE_ENABLED=true \
SCHEDULE_CRON="*/5 * * * *" \
SCHEDULE_ID="version-guard-local" \
SCHEDULE_JITTER=1m \
TEMPORAL_ENDPOINT=localhost:7233 \
TEMPORAL_NAMESPACE=version-guard-dev \
WIZ_CLIENT_ID_SECRET=<your-id> \
WIZ_CLIENT_SECRET_SECRET=<your-secret> \
WIZ_REPORT_IDS='{"aurora-postgresql":"<report-id>"}' \
CONFIG_PATH=config/resources.yaml \
go run ./cmd/server

# Terminal 3: verify via CLI
temporal schedule list --namespace version-guard-dev
temporal schedule describe --schedule-id version-guard-local --namespace version-guard-dev
temporal workflow list --namespace version-guard-dev \
  --query 'WorkflowType = "OrchestratorWorkflow"'
```

Note: `docker-compose up` works too once `SCHEDULE_ENABLED` is exported,
but the bundled Temporal image currently needs a fix on `main` before
compose boots a healthy server — out of scope for this PR.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: revied

cmd/server/main.go

@@ -27,6 +27,7 @@ import (
 	"github.com/block/Version-Guard/pkg/inventory/wiz"
 	"github.com/block/Version-Guard/pkg/policy"
 	"github.com/block/Version-Guard/pkg/registry"
+	"github.com/block/Version-Guard/pkg/schedule"
 	"github.com/block/Version-Guard/pkg/snapshot"
 	"github.com/block/Version-Guard/pkg/store/memory"
 	"github.com/block/Version-Guard/pkg/types"
@@ -72,6 +73,12 @@ type ServerCLI struct {
 	TagEnvKeys   string `help:"Comma-separated tag keys for environment" default:"environment,env" env:"TAG_ENV_KEYS"`
 	TagBrandKeys string `help:"Comma-separated tag keys for brand/business unit" default:"brand" env:"TAG_BRAND_KEYS"`
 
+	// Schedule configuration
+	ScheduleEnabled bool   `help:"Enable scheduled scanning" default:"false" env:"SCHEDULE_ENABLED"`
+	ScheduleCron    string `help:"Cron expression for scan schedule" default:"0 6 * * *" env:"SCHEDULE_CRON"`
+	ScheduleID      string `help:"Temporal schedule ID" default:"version-guard-scan" env:"SCHEDULE_ID"`
+	ScheduleJitter  string `help:"Schedule jitter duration" default:"5m" env:"SCHEDULE_JITTER"`
+
 	// Resource configuration
 	ConfigPath string `help:"Path to resources config file" default:"config/resources.yaml" env:"CONFIG_PATH"`
 
@@ -132,6 +139,12 @@ func (s *ServerCLI) Run(_ *kong.Context) error {
 		fmt.Printf("  Tag Keys - App: %s\n", s.TagAppKeys)
 		fmt.Printf("  Tag Keys - Env: %s\n", s.TagEnvKeys)
 		fmt.Printf("  Tag Keys - Brand: %s\n", s.TagBrandKeys)
+		if s.ScheduleEnabled {
+			fmt.Printf("  Schedule: enabled (cron: %s, id: %s, jitter: %s)\n",
+				s.ScheduleCron, s.ScheduleID, s.ScheduleJitter)
+		} else {
+			fmt.Printf("  Schedule: disabled\n")
+		}
 	}
 
 	if s.DryRun {
@@ -346,10 +359,40 @@ func (s *ServerCLI) Run(_ *kong.Context) error {
 		fmt.Println("⚠️  Orchestrator snapshot activity not registered (no S3 store)")
 	}
 
+	// Create schedule (if enabled)
+	if s.ScheduleEnabled {
+		jitter, parseErr := time.ParseDuration(s.ScheduleJitter)
+		if parseErr != nil {
+			fmt.Printf("⚠️  Invalid schedule jitter %q, using default 5m: %v\n", s.ScheduleJitter, parseErr)
+			jitter = 5 * time.Minute
+		}
+
+		scheduleMgr := schedule.NewManager(temporalClient)
+		schedCtx, schedCancel := context.WithTimeout(ctx, 10*time.Second)
+		defer schedCancel()
+		schedErr := scheduleMgr.EnsureSchedule(schedCtx, schedule.Config{
+			Enabled:        true,
+			ScheduleID:     s.ScheduleID,
+			CronExpression: s.ScheduleCron,
+			Jitter:         jitter,
+			TaskQueue:      s.TemporalTaskQueue,
+		})
+		if schedErr != nil {
+			fmt.Printf("⚠️  Failed to create/update schedule: %v\n", schedErr)
+			fmt.Println("   Worker will continue — trigger scans manually")
+		} else {
+			fmt.Printf("✓ Schedule configured: %s (cron: %s, jitter: %s)\n",
+				s.ScheduleID, s.ScheduleCron, s.ScheduleJitter)
+		}
+	}
+
 	// Start worker
 	fmt.Printf("\n✓ Temporal worker starting on queue: %s\n", s.TemporalTaskQueue)
 	fmt.Println("\nVersion Guard is ready!")
-	fmt.Println("\n📖 To trigger a scan, use the Temporal UI or CLI:")
+	if s.ScheduleEnabled {
+		fmt.Printf("   Scans will run automatically (schedule: %s)\n", s.ScheduleCron)
+	}
+	fmt.Println("\n📖 To trigger a scan manually, use the Temporal UI or CLI:")
 	fmt.Printf("   temporal workflow start --task-queue %s --type %s --input '{}'\n", s.TemporalTaskQueue, orchestrator.OrchestratorWorkflowType)
 	fmt.Println("\n📖 To query findings via gRPC:")
 	fmt.Printf("   grpcurl -plaintext localhost:%d list\n", s.GRPCPort)

docker-compose.yaml

@@ -63,6 +63,10 @@ services:
       WIZ_CLIENT_SECRET_SECRET: ${WIZ_CLIENT_SECRET_SECRET:-}
       WIZ_REPORT_IDS: ${WIZ_REPORT_IDS:-}
       EOL_BASE_URL: http://endoflife:8080/api
+      SCHEDULE_ENABLED: ${SCHEDULE_ENABLED:-false}
+      SCHEDULE_CRON: ${SCHEDULE_CRON:-0 6 * * *}
+      SCHEDULE_ID: ${SCHEDULE_ID:-version-guard-scan}
+      SCHEDULE_JITTER: ${SCHEDULE_JITTER:-5m}
     ports:
       - "8080:8080"
       - "8081:8081"

pkg/schedule/schedule.go

@@ -0,0 +1,126 @@
+package schedule
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"go.temporal.io/sdk/client"
+	"go.temporal.io/sdk/temporal"
+
+	"github.com/block/Version-Guard/pkg/workflow/orchestrator"
+)
+
+// Config holds configuration for the Temporal schedule.
+type Config struct {
+	ScheduleID     string
+	CronExpression string
+	TaskQueue      string
+	Jitter         time.Duration
+	Enabled        bool
+	Paused         bool
+}
+
+// Creator abstracts the Temporal schedule client for testability.
+type Creator interface {
+	Create(ctx context.Context, options client.ScheduleOptions) (client.ScheduleHandle, error)
+	GetHandle(ctx context.Context, scheduleID string) client.ScheduleHandle
+}
+
+// Manager handles Temporal schedule lifecycle.
+type Manager struct {
+	scheduleClient Creator
+}
+
+// NewManager creates a Manager from a Temporal client.
+func NewManager(c client.Client) *Manager {
+	return &Manager{scheduleClient: c.ScheduleClient()}
+}
+
+// NewManagerWithClient creates a Manager with an explicit Creator (for testing).
+func NewManagerWithClient(sc Creator) *Manager {
+	return &Manager{scheduleClient: sc}
+}
+
+// EnsureSchedule creates the schedule if it doesn't exist, or updates it
+// if the cron expression has changed.
+func (m *Manager) EnsureSchedule(ctx context.Context, cfg Config) error {
+	if !cfg.Enabled {
+		return nil
+	}
+
+	opts := client.ScheduleOptions{
+		ID: cfg.ScheduleID,
+		Spec: client.ScheduleSpec{
+			CronExpressions: []string{cfg.CronExpression},
+			Jitter:          cfg.Jitter,
+		},
+		Action: &client.ScheduleWorkflowAction{
+			Workflow:                 orchestrator.OrchestratorWorkflow,
+			Args:                     []interface{}{orchestrator.WorkflowInput{}},
+			TaskQueue:                cfg.TaskQueue,
+			WorkflowExecutionTimeout: 2 * time.Hour,
+		},
+		Paused: cfg.Paused,
+	}
+
+	_, err := m.scheduleClient.Create(ctx, opts)
+	if err == nil {
+		return nil
+	}
+
+	// If the schedule already exists, check if we need to update it
+	if !isScheduleAlreadyRunning(err) {
+		return fmt.Errorf("failed to create schedule %q: %w", cfg.ScheduleID, err)
+	}
+
+	handle := m.scheduleClient.GetHandle(ctx, cfg.ScheduleID)
+	desc, err := handle.Describe(ctx)
+	if err != nil {
+		return fmt.Errorf("failed to describe existing schedule %q: %w", cfg.ScheduleID, err)
+	}
+
+	// Check if the cron expression or jitter has changed
+	existingSpec := desc.Schedule.Spec
+	if existingSpec == nil {
+		existingSpec = &client.ScheduleSpec{}
+	}
+	existingCrons := existingSpec.CronExpressions
+	if len(existingCrons) == 1 && existingCrons[0] == cfg.CronExpression && existingSpec.Jitter == cfg.Jitter {
+		fmt.Printf("  Schedule %q already configured (cron: %s)\n", cfg.ScheduleID, cfg.CronExpression)
+		return nil
+	}
+
+	// Update the schedule with the new spec.
+	// We replace the entire Spec rather than mutating fields because Temporal
+	// parses CronExpressions into Calendars/StructuredCalendar server-side on
+	// create. On subsequent describes, the cron lives in Calendars and
+	// CronExpressions comes back empty — mutating CronExpressions alone would
+	// leave stale calendars in place, causing the schedule to fire on both
+	// the old and new cadences after every restart with a changed cron.
+	err = handle.Update(ctx, client.ScheduleUpdateOptions{
+		DoUpdate: func(input client.ScheduleUpdateInput) (*client.ScheduleUpdate, error) {
+			input.Description.Schedule.Spec = &client.ScheduleSpec{
+				CronExpressions: []string{cfg.CronExpression},
+				Jitter:          cfg.Jitter,
+			}
+			if action, ok := input.Description.Schedule.Action.(*client.ScheduleWorkflowAction); ok {
+				action.TaskQueue = cfg.TaskQueue
+			}
+			return &client.ScheduleUpdate{
+				Schedule: &input.Description.Schedule,
+			}, nil
+		},
+	})
+	if err != nil {
+		return fmt.Errorf("failed to update schedule %q: %w", cfg.ScheduleID, err)
+	}
+
+	fmt.Printf("  Schedule %q updated (cron: %s)\n", cfg.ScheduleID, cfg.CronExpression)
+	return nil
+}
+
+func isScheduleAlreadyRunning(err error) bool {
+	return errors.Is(err, temporal.ErrScheduleAlreadyRunning)
+}