sync-vision

# 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: ```text 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 ```bash 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 1. Read baseline status and preview candidates. 2. Read `VISION.md`, `docs/README.md`, and each candidate's actual owner. 3. Build a classification table with evidence and proposed owner. 4. Resolve contradictions and duplicate doctrine. 5. Update the smallest canonical owners. Keep implementation detail out of `VISION.md`. 6. Regenerate agent mirrors when `.agents` sources changed. 7. Run helper syntax/status checks, exact-term audits, and relevant repository checks. 8. Run `agent-native-reviewer`, then `autoreview`. 9. Record the reviewed head and note in `status.json` only after all applicable gates pass. 10. 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.