Skip to content

feat(sync-plan): explain policy matches and planned actions #107

Description

@ClaudiaFang

Priority

Product capability — trust and auditability

Problem

A selective sync tool should explain not only what it plans to do, but why each file is included, excluded, moved, deleted, or marked as conflicting.

Without decision explanations, users cannot confidently audit a sync plan before data leaves the vault or remote content is changed.

Plan

  • Add structured reason codes to sync-plan entries.
  • Explain include/exclude policy matches from feat: add include/exclude patterns and default-deny sync mode #47.
  • Show the matched profile/rule and relevant path pattern.
  • Explain operation decisions such as local-only, remote-only, moved, modified, deleted, and conflict.
  • Distinguish policy decisions from provider limitations and errors.
  • Add a rule-preview tool for a path or selected folder.
  • Ensure explanations work in both flat and tree views.

Example explanations

Included: matched include rule `blog/**`
Excluded: matched `**/private/**`
Excluded: no include rule matched in default-deny mode
Moved: local path changed since the last successful sync
Conflict: remote blob differs from the last-synced base
Blocked: provider does not support this operation atomically

Acceptance criteria

  • Every actionable sync-plan entry has at least one stable reason code.
  • Users can identify the exact rule responsible for inclusion/exclusion.
  • Explanations are generated by planning logic, not reconstructed in the UI.
  • Reason-code behavior has table-driven tests.
  • The UI remains usable on narrow desktop sidebars and mobile.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions