# ccync Maintainer Guide

This guide covers the internal mechanics for developers working on ccync. For information on the crate dependency graph (DAG) and data flow, please refer to [`architecture.md`](architecture.md). For details on the command-line interface, see [`manual.md`](manual.md).

## Build, Test, and Lint

```sh
cargo build --workspace
cargo test  --workspace
cargo clippy --workspace
```

The primary executable is `ccync` (defined in the `ccync-cli` crate as `[[bin]] name = "ccync"`). ccync's own application state (config, lockfile, cache, canonical render) lives under the `~/.ccync/` directory; see State Ownership Boundaries below for how that relates to the live agent-config surfaces ccync also writes.

> **Testing Note:** Some `setup::health` tests read machine-local `~/.ccync` state and can be sensitive to your local environment. If you hit a flaky health-check test, check `.dev/plans/` for any active plan tracking it, or the README Roadmap section for known follow-up work.

## Projection Vocabulary Guard

`crates/ccync-engine/tests/projection_vocabulary.rs` enforces the [`naming.md`](naming.md#glossary) glossary on every `cargo test --workspace`. It is the only mechanical enforcement of that glossary — ccync still ships no `naming-gate` CLI command.

**What it scans.** Three roots: `crates/**/*.rs`, `docs/**/*.md`, and the root `README.md`. Symlinks are never followed, `target/` is skipped, and the guard's own source is exempt (it necessarily quotes every allowed token as string data). Adding a new crate source file or a new doc page puts it under the guard automatically — no registration step.

**What it rejects.** Any identifier-like token (a maximal run of `[A-Za-z0-9_]`) that case-insensitively contains the retired projection-domain word, unless the exact pair is in the embedded `ALLOWED` array.

**Granularity is `(file path, matched token)`, not `(file, line).`** Once a pair is allowlisted, every occurrence of that exact token in that file passes. This is a deliberate trade: it keeps the list near 100 entries instead of hundreds of line coordinates, and it still blocks the growth vector that matters — any *new* file or *new* token.

**Adding an allowlist entry.** Add an exact `(path, token)` pair, and justify it in one line in the commit message. It must fit one of four reviewed categories:

1. a legacy config-key boundary spelling (`selectedRuntimes` / `primaryRuntime` / old-layout `runtimes` — read forever, never renamed);
2. a pre-existing engine/CLI identifier outside the rename's blast radius (the earlier chains renamed the projection-domain *type* model, not every function and test name);
3. a literal quote of a live CLI output string;
4. genuine execution-environment or third-party meaning (C `Runtime` linkage, `VCRUNTIME140.dll`).

The bare-word entries already in `ALLOWED` (e.g. `("crates/ccync-engine/src/install.rs", …)`) are **grandfathered**, not a pattern to copy: admitting them per-file was the only way to seal the guard without a repo-wide rename. Widening an existing bare-word entry to a new file needs the same scrutiny as a rename.

**The guard cannot pass vacuously.** `assert_scan_roots_exist` fails if any of the three scan roots is missing, and `MIN_SCAN_HITS` is a conservative floor (set well below the real token count) so a scan that silently found nothing — unreadable root, `repo_root()` resolving outside the checkout — fails loudly instead of reading as clean. A companion test seeds a synthetic violation, and another rejects duplicate `ALLOWED` entries, so the detector and the list are both proven sound.

**If it fires:** rename the token per the glossary map first. Allowlisting is the exception, not the default fix.

## Component Locations

| Concern | Crate / Module |
| --- | --- |
| Core paths (`~/.ccync/...`) and configuration | `ccync-foundation` (`paths.rs`, `config.rs`) |
| Catalog resolution to lockfile | `ccync-engine::catalog` |
| Personal plugin fetching (Git cloning, pinning) | `ccync-engine::install` (`fetch_*personal*`) |
| Projection / sync orchestration (internal "update" of derived state via `install::run_update` — distinct from the public `ccync update` self-update verb) | `ccync-engine::install` and `ccync-cli::commands::lifecycle` |
| Binary self-update (`ccync update`) and git-plugin upgrade (`ccync upgrade`) | `ccync-engine::{self_update, plugin_upgrade}` and `ccync-cli::commands::{update, upgrade}` |
| Cross-agent adoption (master-agent state → ccync truth store, `_mcpServers` snapshot) | `ccync-engine::adopt` and `ccync-cli::commands::init` |
| Adopted-item source discovery/lookup/repair-tip seams (`ccync search`/`ccync repair`/`ccync upgrade` share this) | `ccync-engine::adopt` (`adopted_items_without_source`, `find_adopted_item`, `write_adopted_source`) |
| Public repository discovery (`ccync search`) and adopted-item source repair (`ccync repair`) — CLI-first, no engine-level network module | `ccync-cli::commands::{search, repair}` |
| Per-agent projection and managed artifact tracking | `projection` (`ManagedArtifactRegistry`, per-agent serializers) |
| MCP host configuration and live-path enumeration | `mcp`, `ccync-engine::install::generate_managed_mcp` |
| Management health checks aggregated into `ccync doctor` | `setup` (`health` module only — the former interactive session-selection seam was removed) |
| Command dispatching | `ccync-cli::main` (utilizing `CommandKind` in `ccync-engine::lib`) |
| Argument discipline (unknown-flag / extra-positional rejection) | `ccync-cli::commands::args::reject_unknown_flags` |

**Argument discipline (every verb).** Each `cmd_*` handler must call `commands::args::reject_unknown_flags` at its entry, passing its exact allowed flag set, value-bearing flags, and positional cap. This is what makes `docs/manual.md`'s "invalid flag → exit 64" contract true and prevents silent-ignore bugs (a `remove <id> --dry-run` that ignored the flag and performed a real delete). The helper handles both `--flag value` and `--flag=value` forms and treats any single-dash token as a flag. **When adding a new verb, wire the guard** — the `all_verbs_reject_unknown_flag_as_usage` canary test (iterating `CommandKind::ALL`) is a smoke-net, but the authoritative coverage is a per-verb unknown-flag test.

## The Projection Engine

The `projection` crate is the core mechanism enabling ccync's "install once, project everywhere" capability. Its key components include:

- **Per-Agent Serializers:** These write a plugin's skills, commands, and agents into each agent's specific native directory structure (e.g., `~/.claude/skills/<name>`, `~/.copilot/skills/...`, Codex's `~/.agents/skills`, and the native locations for Antigravity, Gemini, and OpenCode).
- **`ManagedArtifactRegistry`:** Located at `~/.ccync/build/lock.json#_ccyncProjection` and featuring per-source attribution, this registry tracks the exact paths created by ccync. This guarantees that pruning operations only delete ccync's own artifacts, never user-created or third-party files. The `can_mutate()` safety guard provides fail-safe protection (if no prior lockfile exists during the first run, it falls back to a content-marker check).
- **Core-Wins Collision Policy:** If collisions occur, the earliest loaded source takes precedence. Subsequent conflicting entries are skipped, and a warning is logged.

### Two-Row Ownership and the Prune Authorization Ladder

`_ccyncProjection` records each projected path **twice**: once as a member of a managed-artifact category (`skillProjectionPaths`, `commandProjectionPaths`, …) and once as a `sourceAttribution` row naming its owning source. The two rows are written by different code paths and can desynchronize, so neither is by itself a proof of ownership:

- A **category row without an attribution row** is the pre-attribution shape (a lockfile written before attribution tracking, or a path recorded through `mark` rather than `mark_with_source`). `owning_source_of` returns `None`, which must fall through to normal authorization — never be read as "foreign", or every legacy entry becomes unprunable.
- An **attribution row without a category row** is an orphan: the path was pruned or replaced somewhere that did not clear its attribution alongside it. `ManagedArtifactRegistry::persist` garbage-collects these, but only for sources installed this pass; a foreign source's orphan is retained because this pass has no authority to judge it. The GC runs **before** persist's `prior == next` equality short-circuit, or an orphan-only change would be short-circuited away and never written.
- A **false attribution row** is the dangerous shape: a path recorded as ccync-owned that ccync never actually created. `ensure_dir_link` returns `bool` precisely to prevent it — `false` means a genuine user-owned directory was preserved untouched, and every call site guards `mark_with_source` on that return. An unconditional mark after a preserve is what writes a user's own directory into ccync's ownership records.

Deletion authority is a ladder, tried in order: a ccync content marker on a real path; a symlink whose target is proven to resolve inside its attributed owner's root; a symlink whose path appears in a prior category row (`can_mutate`); a plain file recorded as managed (`is_managed`). The second rung exists only for orphan symlinks and is deliberately limited to symlinks — it authorizes removing the link itself, never anything the link points at. Its dangling-target case reads the raw `read_link` value and requires it to be absolute and free of `..` components, and compares it to the owner root **without** canonicalizing, because on Windows `canonicalize` yields a `\\?\` verbatim path that would never prefix-match the caller's plain root.

### Bundle-Uninstall Forward Contract

`installed_source_ids` (built from `ctx.opts.sources` / the `sources` passed into `prune_stale_links`) is the full currently-installed source list for a projection pass — not "installed before this uninstall." A source being uninstalled must still appear in it, with zero `keep_names`, during its own final projection pass.

This is why stale-link pruning and attribution GC treat that pass's own entries as ordinary (unprotected) instead of foreign: `prune_stale_links` only skips a path when its recorded owner is foreign — attributed to a source absent from `installed_source_ids` entirely, meaning the pass has no authority over it. Dropping the removed source out of `installed_source_ids` early would make its own stale entries look foreign and leave them stranded on disk instead of pruned. The same list feeds `ManagedArtifactRegistry::persist`'s orphan GC, which likewise only retains attribution rows owned by a source outside `installed_source_ids`.

## Catalog → Lockfile → Cache Pipeline

1. The central catalog, `plugins/catalog.json` (which contains curated `git-clone` companion entries and profiles), serves as the single source of truth. It is embedded directly in the binary via `include_str!` at compile time; catalog resolution reads the embedded copy directly — there is no disk-deploy step, and no `~/.ccync/plugins/ccync/catalog.json` file is ever written.
2. The catalog resolver (which runs internally during `ccync sync`) merges the embedded catalog, machine configuration, and the personal catalog (`~/.ccync/plugins.json`) into `~/.ccync/build/lock.json`. To prevent corruption, resolver keys are safely spliced into the lockfile without overwriting `_ccyncProjection` or other isolated namespaces.
3. When `ccync add` is executed, it clones Git repositories into `~/.ccync/cache/<id>@<sha>/`, pins them by their specific commit, and records the entry under the `_personalPlugins` section of the lockfile.

## First-Run Overwrite Visibility Gate

Before writing to any live agent configuration file on a new machine, `run_unified_projection(dry_run: bool, assume_yes: bool, skip_first_run_gate: bool, gate_abort_context: Option<&GateAbortContext>)` (located in `crates/ccync-cli/src/commands/lifecycle.rs`) verifies the existence of `_ccyncProjection` in the lockfile.

If it is absent (indicating a first-run scenario), the engine builds a read-only `TouchScope` via `build_touch_scope` and **prints the grouped touch-scope disclosure unconditionally**. The disclosure is not gated on `skip_first_run_gate` — only the *confirmation prompt* that follows it is. `skip_first_run_gate == true` (init's case) suppresses the prompt and nothing else, so `init` gains visibility without gaining a second prompt.

**The disclosure is two groups from two different owners, not one flat list.** This split is a truth claim, not formatting:

| Group | Rendered label | Path owner | Scope |
| --- | --- | --- | --- |
| Selected agent surfaces | `Runtime surfaces (would touch, current selection):` | `ccync_engine::install::planned_engine_touches` | Varies with the config's agent selection |
| Fixed MCP host files | `MCP host files (may be written; skipped when already identical):` | `mcp::live_mcp_target_paths()` | The fixed four hosts, independent of agent selection |

The two verbs differ because the guarantees differ. Agent surfaces are a **preview** ("would touch" — the live CLI label, quoted verbatim above, still reads `Runtime surfaces`; renaming that literal string is a code change out of this plan's scope) — `run_unified_projection`'s `projection::run_machine_update` call is best-effort per target, so a listed surface may end up untouched; a genuine machine-phase fault is reported to stderr and folded into an `Error` exit by the engine-owned run accumulator (see [`architecture.md`](architecture.md#projection-run-evidence-and-status-authority)), it is no longer swallowed into a success exit. MCP hosts are "**may be written**" — `write_json_provider_delta` returns `Unchanged` (bytes *and* mtime preserved) on a semantic no-op, so a converged machine writes none of those four paths. Neither group may claim more than it can prove.

`render_touch_scope` is the single renderer for all three consumers — the `--dry-run` report, the generic first-projection confirmation gate, and `init`'s pre-projection disclosure — so the same scope can never be formatted two different ways. A CLI-local second target-to-path table would violate this contract: the disclosure planner must reuse the engine/projection path owner.

The confirmation prompt, when it runs, awaits explicit user confirmation. In non-TTY environments it requires the `--yes` flag or the `CCYNC_ASSUME_YES=1` environment variable; if neither is provided, the write is aborted **before any live-surface write and returns `ExitCode::Error` (exit `1`)** — distinguishable from a full success — after printing a truthful three-part summary from `gate_abort_context`: which ccync state was *already written*, which surfaces were *not written*, and the `ccync sync --yes` next step. The abort message deliberately never claims "no files written" — that literal phrasing is delegated to `--dry-run` output only, and even there it is narrower than it reads: it covers live-surface writes, not the one-time internal layout migration that always runs first and is not gated by `--dry-run` (see [`manual.md`](manual.md#ccync-sync---dry-run---yes)).

Subsequent runs bypass this gate because the lockfile will now contain the `_ccyncProjection` key.

Division of labor across the four lifecycle commands: `sync`, `add`, and `remove` all share this gate as-is (`remove` needs `--yes` to bypass it non-interactively, same as `sync`/`add`); `init` passes `skip_first_run_gate=true`, which skips **only the confirmation prompt** — it still prints the same grouped disclosure, because it already showed its own agent-selection UI before calling `run_unified_projection` and that UI is the intent signal; `upgrade` runs the gate but passes `assume_yes=true`, so it always auto-confirms without prompting. Because the surfaces already written before the gate differ per verb, each caller passes its own `GateAbortContext` constant (`SYNC_`/`ADD_`/`REMOVE_GATE_ABORT_CONTEXT`) so the abort summary is truthful: `sync` has updated the lockfile/resolved state; `add` has updated cache + personal catalog + lockfile; `remove` has additionally already run the canonical render. `add`'s live-surface render/projection happens strictly *after* the gate passes — a declined gate leaves those command-specific catalog/cache/lockfile writes in place but produces zero live-surface writes.

## Cross-Agent Adoption

Running `ccync init [<claude|codex>]` reads the installation state of the specified master agent. It adopts any non-managed items into the ccync lockfile, records the `_adoptMaster` key, and subsequently executes the unified projection engine. Configuration writes are atomic, and any native entries unrelated to ccync within the agent's configuration are carefully preserved. This entire process is idempotent.

### Adopted Source Recording

Adopted items are written into three isolated namespaces inside `~/.ccync/build/lock.json`:

- **`_adoptedItems`** — marketplace plugins discovered in the master agent's live config. Each entry carries a `sourceId` field — an agent-and-kind tag such as `claude-skill` or `claude-mcp` (written by `adopt::source_id`) that identifies which secondary namespace it also occupies: a `skill`-tagged entry has a corresponding entry in `_looseSkills`, an `mcp`-tagged entry in `_mcpServers`. Each entry also carries `name`, `origin: "adopted"`, an optional `source` (a resolvable clonable reference — from catalog resolution at adoption time, or written later by `ccync repair`; absent when unknown), and, for marketplace plugins, a `baselineVersion` snapshot taken at adoption time.
- **`_looseSkills`** — free-standing skill directories found in the master agent's skills surface but not traceable to any catalog entry. Each entry records the raw source path so ccync can re-materialize the directory into the canonical root during sync.
- **`_mcpServers`** — MCP server entries from the master agent's configuration. Stored as a key-value map; keys match the agent-side MCP server identifiers.

The `sourceId` field links an `_adoptedItems` entry to its secondary namespace: `ccync engine::adopt::remove_adopted_item` reads `sourceId` to determine which secondary namespace to also clear when the item is removed via `ccync remove`.

**Filling a missing `source` after the fact.** `ccync init` resolves a plugin's `source` from the local marketplace catalog when it can (`read_marketplace_plugin_source`), but that resolution can miss (unknown marketplace, missing local clone, plugin absent from the catalog) or simply not apply (MCP servers and loose skills have no marketplace catalog at all). `ccync repair [<id>]` is the dedicated follow-up for that gap: it writes a user-confirmed `source` onto an existing `_adoptedItems` row via `adopt::write_adopted_source` (a unique-name, fail-closed atomic write — see [`architecture.md`](architecture.md#ccync-repair--layering-and-the-metadata-enrichment-boundary)), independent of `ccync init`/`ccync sync` and without triggering a projection. `adopt::adopted_items_without_source` is the shared seam that both `ccync repair`'s batch mode and the `upgrade`/`list --upgrade-available`/`init` repair-tip all read.

### Loose-Skill Materialization

During `ccync init`, after the `_adoptedItems` / `_looseSkills` snapshot is written, `adopt_loose_skills` runs to copy each loose skill directory into the canonical root (`~/.ccync/build/render/skills/`). This makes adopted loose skills immediately visible to every downstream agent without an extra `ccync sync` step.

`adopt_loose_skills` is a pure copy step — it never modifies the source agent's skill directory. On subsequent `ccync sync` calls the canonical root is rebuilt from the lockfile, so loose skills re-materialize from the `_looseSkills` snapshot automatically.

## State Ownership Boundaries

- **Reproducible from Source:** This repository itself (via `git clone` and `cargo build`).
- **Rebuildable Output State:** The `~/.ccync/build/` directory. `ccync sync` recreates the *content* every file under `build/` should hold — but `build/lock.json`'s init adoption snapshots (`_adoptedItems` / `_mcpServers`) are not re-derivable this way (`sync` never re-queries a master agent; only `ccync init` does), and `build/mcp/{managed,projected-state,projection.txn}.json` carry MCP-ownership proof whose *loss* (not their bytes) matters for recovery — see the exceptions in the next bullet and [`manual.md`](manual.md#machine-layout).
- **Machine-Local Input State:** `~/.ccync/config.json` and `~/.ccync/plugins.json`. Never auto-deleted by ccync. `ccync backup` / `ccync restore` target both INPUT files **plus one exception from the OUTPUT class**: `build/lock.json` (backed up as `plugins.lock.json`), because it carries the init adoption snapshots (`_adoptedItems` / `_mcpServers`) that cannot be regenerated from the INPUT files. The rest of `build/` and all of `cache/` stay out of the backup set.
- **Rebuildable Cache:** `~/.ccync/cache/`. Rebuildable from network/source but may require connectivity.

**Source-of-truth vs live-surface boundary:** ccync's own state (config, lockfile, cache, canonical render) lives entirely under `~/.ccync/`, and that tree is where `backup`/`restore` operate. But ccync also *projects* that state onto each selected agent's live config surface outside `~/.ccync/` — `~/.claude/skills/...`, `~/.claude.json`, `~/.codex/config.toml`, `~/.copilot/mcp-config.json`, and equivalents for the other supported agents. Writing to those live surfaces is the entire point of "install once, project everywhere"; it is gated by the First-Run Overwrite Visibility Gate above and tracked by `ManagedArtifactRegistry` so ccync only ever touches artifacts it created.

## Release Architecture

Details regarding the build, signing, and publishing processes—including binary-only archives, the GitLab-to-GitHub split, `release.yml`, cosign keyless integration, winget/Homebrew manifests, and submission gates—are comprehensively documented in [`release.md`](release.md).

## Known Deferred Work

Where follow-up work lives, by altitude:

- **Product-level, user-visible** → the README Roadmap section (e.g. Windows clean-machine acceptance, which is hardware-gated).
- **In-flight** → `.dev/plans/` active plans.
- **Maintainer-level engineering backlog** → this section. Items land here when the plan that found them closes: a plan file is deleted at lifecycle close, so anything still owed must be recorded somewhere durable first. Each item is self-contained (file:line + why it was deferred) so a later plan can act on it without the originating conversation. There is still no standalone deferred-work file.

- **Resolved:** Projection previously required a source-checkout engine; this has since been resolved — see the README Roadmap section for the universal-installer follow-up scope.
- **Resolved:** `ccync doctor`'s canonical-root staleness check previously flagged the dynamically rendered canonical root as anomalous on every run (a no-op false positive). This has been fixed: `ClaudePluginCacheCheck` now receives the real canonical root (`canonical_plugin_root()`) and its staleness check is a genuine, non-no-op health signal.

### Open engineering backlog

Recorded at the close of `fix-fresh-user-audit` (2026-07-16). None are release-blocking; each needs its own plan.

1. **`irm | iex` clobbers caller variables and functions.** `packaging/install.ps1:29-30` assign `$Repo`/`$InstallDir` at script scope, which under `iex` *is* the caller's scope; the file also defines 9 functions into the caller's session (proven: function count 45→53; a caller's own `Write-Info 'probe'` printed `ccync-install: probe` after `iex`). The installer-preference contract (preferences do not leak) is met — this is beyond its text. The fix is to wrap the file body in `& { ... }` or prefix all names; deferred because it reworks the structure that was just stabilized and endorsed.
2. **Codex `toml_string` control-character escaping gap.** `crates/mcp/src/serializers/codex.rs:141-144` escapes only `\` and `"`; a resolved value containing a control character renders unparseable TOML. Fail-closed (the fingerprint fires during planning, before any write), but such a user can never sync at all.
3. **Codex uninstall does not consult `unaddressable`.** `crates/mcp/src/lib.rs:970-997` — `run_mcp_remove_managed_inner` calls `write_codex_delta` for every owned name. If a user restructures `~/.codex/config.toml` into an inline `[mcp_servers]` key after ccync committed ownership, the line-based writer strips nothing, returns `Ok`, uninstall reports `hosts_updated: [codex]`, then deletes `projected-state.json` — stranding the entry permanently. Pre-existing; the `unaddressable` concept that would close it exists but is applied only to the projection path.
4. **`write_json_provider_delta` inserts `"mcpServers": {}`** into a `~/.claude.json` that lacks the key, rewriting (and, with `serde_json` lacking `preserve_order`, reordering) the file once even with an empty desired manifest. Pre-existing; compounds the `preserve_order` item.
5. **`write_atomic`'s fixed `<dest>.tmp` sibling** collides between concurrent processes writing the same destination — belongs with the file-locking backlog item.
6. **Unbounded in-RAM tree load in the snapshot walker.** `collect_dir_snapshot` (`crates/ccync-engine/src/install.rs:643-687`) holds the entire tree in memory (`Vec<(String, Vec<u8>)>`) with no size cap and no ignore list; the plain-directory source is exactly where `node_modules`/`target/` live. Deferred because a streaming fix must preserve the read-once/hash-and-copy-the-same-bytes property that makes the walker TOCTOU-free — a design task, not an edit. Failure mode is loud (OOM/thrash), not silent data loss.
7. **Dead second author-facing `.mcp.json` reader in the Protected Path.** `crates/projection/src/lib.rs:167-189` `decompose_plugin` accepts only `"servers"`, violating the one-author-facing-reader rule (see [`architecture.md`](architecture.md#author-facing-vs-internal-mcp-keys)). It is dead code (no production caller) inside `crates/projection/` (a Protected Path), so deleting it or repointing it to `read_author_mcp_servers` needs its own plan with a recorded architect review.
8. **Empty directories invisible to the snapshot.** The walker (`crates/ccync-engine/src/install.rs:669-670`) neither hashes nor recreates empty directories, so two trees differing only by empty dirs share a cache key and the snapshot silently drops them.
9. **Temp-dir prefix collision in `fetch_personal_plugin`.** `crates/ccync-engine/src/install.rs:447` treats any cache entry matching `starts_with("<id>@")` as `AlreadyPresent`, which can match `@__copying__`/`@__fetching__`/`@__extracting__` staging residue left by a hard kill. The snapshot fetcher's own path is more careful (exact `target.exists()`); align the incumbents with it. This is distinct from the *intended* short-circuit on this same prefix — a genuine, already-populated `<id>@<sha>`/`<id>@<sha256-first12>` cache dir correctly skips re-fetch/re-extraction for Git, archive, and plain-directory sources alike; only the staging-residue false positive above is the debt.
10. **Copilot-agents deselect-cleanup asymmetry.** Deselected `gemini`/`opencode` commands get cleaned via else-branches; deselected copilot agents do not — their files are left in place. Fail-safe (leaves files rather than deleting them), but asymmetric. Needs its own architect-reviewed prune change, since it is a prune/registry/mutation-authorization change.
11. **Render / managed-MCP failures still exit 0 with a warning.** Pre-existing best-effort contract. Now that the ownership model makes data loss impossible, the remaining harm is staleness only — but the exit code is still not truthful about it.

Recorded at the close of the docs-vs-implementation reconciliation plan (2026-07-21). Documentation-only fixes landed in this plan for all three; the underlying code/behavior gap each describes remains open.

12. **Refresh/sync timestamp non-determinism has no regression coverage.** The per-target lifecycle writers driven by `apply_lifecycle_artifact_chain` (`install.rs`) stamp a fresh `"generatedAt"` into each target-state manifest on every write, so two successive `ccync refresh`/`ccync sync` runs are content-idempotent but not byte-identical — yet nothing tests this boundary. `refresh_with_writes_canonical_and_is_idempotent` (`refresh.rs`) only compares `(relative_path, file_size)` pairs per file, which cannot detect a timestamp-only content diff. Evidence: `install.rs` `"generatedAt": chrono::Utc::now().to_rfc3339()` call sites; `refresh.rs`'s `dir_snapshot`/`collect_dir` test helpers. Owner: unassigned — needs its own plan. Status: open (docs corrected in this plan; code/test gap unchanged). Remediation: add a regression test that explicitly documents the timestamp exception (e.g. asserts every *other* byte is identical), or make the manifest timestamp stable when nothing else in the render changed.
13. **`devMode`/`ccyncRoot` are parsed but functionally dead.** The config model still parses and round-trips both fields, but `run_update`'s mode string is hardcoded to `"normal"` (`install.rs:538-540`) — no production code path reads either field to change behavior. Evidence: `install.rs:538-540`. Owner: unassigned. Status: open (docs now label both fields inactive, this plan; the fields themselves are still accepted input). Remediation: either remove both fields (a config that already sets them today observes zero behavior change either way) or reinstate a real dev-mode code path if the split is still wanted.
14. **`ccync doctor --dry-run`/`--release-gate` are accepted but no-op.** `doctor.rs` parses both flags; `run_doctor` discards them unconditionally (`let _ = opts.dry_run; ... let _ = opts.release_gate;`, `crates/ccync-engine/src/doctor.rs:34,62`) — no check varies by either flag today. Evidence: `crates/ccync-engine/src/doctor.rs:34,62`. Owner: unassigned. Status: open (docs now disclose the no-op, this plan). Remediation: either wire `--release-gate` to a stricter CI-oriented check set (its apparent original intent) or remove both flags from the CLI surface.

Recorded at the close of the same plan (2026-07-22), from a defect the landing gate caught in the plan's own output.

15. **Rust identifiers cited in prose have no continuous existence guard.** `crates/ccync-engine/tests/projection_vocabulary.rs` guards *vocabulary* tokens across `crates/`, `docs/`, and `README.md`, but nothing checks that a function or type named in documentation prose still exists in the tree. Both failure directions have already occurred: `docs/architecture.md` cited `write_surface_lifecycle_artifacts` from 2026-07-03 and went silently false when that symbol was retired for `apply_lifecycle_artifact_chain` on 2026-07-19; `docs/devguide.md` then acquired two fresh citations of the same already-retired symbol on 2026-07-22. Neither was caught by `cargo test --workspace` — only by the landing gate, which harvests plan evidence prose rather than `docs/`. Evidence: retirement commit `ad94a481`; the surviving explanatory comment at `crates/ccync-engine/src/install.rs:4056`. Owner: unassigned. Status: open (all three citations corrected 2026-07-22; the missing guard is unchanged). Remediation: extend the vocabulary guard, or add a sibling test, to resolve backticked `snake_case`/`CamelCase` identifiers appearing in `docs/`+`README.md` against declarations under `crates/`, with an allowlist for the many legitimate non-Rust backticked tokens (config keys, JSON fields, CLI flags).

16. **Lockfile mutations in `adopt.rs` are non-atomic except the newest one.** `crates/ccync-engine/src/adopt.rs` rewrites `build/lock.json` from four sites (adoption write-back, loose-skill materialization, MCP snapshot, and `remove_adopted_item`) through a plain `std::fs::write`, which truncates the destination before writing — a crash or a full disk mid-write leaves a truncated lockfile carrying the non-rebuildable `_adoptedItems`/`_mcpServers` adoption snapshots. `write_adopted_source` (added by `ccync repair`) is the module's only caller of `ccync_foundation::platform::atomic_write_bytes` (tmp + rename). The inconsistency is not merely cosmetic: `docs/architecture.md` and `docs/manual.md` both asserted, until this plan's landing review, that repair used "the same primitive the rest of ccync's lock-file mutations use" — the uniformity reads as true from any single call site. Evidence: `adopt.rs` `std::fs::write` sites vs. its single `atomic_write_bytes` call. Owner: unassigned. Status: open (the two false doc claims corrected at this plan's landing; the four non-atomic write sites unchanged). Remediation: route every `adopt.rs` lockfile write through `atomic_write_bytes`, in its own change — each site has its own error-path and test surface, and `backup`/`restore` treat this file as the one non-rebuildable OUTPUT.

Recorded at the close of `chore-remove-ledger-residue` (2026-07-27), from a defect that plan's own landing review caught.

17. **Line-granular grep allowlists hide a retired concept's surviving clause.** Retirement plans in this repo express their acceptance as "`grep -n <concept> <file>` matches only the allowed lines" — but the allowlist unit is a *line*, while the stale prose unit is a *clause*. `docs/manual.md:56` was allowlisted wholesale because its "any legacy `ledger.json`" clause stays true after the retirement; the same line's trailing "No uninstall ledger is written." survived the entire nine-task plan and every per-task audit, and is only true in a world where some *other* operation still writes one. Nothing mechanical can see this: the line is on the allowlist, so its full text is never re-read. The same shape is available to every prior retirement here (`dist/runtimes/`, `install-state.json`, the `gal`→`ccync` rename), each of which left surviving legacy-cleanup mentions on allowlisted lines. Evidence: the removal landed at this plan's landing review as `6188d2bf` (+ mirror `575f5f2f`), not during the manual-update task that rewrote the rest of that file. Owner: unassigned. Status: open (this instance corrected; the acceptance-criterion shape unchanged). Remediation: state retirement acceptance at clause granularity — for each allowlisted line, assert *what* the surviving mention says, not merely that the line is permitted to mention it — or have the landing review re-read the full text of every allowlisted line rather than the grep summary.

18. **A line-number-anchored allowlist drifts silently when the file above it changes.** Probe 1 in `packaging/test-release-artifacts.sh` used to allowlist this file's one deliberate mention of the retired project name by pinning `DEVGUIDE_ALLOWED_LINE` to an ordinal line number and stripping an exact phrase from that line before re-checking. This was clause-granular (the remedy item 17 above prescribed) but positionally fragile: inserting or deleting any line above the pinned number shifted the target. The common case was fail-closed and loud — the real mention moved off the pinned line and the probe went red — but there was a silent case, where whatever sat on that line carried its own mention of the retired name and got allowlisted without anyone asking for it. Evidence: introduced by `e91fa0d7` during the `chore-degal-residue` guard-hardening work; the drift itself resurfaced live during the `feat-release-chain-parity` plan's own release-smoke test run (the phrase had moved to line 189 by the time that plan started, while the probe was still pinned to 173, so the probe was already red before this item was fixed). Owner: unassigned. Status: **closed** (`feat-release-chain-parity`) — the allowlist now matches the exact phrase wherever it appears in the file, with no line number involved at all, so it survives edits anywhere above or below it.
19. **The two residue probes disagree about whether the generated agent-instruction adapters are in scope.** Probe 1's scan root is `crates/` plus `docs/` plus five explicit packaging files; the eight tracked adapter files at the repo root and under the dot-directories are kept out on purpose, because they are regenerated tooling output and scanning them would turn the harness red after every regeneration. Probe 1b, added to the same harness in the same plan, iterates `git ls-files` and excludes only `.dev/**` — so those same eight adapters *are* in its scan root, against the rationale stated one probe above it. This is latent rather than active: the adapters carry zero plan-ID matches today. It becomes real the moment a regeneration copies a plan-ID-bearing line out of `.dev/project.md`, which still carries several such references in its own prose — at which point the harness goes red over content this repo cannot durably edit, since the next regeneration overwrites it. Evidence: `6eb4565d`, the `chore-degal-residue` commit that added the second probe; exposure measured at that plan's landing review — 8 tracked adapters, 0 current matches. Owner: unassigned. Status: open. Remediation: pick one scan root for both probes — either exclude the adapter paths from Probe 1b the way Probe 1 excludes them, or bring them into both and accept the regeneration coupling; do not leave the two probes disagreeing about the same files.

### Carried verification condition — unix walker arm is NotRun

The snapshot walker's two `#[cfg(unix)]` tests and its **non-Windows production arm** have never compiled or run anywhere: ccync's development box is Windows-only and a cross-target check was attempted and blocked. They were reviewed by reading and judged compile-plausible and low-risk, but they are labelled **NotRun, not pass** — an unexercised arm is not a passing arm. They are owed exactly one unix run (CI or WSL). Do not treat the walker's unix path as verified until that run exists.

### Known partial satisfaction — MCP `--dry-run` reporting

`ccync sync --dry-run` inspects and reports MCP state, but only *half* of what the originating requirement asked for. This is a recorded architectural limit, not an oversight:

| Half | Status | Notes |
| --- | --- | --- |
| Never write / commit / clear ownership, transaction file, or live config | **Satisfied** | Substantively, not vacuously — dry-run performs a real read-only inspection of MCP/live-surface state (the one-time internal layout migration is a separate, unconditional step that always runs first — see the dry-run caveat above) |
| Report legacy bootstrap and pending transaction | **Satisfied** | |
| Report planned deletion and collision | **Not satisfied** | Reported explicitly as "not determined (requires render)" rather than as an empty list |

The reason is structural. Planned deletions and collisions come from `planner::plan_host`, which needs `desired` — and `desired` exists only *after* the render (`crates/mcp/src/lib.rs:714-726`). The render is `ccync_engine::install::run_update`: the whole projection, which writes live surfaces like `~/.claude/skills/ccync`. A dry run that called it would no longer be a dry run. `generate_managed_mcp` cannot be reused standalone either — its core input is the `canonical_root/.mcp.json` that `render_canonical_root` writes, and it unconditionally writes `managed.json`. The only code that computes the desired MCP set lives in `render_canonical_root`, inside the Protected Path `crates/projection/`.

Closing this requires a new pure-function `desired_manifest(config)` seam that merges plugin/bundle/adopted MCP in memory — a cross-crate refactor touching a Protected Path, which needs its own plan and its own architect review.

Reporting "not determined" rather than an empty list is deliberate: an empty list would be a false claim of "nothing to delete, no collisions", which is exactly the kind of unproven assertion the MCP ownership model exists to prevent.

## Internal Developer Tooling

These commands are dispatchable but intentionally absent from `ccync --help`. They are for use by ccync maintainers only and are not part of the public product surface.

### `ccync refresh`

Rebuilds the derived layer from existing `~/.ccync` state without running the full public `sync` lifecycle. Internally calls the same projection core as `sync` (canonical render + machine projection + MCP projection), but skips the first-run gate, catalog resolve, and interactive prompts.

- Content-idempotent, not byte-identical: re-running with unchanged state re-renders the same components, but the per-target lifecycle writers driven by `apply_lifecycle_artifact_chain` stamp a fresh `"generatedAt"` timestamp into each target-state manifest on every run (`install.rs`), so successive runs are not byte-for-byte identical even when nothing else changed.
- Does not modify `~/.ccync/config.json` or `~/.ccync/plugins.json` (machine-local INPUT files).

Use case: after editing source, quickly materialize changes to local machine state for observation or testing without going through the full managed-catalog pipeline.

### `ccync rollback [--yes]`

Rolls back the ccync source repo to the latest stable release tag (`v*`), creates a backup branch, then rebuilds derived outputs via `refresh`.

**Prerequisites:**

- Must be run from inside the ccync source repo (fingerprint: `Cargo.toml` + `crates/ccync-cli` + `plugins/catalog.json`).
- At least one stable release tag (`v*`, prereleases like `-rc` excluded) must exist. Until one does, `rollback` safely fails closed (returns an error, no mutation).

**Guards (all must pass):**

1. `is_ccync_source_repo()` fingerprint check.
2. Fail-closed resolution of the latest stable release tag, verified to be an ancestor of HEAD — a tag on a divergent branch is refused, to avoid a sideways `git reset`.
3. Discard scope output (shows uncommitted count and commits ahead of the target tag).
4. `--yes` flag required (without it, returns `Usage` with zero mutation).

**Rollback sequence (A-semantics):**

1. Create backup branch `ccync-rollback-backup-<timestamp>` pointing at current HEAD.
2. `git reset --hard <release-tag>`
3. `git clean -fd`
4. Chain `ccync refresh` to rebuild derived layer.

> **Note:** `rollback` is distinct from the public `ccync restore --from <dir>`, which restores machine-local INPUT files from a backup directory and does not touch the source repo.

> **Ownership note:** ccync only manages files that carry its content header (`# Generated by CCYNC Setup-Machine…`). Any agent file without that header — including legacy agent files left over from a pre-carve install — is treated as user-owned and is **never** removed by ccync; no migration or sync deletes it. This is by design and permanent (not a temporary migration gap): clean up such leftover files manually (`rm`) if you no longer want them.

## Contributing

For guidelines on contributing to the project, please review [`contributing.md`](contributing.md).