Objective
Add --dry-run and --check modes to dev-tools:sync so maintainers can inspect pending synchronization changes before writing files, and optionally confirm replacements interactively in terminal sessions.
Current Limitation
dev-tools:sync performs file and repository mutations directly. Maintainers of consumer repositories need a safe way to preview changes, identify stale managed files, and use a CI-friendly mode that fails when sync-managed files are drifted.
Proposed Work
Add three execution modes:
--dry-run: report the changes sync would make without writing files or running mutating Git operations.
--check: report whether the repository is in sync and return a non-zero exit code when changes would be required.
--interactive: when running in an interactive terminal, show detected drift and ask whether each managed file should be replaced.
The default dev-tools:sync behavior should remain non-interactive. Prompting should only happen when --interactive is explicitly requested and the input is interactive.
Scope
- Cover all existing sync phases where practical: Composer metadata, workflow stubs,
.editorconfig, Dependabot, wiki setup, .gitignore, .gitattributes, skills, license, and Git hooks.
- Ensure
--dry-run does not write files, create symlinks, initialize hooks, or add submodules.
- Ensure
--check is suitable for CI and exits non-zero on detected drift or missing managed assets.
- Reuse or prepare drift/status logic from sync phases rather than shelling out blindly.
- Surface drift details in output, including affected phase, path, and text diffs where available.
- Keep
--interactive optional and TTY-aware so Composer hooks and CI runs do not block on prompts.
Non-goals
- Implementing selective
--only or --skip sync phases.
- Changing default sync behavior.
- Forcing prompts during Composer hooks, CI, or non-interactive sessions.
- Guaranteeing dry-run support for unsupported external tools in the first pass; unsupported phases should report that clearly.
Acceptance Criteria
Delivery Criteria
Architectural / Isolation Criteria
Objective
Add
--dry-runand--checkmodes todev-tools:syncso maintainers can inspect pending synchronization changes before writing files, and optionally confirm replacements interactively in terminal sessions.Current Limitation
dev-tools:syncperforms file and repository mutations directly. Maintainers of consumer repositories need a safe way to preview changes, identify stale managed files, and use a CI-friendly mode that fails when sync-managed files are drifted.Proposed Work
Add three execution modes:
--dry-run: report the changes sync would make without writing files or running mutating Git operations.--check: report whether the repository is in sync and return a non-zero exit code when changes would be required.--interactive: when running in an interactive terminal, show detected drift and ask whether each managed file should be replaced.The default
dev-tools:syncbehavior should remain non-interactive. Prompting should only happen when--interactiveis explicitly requested and the input is interactive.Scope
.editorconfig, Dependabot, wiki setup,.gitignore,.gitattributes, skills, license, and Git hooks.--dry-rundoes not write files, create symlinks, initialize hooks, or add submodules.--checkis suitable for CI and exits non-zero on detected drift or missing managed assets.--interactiveoptional and TTY-aware so Composer hooks and CI runs do not block on prompts.Non-goals
--onlyor--skipsync phases.Acceptance Criteria
Delivery Criteria
dev-tools:sync --dry-runreports planned changes without modifying the working tree.dev-tools:sync --checkexits0when no sync changes are needed.dev-tools:sync --checkexits non-zero when managed files are missing or drifted.dev-tools:sync --interactiveprompts before replacing drifted managed files when input is interactive.Architectural / Isolation Criteria
SyncCommandremains orchestration-focused.