cds-ai/cdssync/AGENTS.md

AI Agent Instructions for cdssync

These instructions apply anywhere under /home/aw/code/cds/cdssync.

Migration Test Dataset Workflow

For migration test datasets in this workspace, follow this process by default:

1. Generate the dataset locally from this workspace.
2. Preserve the local generated dataset as the canonical original copy.
3. Copy the dataset to the test machine using metadata-preserving tooling.
4. Verify the copied dataset on the test machine before using it for migration testing.

Generation Rules

• Use /home/aw/code/cds/cdssync/generate_migration_test_dataset.sh to create the dataset unless the user explicitly asks for a different method.
• Prefer /home/aw/code/cds/cdssync/migration-test-dataset as the local canonical dataset location unless the user specifies another target.
• The generator script accepts an optional UPDATE_INTERVAL_SECONDS argument:
  • omit it to create the dataset once and exit
  • use 0 for continuous random content updates
  • use any integer greater than 0 to rewrite mutable files every N seconds
• The generator script also accepts --update-only:
  • use it to update an existing dataset in place without recreating files, links, or directories
  • combine it with UPDATE_INTERVAL_SECONDS to keep mutating an existing dataset on a fixed interval
• The generator script can also create additional bulk test data under bulk/:
  • --folder-count N controls how many bulk folders are created
  • --files-per-folder N controls how many bulk files are created in each folder
  • --min-file-size-mib N and --max-file-size-mib N control the random size range for bulk files
  • --max-dataset-size-mib N caps the total size of generated bulk files only
  • once bulk files exist, update mode rewrites them too as part of the mutable-content set
• If ACL/xattr coverage matters, ensure the generation host has:
  • acl installed for setfacl and getfacl
  • attr installed for setfattr and getfattr

Copy Rules

• Use rsync -aHAX by default when copying the dataset to another machine.
• Preserve permissions, timestamps, symlinks, hard links, ACLs, and xattrs.
• Do not use GUI copy/paste or non-preserving copy methods for this dataset unless the user explicitly asks for that.

Verification Rules

After copying to a test machine, verify at least:

• file and directory structure
• permissions
• symlinks
• hard links
• timestamps
• ACLs
• xattrs

Preferred verification commands include:

• find DEST_DIR | sort
• stat DEST_DIR/regular/script_3mb_700.sh
• stat DEST_DIR/readonly-dir/locked_text_1mb_444.txt
• readlink DEST_DIR/links/symlink_to_text_1mb_644.txt
• stat DEST_DIR/regular/random_3mb_644.bin DEST_DIR/links/hardlink_to_random_3mb_644.bin
• getfacl -p DEST_DIR/metadata/acl_text_1mb_644.txt
• getfattr -d DEST_DIR/metadata/xattr_text_1mb_644.txt

Destination Host Requirements

• If the destination host lacks acl or attr, ACL/xattr verification will be incomplete.
• If the destination filesystem does not support ACLs or xattrs, those attributes may not survive transfer even when the copy method is correct.
• The generator now logs and continues when ACL/xattr assignment is unsupported on the target filesystem instead of exiting.