purpose-sync

Keep the project's purpose tree in step with its implementations. Uses the purpose-tree method; read it first if you have not.

You touch realized_by and last_synced. A purpose changes only when the human explicitly accepts a session-end review item (step 2b); never edit one on your own.

Steps

1. Collect changes. Run:

   node <this-skill>/scripts/changes.cjs
   

   It prints JSON: the tree file, the base commit (the tree's last_synced, or the last commit that touched the tree), every changed path since then (committed and not), and for each path the node ids whose realized_by mentions it. touched_any lists every path changed by any commit in the range (plus uncommitted ones), with its nodes; a path changed and then reverted still appears there. Exit 2 = no tree here: stop silently. Exit 4 = the tree exists but does not parse: print exactly purpose-sync: skipped reason=unparseable file=<tree> as your last line, change nothing, and let the session end continue (purpose-review can rebuild the tree). Exit 3 = setup problem (skill missing, not a git repo): report it in one line and stop.

   Too many changes? If there are more than 50 changes (whatever base_source is), the range is too old to sync item by item. Do not propose anything. Ask one question: "Set the sync baseline to HEAD? (purposes stay as they are; run a tree review to catch up)". Only on yes, do step 5. On no or no answer, write nothing. Print the summary with proposed=0.

2. Decide proposals. Work from that JSON, not from memory of the session. Use the conversation only to understand why something changed.

   • A node's implementation was renamed, moved, or deleted → update its realized_by.
   • A node gained a new implementation → add it to that node's realized_by.
   • A changed path matches no node (unmatched) and is real functionality → propose which existing purpose it serves. If none fits, flag it as a gap; do not invent a purpose.
   • A node now has no implementation left → flag it as a gap.
   • A change with match: coarse reached its node only through a directory prefix, inside a subdirectory that is new since base. Ask: "does <subdir> serve <node>, or another purpose?". Exact matches and renames are never marked.
   • Tests, formatting, lockfiles, and docs-only edits are not proposals.

2b. Session-end review. Look only at the nodes this session touched and their parents: start from the nodes in touched_any (the range can include other sessions' commits), and narrow them to this session using the conversation. Raise a review item when one of these holds:

• (a) Several implementations of the same purpose were replaced in this session.
• (b) The node is in churn: its realized_by already changed 3+ times in 30 days. Endless tweaking usually means the purpose is unclear (rabbit-holing).
• (c) New functionality fits no purpose and looks like a new direction, not a stray file. A review item is a question, not an edit: "Is <id> still about ''?" or "Is this a new purpose, or should it not exist?". If the human answers with a new wording, apply it; otherwise change nothing. Use the conversation to judge (a) and (c); do not go back to older sessions.

1. If there is nothing to show (no proposal, gap or review): say nothing. Skip step 5 and leave the tree file untouched; print the summary line.

2. Otherwise ask once. One numbered list, then one question:

   Purpose tree — 3 proposals
   1. daily_awareness: realized_by "cron brief" → "scripts/brief.js"
   2. offline_reading: add "app/cache/"
   3. gap: scripts/export.js serves no purpose — which purpose is it for?
   4. review: daily_awareness changed 4 times in 30 days — still "Know what matters before the day starts"?
   Accept all? (or e.g. "reject 2", "3: serves sync_progress")