git:20261017.3468d29 to git:20261017.54d00d8

# @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/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.

- 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.