Hot-reload WORKFLOW.md changes

[VincentShipsIt]

PRD: hot-reload-workflow-md

Executive Summary

Adopt Symphony's dynamic-reload semantic. A file watcher on `.shipcode/WORKFLOW.md` re-parses and atomically swaps config when the file changes. Future dispatches and reconcile ticks pick up new values; in-flight pipelines keep their existing config. Lets users tune prompts and concurrency without restarting the desktop app or daemon.

Implementation Checklist

• Watcher uses `chokidar` or `fs.watch` on the resolved WORKFLOW.md path
• Debounce file events to coalesce rapid saves (200ms)
• On change: re-run loader, re-validate; on success, swap the shared config object atomically; on failure, keep prior and emit warning
• Renderer receives an IPC event `workflow:reloaded` with success/failure detail; UI shows toast
• Watcher unregistered cleanly on app quit

Problem Statement

With #65 landed, prompt and config edits will require an app restart to take effect. For a daemon (#70) running on EC2, restart drops state and breaks the autonomous loop. For local desktop use, restart is friction.

Goals

• Watcher on `.shipcode/WORKFLOW.md` (and root fallback) detects writes.
• On change, re-parse and validate the file.
• Valid reload swaps config atomically; invalid reload keeps the last known good and emits a warning.
• New config applies to: future dispatch, reconcile cadence, retry scheduling, hooks, prompts.
• In-flight pipelines retain their existing config.

Non-Goals

• Restarting in-flight agent sessions automatically.
• Watching arbitrary files outside the configured path.
• Migrating mid-flight prompts.

User Stories

• As a maintainer tuning the planner prompt, I want my edit to take effect on the next pipeline without restart, so iteration is fast.
  Acceptance:
  • Editing the planner prompt body and saving changes the next pipeline's prompt verbatim.
  • Editing `agent.max_concurrent_agents` from 3 to 1 caps the next dispatch tick to 1.
  • Saving invalid YAML keeps the prior config and surfaces a warning toast.

Functional Requirements

1. Watcher uses `chokidar` or `fs.watch` on the resolved WORKFLOW.md path.
2. Debounce file events to coalesce rapid saves (200ms).
3. On change: re-run loader, re-validate; on success, swap the shared config object atomically; on failure, keep prior and emit warning.
4. Renderer receives an IPC event `workflow:reloaded` with success/failure detail; UI shows toast.
5. Watcher unregistered cleanly on app quit.

Non-Functional Requirements

• Debounce + parse + swap must complete in <100ms typical.
• Warning surface must include the parse error string but never the full file contents.

Success Criteria

• Unit tests with mocked watcher: change event triggers reparse and swap.
• Invalid YAML test: prior config preserved.
• Future-dispatch test: new value observed on next dispatch tick.
• In-flight test: a pipeline mid-run keeps its captured config snapshot.
• Manual: edit WORKFLOW.md; observe toast and confirm next pipeline picks up change.

Out of Scope

• Watching `.git` for branch switches (the WORKFLOW.md may change as a side effect, which is fine).
• Hot-rebinding the HTTP server port (Symphony spec also exempts this; defer to Add JSON state API for daemon #76).
• Restart-required behavior for hook-script-only edits.

Dependencies

• Add WORKFLOW.md target-repo policy #65 (loader + config object).
• IPC bus in `apps/desktop/src/main/index.ts`.
• Symphony spec: https://github.com/openai/symphony/blob/main/SPEC.md#62-dynamic-reload-semantics

Verification Plan

• tests: new `packages/pipeline/src/workflow-watcher.test.ts` covering change detection, debounce, invalid reload preservation, atomic swap.
• manual: with desktop app running, save WORKFLOW.md edit; verify toast and behavior change on next pipeline.

Risks & Open Questions

• File-watcher reliability on macOS APFS — `chokidar` known good but adds dependency weight.
• In-flight dispatch tick that has read config but not yet spawned — confirm snapshot semantics so it does not split-brain.