udecode Sync Vision
sync-vision turns repository changes into an explicit doctrine-drift audit. It
does not rewrite vision from commit messages.
Autogoal Dependency
Every sync or advance run is durable work. Create or resume a goal from the
sync-vision template with the agent-native pack before editing.
status and preview are read-only and may run without a goal.
State
The committed baseline lives at:
docs/sync/vision/status.json
It records the last reviewed commit, review time, optional note, and the files whose conclusions were advanced. The baseline means “reviewed for doctrine,” not “all changes were copied into VISION.md.”
Commands
node .agents/rules/sync-vision/scripts/collect-vision-diff.mjs --status
node .agents/rules/sync-vision/scripts/collect-vision-diff.mjs --preview
node .agents/rules/sync-vision/scripts/collect-vision-diff.mjs --since <sha>
status: show baseline and candidate count.preview: print the candidate file/keyword evidence since baseline.sync: inspect candidates, update owners, validate, and advance state.advance: advance without doctrine edits only after recording why every candidate is already represented, implementation-only, or intentionally rejected.
Input Scope
The collector searches source-owned doctrine and planning surfaces:
VISION.md,.agents/AGENTS.md, and.agents/rules/**;docs/README.md, plans, PRDs, milestones, ADRs, analysis, brainstorms, research, solutions, and sync records;- root Markdown/MDX/MDC sources.
Generated skill mirrors, build output, fixtures, temp apps, dependencies, and the current generated sync report are excluded. Source changes may still require inspection even when their text does not contain a keyword.
Classification
Classify every candidate:
| Class | Owner/action |
|---|---|
| durable doctrine | update VISION.md |
| planning map | update PRD/milestone/docs map |
| architecture decision | update ADR/analysis and link from vision if durable |
| repository workflow | update .agents source and regenerate |
| current implementation detail | keep in source/docs; no vision edit |
| superseded/rejected | record reason; no vision edit |
| contradiction | stop and resolve before advancing |
Relevant kitcn topics include public API, cRPC/ORM, Convex import graphs, plugins, auth, CLI/DX, scaffolds, fixtures, docs, compatibility, release, proof, and agent workflow.
Sync Workflow
- Read baseline status and preview candidates.
- Read
VISION.md,docs/README.md, and each candidate's actual owner. - Build a classification table with evidence and proposed owner.
- Resolve contradictions and duplicate doctrine.
- Update the smallest canonical owners. Keep implementation detail out of
VISION.md. - Regenerate agent mirrors when
.agentssources changed. - Run helper syntax/status checks, exact-term audits, and relevant repository checks.
- Run
agent-native-reviewer, thenautoreview. - Record the reviewed head and note in
status.jsononly after all applicable gates pass. - Rerun
--status; it must show the expected baseline and no unexplained candidate drift.
Baseline Advancement
Never advance merely to silence the collector. The goal plan must contain:
- old and new commit ids;
- candidate inventory and classification;
- changed owners or no-change reasons;
- contradiction resolution;
- validation and review receipts.
If the working tree contains relevant uncommitted doctrine changes, include them in the audit and do not pretend a commit-only baseline represents them.
Final Handoff
Report updated doctrine owners, intentionally unchanged candidates, exact baseline, validation, and any open decision.