AGENTS.md@packages/changes git:20261009.95ca1efA

Immutable. This exact content never changes and is served at /api/v1/blob/1be6b374d1a82881.

# @shadowclone/changes

Writes local files as revisions that people can inspect and undo. Skills, profile, environment, and harness writes use it.

<!-- package-facts:start -->

(generated by `bun run guides`; do not edit by hand)

- Package name: `@shadowclone/changes`
- Workspace dependencies: `@shadowclone/core`, `@shadowclone/sessions`
- External dependencies: `zod`
- Export subpaths: `.`

<!-- package-facts:end -->

## Owns

- `src/apply.ts`: `commitLocalChanges`, `revisionTarget`, and the apply and reverse logic.
- `src/store.ts`: revision records in `history/`, with `listRevisions` and `readRevision`.
- `src/index.ts`: `showRevision`, which returns the redacted revision text.
- `src/types.ts`: `LocalRevision` and `FileUpdate`.

## Rules

- A revision records the text of each file before and after the change.
- `commitLocalChanges` saves the revision as `prepared` before it writes any file. It saves `applied` after the last write.
- If a file changed after the caller read it, the commit fails and keeps every file.
- If a write fails, the package restores the files that it already wrote.
- A target outside the revision root is an error. A revision has at most 256 files and no duplicate destination.
- The history files use owner-only permissions.

## Tests

Run `bun test` in this folder, or `bun test packages/changes` from the root. The tests use temporary folders and need no other tool.

Update this file in the same commit when you change the package purpose, public exports, dependencies, or a rule above.