Symphony: manage project template drift and binary updates

[gannonh]

Follow-up from #502.

Background

Symphony now supports project-local .symphony/ assets created by symphony init. The current implementation embeds starter assets in the binary and preserves existing files unless symphony init --force is used.

Remaining work: detect drift between a repo's committed .symphony/ assets and the bundled assets in a newer Symphony binary, and provide a binary update notification/update flow for long-running daemons.

Scope

1. Project template drift detection

Add metadata and commands so users can tell when their .symphony/ assets differ from the bundled templates.

Proposed behavior:

• Add template metadata to generated starter files, for example:
  <!-- symphony-template: prompts/system.md version=<version> checksum=<checksum> -->
• Add symphony prompts status to report each managed asset as:
  • matches bundled template
  • modified by user
  • missing
  • template has newer bundled version
• Add symphony prompts update to:
  • update files that still match the previous bundled template
  • write .new files for files with user modifications
  • create missing starter files
  • avoid overwriting user-edited files unless explicitly forced
• Keep repository-specific prompt files editable and committed in .symphony/.

2. Symphony daemon version checks

The running Symphony daemon should periodically check whether a newer Symphony version is available.

Proposed behavior:

• On startup and periodically afterward, check the latest available Symphony release/version.
• If a newer version exists, notify the user in the TUI, logs, and HTTP dashboard/API.
• Include current version, latest version, release URL, and a concise upgrade instruction.
• Make the check configurable for offline/private deployments.
• Avoid blocking orchestration if version checks fail.

3. Symphony update flow

Define and implement a supported update path for binary installs.

Possible shape:

• Add symphony update to download and install the latest compatible binary.
• Support dry-run/status output before mutating anything.
• Verify downloaded artifacts before replacing the current binary.
• Handle permission failures with a clear manual command.
• Coordinate with the daemon so users can update safely while Symphony is running.

Acceptance criteria

• symphony prompts status detects clean, modified, missing, and newer bundled prompt/workflow assets.
• symphony prompts update preserves user edits and writes reviewable .new files when needed.
• The daemon surfaces an available-version notification without interrupting active workers.
• Users have a documented update path for newer Symphony binaries.
• Docs cover template drift, version checks, offline configuration, and update commands.
• Tests cover checksum/status/update behavior and version-check notification behavior.

[coderabbitai]

🔗 Related PRs

#154 - KAT-901: post-patch verification + docs parity for TUI/dashboard [merged]
#213 - feat(symphony): split shared prompt into system + repo preambles [merged]
#219 - feat(symphony): silence unconfigured Symphony and add setup guidance [S03] [merged]
#459 - fix(symphony): finalize workflow runtime cleanup [merged]
#474 - [S901] Docs site audit and source inventory [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!