AGENTS.md@packages/environment git:20261017.cfce63fA

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

# @shadowclone/environment

Holds what agents receive: the environment record, skill publication, native instruction sections, hooks, install, and undo.

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

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

- Package name: `@shadowclone/environment`
- Workspace dependencies: `@shadowclone/agents`, `@shadowclone/changes`, `@shadowclone/core`, `@shadowclone/profile`, `@shadowclone/redact`, `@shadowclone/sessions`, `@shadowclone/skills`
- External dependencies: `zod`
- Export subpaths: `.`, `./testing`, `./browser`

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

## Owns

- `src/environment/`: the store (`readEnvironment`, `writeEnvironment`), `publishEnvironmentRevision`, `undoRevision`, `syncLearningEnvironment`, and `environmentStatus`.
- `src/environment/builds/` and `harness/`: build definitions, routing text, and the harness manifest.
- `src/integrations/`: native sections, hooks, `installIntegration`, `uninstallIntegration`, `compileContext`, and `isContextBlocked`.
- `src/integrations/installation/`: the install record and artifact ownership checks.
- `src/environment/learningNotice.ts`, `repositoryQuestion.ts`, and `reviewPrompt.ts`: the one-time triage notice, the repository destination question, and the prompt to review waiting proposals in session-start context.
- `src/integrations/contextSkill.ts`: the `shadowclone-context` skill that each agent receives, including the steps to review proposals with the user.

## Rules

- Every write goes through `publishEnvironmentRevision`. A path outside the authorized destinations is an error.
- `undoRevision` takes the write lock. It refuses an unauthorized root and a revision that conflicts with later edits.
- Native routing text is at most 4096 bytes. A longer text is an error, and the old section stays.
- shadowclone rewrites only the text between the `<shadowclone-guidance>` markers. Malformed markers are an error.
- A preserved integration file throws `PreservedFileError` with its path and reason. Only `replaceEdited` from `shadowclone sync --replace-edited` replaces the shadowclone content in it. A build plan that meets one stops with an error that names the file, the reason, and that command.
- shadowclone replaces an installed file only when its fingerprint matches the install record. A manual edit stays.
- Session start sets only `deliveredAt` on the current integration record. It never saves the copy that it read earlier.
- Hook entries match by value. The key order in a hook file does not matter.
- `materializeSkillDelivery` keeps one copy of each skill name. A repository copy wins over a personal copy, and a missing published copy falls back to a copy that exists.
- Initialization copies the original skills and native instructions to `environment-baselines/` before it publishes.
- The skills environment is the only store for learned rules. Without `environment.json`, learning and `remember` stop and say to run `shadowclone init`, and context delivery is empty.
- `syncLearningEnvironment` removes a registered repository whose folder no longer exists, with the skills and instructions published inside it, and reports each folder.
- Native publication, session-start context, and skill delivery render routing through `withoutMissingBuildSkills`. Routing leaves out a build skill with no copy left. Sync reports it when its build selects it, and keeps its records.
- Skill publication and sync release a skill record when every rule behind it is retired, also outside the destinations. They drop the record and delete an unchanged copy that shadowclone made. They never write `original` back, because a file that matches the record can hold edits that sync copied into it.
- A repository with `privateSkillsDirectory` publishes skills only under `~/.shadowclone/builds/`. Its routing names each skill by its file path, and no repository file changes.

## Tests

Run `bun test` in this folder, or `bun test packages/environment` from the root. The `./testing` export gives `environmentFixture`, `writeActiveEnvironment`, `learningRecord`, and `skillFixture`. Several tests run `git` on temporary repositories.

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