The CTX9 workspace and nested CodeFolderSync product are independent repositories. Read both AGENTS.md files, preserve unrelated work, and never stage the child as a submodule. Workspace plans/docs and product source belong in separate commits when commits are requested.
The active product path is src/v3/. src/v2/ is not an acceptable place for new product behavior. The shared versioned installer currently remains in src/v2/service.ts while V2 product routing is removed.
corepack pnpm install
pnpm check
pnpm buildpnpm check runs formatting validation, strict TypeScript, and the complete repository test suite. Test files run serially to bound temporary allocation. For iteration, run the focused V3 file directly, then run the full gate.
When an active acceptance controller depends on the checkout's compiled helpers,
check an exact disposable source copy instead of rebuilding those helpers in
place. Retain the default tsx --test --test-concurrency=1 scheduling.
This changes scheduling, not assertions or corpus.
Count the copied source and every temporary directory against the active budget.
The active CLI loads native SQLite only when opening a database. Backup capture, ciphertext receipt and visibility observation do not need SQLite, and must not emit its Node 22 experimental-module warning. Keep other runtime and backup-tool warnings enabled. The existing backup and observer integration cases enforce clean successful diagnostics and strict rejection of tool warnings.
Large test temporaries may live in an existing private bounded volume, but the
native systemd fixture's paths must remain visible to the host user manager.
Set CODEFOLDERSYNC_TEST_NATIVE_CONTROL_ROOT and
CODEFOLDERSYNC_TEST_NATIVE_CONTROL_RUN_ID to a fresh physical sentinel-qualified
host-visible control root outside Code. The existing systemd test validates that
root, creates only its own small child, and removes its child afterward. Other
tests continue to use TMPDIR. A missing or mismatched supplied sentinel fails
the native fixture, rather than disabling the platform check.
Keep test/product.integration.test.ts at ten tests or fewer. Prefer a complete setup-to-hub-to-adoption-to-apply case over unit tests of private helper shapes or wording.
| Change | Required evidence |
|---|---|
| Recursive scan or ignore | Deep paths, hard exclusions, aliases, unsupported objects |
| Manifest/object | Exact round trip, digest rejection, bounded transfer |
| Authority/enrollment | Target-local key, signed revision, tamper rejection |
| Adoption | Populated target recovery, source zero mutation, force verify |
| Normal merge | Causal concurrent edits and visible exact conflict |
| Directory identity | Deep rename and zero object upload |
| Rename transaction | File/directory cycles plus case and Unicode spelling changes |
| Repository context | Local Git-state preservation, nested scope, races, context advance |
| Protocol | Local/SSH parity, version mismatch, frame and object bounds |
| Durability | Injected source seal, apply, adoption, and cutover restarts |
| Integrity | Corrupt hub object rejected before live mutation |
| Service | Explicit test paths, disabled before cutover, exact uninstall |
| Distributed setup | Exact release, lost response at every remote step, per-target approval |
| Real-snapshot acceptance | Two fresh witnessed copies, deterministic cassette, exact convergence |
| AI coding workload | Real model command, 50 files, eight directories, verified replay, timings |
Automated tests use mkdtemp or a sentinel-qualified run root outside ~/Code. They never use the default config, active user-local binary, daily-driver hub, service label, real backup fixtures, or existing Code folder.
Real fleet acceptance must use the V3 plan's fresh ~/codefoldersync-v3-runs/<run-id>/ shape with an exact sentinel and separate peer, hub, controller, and evidence directories. Canonical masters are read-only inputs and never cleanup targets.
- Does authority or peer signature validation still cover the changed meaning?
- Does the hub sequence remain the only causal order?
- Are all referenced objects durable before acceptance?
- Can an unknown response retry the exact event?
- Is every apply target contained and revalidated?
- Is prior live data moved to recovery first?
- Can startup reverse every prepared journal without guessing?
- Does Git metadata remain local, with context revalidated before capture and apply?
- Is every stable losing version visible or recoverable?
- Does a failure return non-clean status and preserve evidence?
- Do docs and schema/protocol versions describe the executable truth?
A repository candidate requires format, typecheck, tests, build, the focused V3 scenarios, and current CTX9 docs. A daily-driver release additionally requires the active CTX9 branch-policy plan's backup, complete original-archive, real-folder stress, native-machine, and limited-pilot gates. The original recursive-adoption plan remains a requirements source; its whole-Code rollout and Git-mirroring workflow are superseded.
- Types, manifests, or SQLite: data model.
- Scan, adoption, merge, apply, or daemon: sync engine.
- Frames, operations, bounds, retry: protocol.
- Outbox, journals, recovery, retention: durability.
- Trust or filesystem boundary: safety.
- Operator-visible conflicts: conflicts.
- Setup or service behavior: installation and operations.
- Proof workload: scenarios and this document.