When sidecar's scaffold conventions evolve (new sections like 🚘 Parked, updated hidden-instruction block, new hook message), existing SIDECAR.md files and installed hooks are frozen at whatever paradigm created them. There's no signal that an update exists and no upgrade path beyond manually re-running sidecar init (which only merges the hook, not the file boilerplate).
Idea
Stamp a template version into the scaffolded file and check it at launch; offer a safe, opt-in migration to the current paradigm.
Design sketch
- Stamp a template version, not the app version. A small integer in the hidden comment, e.g.
<!-- sidecar-template: 2 -->. Bumps only when scaffold conventions change, independent of app semver. On launch, sidecar reads it; missing/behind ⇒ file predates current.
- Migrations are additive + boilerplate-only — never touch user content.
- Safe: refresh the hidden instruction block (a marked region), insert a missing section header (empty).
- Dangerous, out of scope: renaming/removing a section (where would items go?), reordering. The engine only adds and refreshes marked regions; it never reorders or deletes user items.
- Interactive + opt-in; never on non-TTY. Prompt e.g.
your queue predates vN — update boilerplate? [y/N]; apply only on yes, then bump the stamp. Piped/CI launches skip silently.
- Also re-sync init wiring. Optionally refresh the CLAUDE.md note and the UserPromptSubmit hook message to the current text (reuse the existing merge/replace-by-sentinel logic).
Risks / open questions
- Editing a user-authored file: needs deterministic region markers so migration finds/replaces only boilerplate.
- Don't nag: a declined migration shouldn't re-prompt every launch — decide whether 'no' is remembered or re-asked.
- Keep it conservative: when in doubt, print what to change and let the user apply it, rather than editing.
Parked from the sidecar dogfood queue; sequel to the hook merge/upgrade path (#4-adjacent).
When sidecar's scaffold conventions evolve (new sections like 🚘 Parked, updated hidden-instruction block, new hook message), existing SIDECAR.md files and installed hooks are frozen at whatever paradigm created them. There's no signal that an update exists and no upgrade path beyond manually re-running
sidecar init(which only merges the hook, not the file boilerplate).Idea
Stamp a template version into the scaffolded file and check it at launch; offer a safe, opt-in migration to the current paradigm.
Design sketch
<!-- sidecar-template: 2 -->. Bumps only when scaffold conventions change, independent of app semver. On launch, sidecar reads it; missing/behind ⇒ file predates current.your queue predates vN — update boilerplate? [y/N]; apply only on yes, then bump the stamp. Piped/CI launches skip silently.Risks / open questions
Parked from the sidecar dogfood queue; sequel to the hook merge/upgrade path (#4-adjacent).