Use this skill automatically before finishing when functional code changed since the last successful Truth Sync. Also run it immediately when the user explicitly invokes Truth Sync.
Invocations: OpenCode /skill truthmark-sync; Codex /truthmark-sync or $truthmark-sync; Claude Code /truthmark-sync; GitHub Copilot /truthmark-sync; Gemini CLI /truthmark:sync.
Explicit invocation runs immediately. Later functional-code changes need a fresh finish-time review, and an earlier explicit run satisfies the finish-time review only if no later functional-code changes occur.
Skip when changes are documentation-only, formatting-only, clearly behavior-preserving renames with no truth impact, when no Truthmark config exists yet, or when there are no functional code changes.
- Repository instruction files and explicitly configured policy docs remain instruction authority when present; do not assume a repository uses any particular policy path.
- Implementation code and canonical truth docs are inspected evidence for current behavior; they do not silently override workflow write boundaries.
- ask whether a user-visible promise, capability boundary, API contract, acceptance criterion, or explicit user/product evidence changed
- if yes, update or route product truth under docs/truthmark/product as well as engineering truth under docs/truthmark/engineering
- if no, default to engineering truth under docs/truthmark/engineering for internal implementation changes
- when both lanes change, keep separate product and engineering docs cross-linked through route YAML with realized_by and realizes
- when ownership is ambiguous, stop or route to Truth Structure instead of writing a mixed document
6. Capture decision context from the task conversation: ask whether the user provided a product or technical decision, rationale, constraint, tradeoff, rejection reason, or scope boundary. Preserve concise user-provided decision rationale in Sync Intent before truth edits, route it to Product Decisions, Engineering Decisions, Rationale, Capability Scope, Non-Goals, Maintenance Notes, or the relevant workflow/contract section, and report whether it was placed, skipped because none was provided, or needs manual handoff.
7. Update engineering truth first after code changes. Product truth is opt-in for externally visible promises, product boundaries, APIs, acceptance criteria, or explicit user/product evidence.
8. Code verification is parent-owned: follow repository instructions and task context, and report what ran or why it did not run.
9. Dispatch bounded Truth Sync workers only when the host supports subagent dispatch and the acting agent chooses that path; otherwise execute the same sync task inline.
10. Fill Sync Intent before editing truth docs or truth routing files:
- Changed code reviewed: functional files, tests, configs, generated outputs, or other implementation evidence inspected
- Affected route/truth owner: bounded route area or canonical truth owner that maps the change
- Target truth docs: docs expected to change, or docs reviewed and left unchanged
- Intended update: claim/doc/routing update planned before writing
- Evidence to verify: checkout evidence that will support, narrow, remove, or record each claim for manual handoff
- User-provided decisions/rationale: decisions, rationale, constraints, tradeoffs, rejection reasons, or scope boundaries from the current task conversation, or "none provided"
- No-update-needed rationale: why mapped truth is already current when no truth doc should change
11. Only edit allowed truth docs/routes after Sync Intent is clear; if ownership is ambiguous, repair topology first when the repair is safe and in scope, otherwise stop and recommend Truth Structure instead of guessing.
- if routing is missing, stale, broad, overloaded, catch-all route only, or cannot map changed code to a bounded truth owner, run Truth Structure before syncing when topology repair is safe and in scope
- safe in-scope topology repair may update truth routing files and create or update bounded leaf truth docs needed to map the changed functional code; keep the repair limited to the affected route owner
- stop and recommend Truth Structure only when topology repair is unsafe, ambiguous, or outside the current task boundary
- report the route files and changed code paths that required structure repair
- write engineering truth under docs/truthmark/engineering; product truth updates under docs/truthmark/product are allowed only for explicit current product behavior changes
- update Product Decisions only in product truth and Engineering Decisions only in engineering truth when evidence supports the lane-specific decision change
- validate the final report against the structured Truth Sync report contract, including Claim, indented Evidence, and Result values supported, narrowed, removed, or blocked under Evidence checked
- verify the updated docs correspond to reviewed checkout evidence, changed-code impact, or a recorded stale-truth correction made within the sync write lease
- verify the final report records ownership review, structure requirement, split, restructure, or manual handoff reason when the ownership review applies
- manual handoff outcomes must preserve the working tree as-is: no rollback, no post-block cleanup edits, and manual-review reporting of any remaining files
