feat(import) --sync / --prune flags, options.pin, CRDT action model (#520)

`vcspull import` silently skipped repos whose remote URL had changed,
forcing users to delete their config and re-run from scratch.  Repos
removed from the remote stayed in config forever.

This branch adds full bidirectional reconciliation to `vcspull import`
and applies a consistent CRDT action model (pure classifier -> enum ->
apply) across all five config-mutation operations.

New flags:

  --sync        Add new repos, update changed URLs, prune entries
                no longer on the remote (scoped by provenance tag).
  --prune       Prune stale entries only (no URL updates).
  --prune-untracked
                Extend --sync/--prune to also remove entries that
                lack any import provenance (manually added repos or
                entries from before provenance tracking).  Requires
                --sync or --prune.  A confirmation prompt lists
                exactly what would be removed.

Provenance tracking (metadata.imported_from):

  When --sync or --prune is used, each imported repo is tagged with
  "{service}:{target}" (e.g. "github:myorg").  Pruning is scoped by
  this tag -- only entries matching the current import source are
  candidates for removal.  Manually added repos and repos from other
  sources are never pruned.  Pruning is config-only; cloned
  directories on disk are not deleted.

options.pin -- per-repo, per-operation mutation guard:

  pin: true               block ALL operations
  pin: {import: true}     block import only
  allow_overwrite: false   shorthand for pin: {import: true}

  pin_reason is shown in log output when a repo is skipped.  Pin
  awareness has been added to import, add, discover, fmt, and the
  duplicate-workspace-root merge resolver.

CRDT action model:

  Every config-mutation command now follows the same three-step
  pattern: pure classifier -> enum action -> apply.

  import:    ADD, SKIP_UNCHANGED, SKIP_EXISTING, UPDATE_URL,
             SKIP_PINNED, PRUNE
  add:       ADD, SKIP_EXISTING, SKIP_PINNED
  discover:  ADD, SKIP_EXISTING, SKIP_PINNED
  fmt:       NORMALIZE, NO_CHANGE, SKIP_PINNED
  merge:     KEEP_EXISTING, KEEP_INCOMING

Bug fixes:

  vcspull add, discover, and fmt all called save_config_yaml()
  unconditionally, silently corrupting .json config files by
  overwriting them with YAML content.  All save sites now check
  the file extension and call the correct serialiser.

Author: tony

CHANGES

@@ -33,6 +33,104 @@ $ uvx --from 'vcspull' --prerelease allow vcspull
 _Notes on upcoming releases will be added here_
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### New features
+
+#### `vcspull import`: Add `--sync` and `--prune` (#520)
+
+`--sync` fully reconciles your config with the remote: updates changed URLs,
+and prunes entries no longer on the remote. `--prune` does prune-only (no URL
+updates). Both respect pinned entries and use provenance tags
+(`metadata.imported_from`) to scope pruning — manually added repos are never
+removed.
+
+```console
+$ vcspull import gh myorg \
+    --mode org \
+    --workspace ~/code/ \
+    --sync
+```
+
+Available on all six import providers. Pruning is config-only — cloned
+directories on disk are not deleted. See {ref}`cli-import` for details.
+
+#### `vcspull import`: Add `--prune-untracked` flag (#520)
+
+`--prune-untracked` expands `--sync` / `--prune` to also remove config
+entries in the target workspace that lack import provenance — repos added
+manually or before provenance tracking. Entries imported from other sources
+and pinned entries are preserved. A confirmation prompt lists exactly what
+would be removed.
+
+```console
+$ vcspull import gh myorg \
+    --workspace ~/code/ \
+    --sync \
+    --prune-untracked \
+    --dry-run
+```
+
+#### `options.pin`: Per-repo, per-operation mutation guard (#520)
+
+Any repository entry can carry an `options.pin` block that prevents specific
+vcspull operations from mutating it. This is useful for pinned forks, company
+mirrors, or any repo whose config should only be changed manually.
+
+Pin all operations:
+
+```yaml
+~/code/:
+  myrepo:
+    repo: git+git@github.com:me/myrepo.git
+    options:
+      pin: true
+      pin_reason: "pinned to company fork — update manually"
+```
+
+Pin only specific operations:
+
+```yaml
+~/code/:
+  other-repo:
+    repo: git+git@github.com:me/other.git
+    options:
+      pin:
+        import: true    # --sync cannot replace this URL
+        fmt: true       # vcspull fmt preserves the entry verbatim
+      pin_reason: "pinned for import and fmt"
+```
+
+Shorthand — equivalent to `pin: {import: true}`:
+
+```yaml
+~/code/:
+  shorthand-repo:
+    repo: git+git@github.com:me/pinned.git
+    options:
+      allow_overwrite: false
+```
+
+Pin semantics:
+
+- `pin: true` — all five operations are blocked (`import`, `add`, `discover`,
+  `fmt`, `merge`)
+- `pin: {op: true}` — only the named operations are blocked; unspecified keys
+  default to `false`
+- `allow_overwrite: false` — concise shorthand, equivalent to
+  `pin: {import: true}`
+- `pin_reason` — human-readable string shown in log output when a repo is
+  skipped due to a pin
+
+Pin awareness has been added to all config-mutation commands: `import`,
+`add`, `discover`, `fmt`, and the duplicate-workspace-root `merge` resolver.
+
+### Bug fixes
+
+#### `vcspull add`, `vcspull discover`, `vcspull fmt`: Fix JSON configs saved as YAML (#520)
+
+All three commands called `save_config_yaml()` unconditionally, silently
+corrupting `.json` config files by overwriting them with YAML content. Each
+save site now checks the file extension and calls the correct serialiser.
+
 ## vcspull v1.57.0 (2026-02-22)
 
 ### Breaking changes

docs/cli/add.md

@@ -109,6 +109,32 @@ repositories stay intact. When it collapses multiple sections, the command logs
 a summary of the merge. Prefer to inspect duplicates yourself? Add
 `--no-merge` to keep every section untouched.
 
+## Pinned entries
+
+Repositories whose configuration includes a pin on the `add` operation are
+skipped with a warning. For example, given this configuration:
+
+```yaml
+~/code/:
+  internal-fork:
+    repo: "git+git@github.com:myorg/internal-fork.git"
+    options:
+      pin: true
+      pin_reason: "pinned to company fork — update manually"
+```
+
+Attempting to add a repo that matches an existing pinned entry produces a
+warning and leaves the entry untouched:
+
+```vcspull-console
+$ vcspull add ~/code/internal-fork
+⚠ Repository 'internal-fork' is pinned (pinned to company fork — update manually) — skipping
+```
+
+Both `options.pin: true` (global) and `options.pin.add: true` (per-operation)
+block the `add` command. The `pin_reason` (if set) is included in the warning.
+See {ref}`config-pin` for full pin configuration.
+
 ## After adding repositories
 
 1. Run `vcspull fmt --write` to normalize your configuration (see

docs/cli/discover.md

@@ -225,6 +225,36 @@ Skipped flask (already exists)
 
 You can choose to skip or overwrite the existing entry.
 
+## Pinned entries
+
+Repositories pinned for the `discover` operation are silently skipped during
+scanning. For example, given this configuration:
+
+```yaml
+~/code/:
+  internal-fork:
+    repo: "git+git@github.com:myorg/internal-fork.git"
+    options:
+      pin:
+        discover: true
+      pin_reason: "pinned to company fork — update manually"
+```
+
+When `vcspull discover` encounters `internal-fork` on disk, it groups it with
+existing entries and does not prompt for it. A debug-level log message is
+emitted, so pass `--log-level debug` to see which entries were skipped due to
+pins:
+
+```console
+$ vcspull discover ~/code \
+    --recursive \
+    --log-level debug
+```
+
+Both `options.pin: true` (global) and `options.pin.discover: true`
+(per-operation) block discovery. See {ref}`config-pin` for full pin
+configuration.
+
 ## Migration from vcspull import --scan
 
 If you previously used `vcspull import --scan`:

docs/cli/fmt.md

@@ -32,6 +32,38 @@ The formatter performs four main tasks:
 - Consolidates duplicate workspace roots into a single merged section while
   logging any conflicts.
 
+### Pinned entries
+
+Repositories pinned for the `fmt` operation are preserved **verbatim** — no
+normalization, no key reordering, no string-to-dict expansion. For example,
+given this configuration:
+
+```yaml
+~/code/:
+  pinned-dep:
+    url: git+https://corp.example.com/team/pinned-dep.git
+    options:
+      pin:
+        fmt: true
+  libvcs: git+https://github.com/vcspull/libvcs.git
+```
+
+After `vcspull fmt --write`, only `libvcs` is normalized. The `pinned-dep` entry
+keeps its original `url` key and field order:
+
+```yaml
+~/code/:
+  libvcs:
+    repo: git+https://github.com/vcspull/libvcs.git
+  pinned-dep:
+    url: git+https://corp.example.com/team/pinned-dep.git
+    options:
+      pin:
+        fmt: true
+```
+
+See {ref}`config-pin` for full pin configuration.
+
 For example:
 
 ```yaml