sync-docs

name	sync-docs
description	Sync all relevant documents based on the active phase's history log. Activates when the user invokes /sync-docs or asks momentum to run the sync-docs recipe.

Sync all relevant documents based on the active phase's history log. Token-efficient: reads history + 2 tiny indexes first, then only targeted files.

Steps

Step 1: Load history and indexes (cheap reads)

• Read specs/status.md → identify active phase
• Read specs/phases/<active-phase>/history.md → extract all entries
• Read specs/phases/index.json (~2KB)
• Read specs/decisions/impact-map.json (~3KB)

Step 2: Build targeted file list

For each history entry:

• Extract Topics list
• Look up each topic in index.json → collect affected phase tasks.md files
• Look up each topic in impact-map.json → collect affected spec files/sections
• Deduplicate the combined list
• For monorepo: EXCLUDE files in specs/architecture/ (constitution — never auto-synced, only amended via formal process)
• Multi-repo: PARTITION OUT cross-repo entries. If a history entry has an Affects-specs: path starting with ../ (or otherwise outside this repo), add it to a separate "cross-repo" list. NEVER edit those files — you only own this repo's docs.

Step 3: Show sync plan (ALWAYS show before touching anything)

Present to user: "Based on phase history, I will check and potentially update:

• [list of files] Proceed? (yes/no)"

If any cross-repo entries were partitioned out in Step 2: also show them under a "Cross-repo impact (NOT touching — sync the other repo manually)" heading, listing each Affects-specs: ../... path. Tell the user which repo they need to edit and which entries pointed there. Do NOT prompt for approval on cross-repo paths — they're informational only.

If user says no → stop.

Step 4: Read and assess (targeted reads only)

For each file in the list:

• Read only the relevant section
• Assess: does it need updating based on history entries?

Step 5: Make updates (one at a time, fully visible)

For each file that needs updating:

• Show the user what will change
• Use the Edit tool to make the change

Step 6: Update phase index if scope changed

If any [SCOPE_CHANGE] entries exist:

• Update specs/phases/index.json for the active phase's topic list

Step 7: Commit all changes

git add <all modified spec files>
git commit -m "docs(phase-N): sync specs from phase history"

Step 8: Confirm completion

"Spec sync complete. Updated N files:

• [list] Ready to run /complete-phase."

Safeguards

• NEVER update files not in the targeted list
• NEVER update specs/architecture/ (monorepo only — constitution is read-only)
• NEVER update files in another repo (paths starting with ../) — you only own this repo's docs. Flag cross-repo entries to the user instead.
• ALWAYS show the plan (Step 3) before making any edits
• History entries are NEVER modified — only read