Sync Docs

Sync docs

Contract

Inputs

• Mode: report (default) or apply. apply still edits only safe-fix issues.
• Scope: recent (changed files from current branch or last few commits), before-pr (branch diff against PR base), or all (all tracked code and docs).
• Base: explicit base ref preferred. If absent, resolve the default branch, then fall back to HEAD~5 for recent.

Refusal

• No diff or empty scope: stop. Report the resolved base and scope; do not fabricate drift.
• Ambiguous base ref: stop. List candidate refs and ask the user.
• Manifest parse failure: skip the version-bump safe fix for that manifest; flag the file as MEDIUM with reason.
• Post-edit read mismatch: revert the edit; reclassify the issue as flag-only with reasonFlagOnly.
• Codegraph unavailable: use syntax fallback; downgrade confidence to MEDIUM for symbol-dependent claims.

Procedure

1. Pick scope and base. Refuse ambiguous review scope when the user expects PR readiness. Resolve the base ref and compute the changed-file list. In ODIN tool mode, use bash only for git commands; use find, search, read, lsp, ast_grep, and edit for everything else. Done when: the scope and base are resolved and the changed-file list is computed.
2. Compute changed code. Keep only source/config/package files that can change docs. Exclude pure docs, vendored/generated paths, lockfiles unless version docs mention package manager output, and deleted files that were never public. Done when: the changed-code file list is filtered.
3. Extract coupling terms. For each changed code file derive filename stem, full path, import strings from the diff, and exported/public symbols via codegraph when indexed or syntax fallback. Load references/doc-issues.md for the full detection recipe. Done when: coupling terms are extracted for every changed file.
4. Discover related docs. Search live doc surfaces: README.md, CHANGELOG.md, docs/**/*.md, *.md at repo root. For each coupling term, search docs and record doc, line, term, referenceType. Done when: every coupling term is searched against docs.
5. Classify issues. Load references/doc-issues.md for the severity taxonomy, safe-fix boundary, and default ignore list. Classify each finding as HIGH, MEDIUM, or LOW. Ignore generated docs unless explicitly in scope, vendored docs, changelog append-only entries, and versioned snapshots unless in scope. Done when: every finding is classified with severity and safe-fix eligibility.
6. Apply safe fixes only (in apply mode). Safe fixes are: version bump (replace stale semver in docs with the manifest version when the line clearly labels a version) and CHANGELOG ## [Unreleased] entry (insert a minimal bullet citing commit/file evidence). Load references/detection-recipes.md for per-ecosystem manifest version fields and changelog evidence commands. Do not auto-edit removed exports, import paths, examples, undocumented exports, dead-code docs, or doc-drift prose. Those require human intent. Done when: safe fixes are applied or confirmed unavailable.
7. Flag the rest. Emit a compact report sorted by severity then file path. Done when: every non-safe-fix finding is flagged with file:line evidence and reason.
8. Return fix ledger. For every edit record file, line, type, before, after, and evidence source. For every flag-only item record reasonFlagOnly. Done when: the fix ledger is complete.

Failure modes

• Partial results: if some coupling terms resolve and others do not, report resolved issues and flag unresolved terms. Never widen scope to compensate for missing evidence.
• Rollback: revert any edited file to its pre-edit content. The fix ledger records before/after for every edit.

Output

A JSON fix ledger: opCell, scope, base, changedCode array, relatedDocs array, fixesApplied array, flagged array. Completion means safe fixes are applied or explicitly unavailable, and all remaining drift is flagged. A clean report with no edits is valid only after the diff-to-doc mapping and taxonomy pass ran.