AGENTS.md@packages/learning git:20261011.f886e12A

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

# @shadowclone/learning

Turns evidence from consented sessions into guidance. It distills, reconciles, and queues rules for review. It also runs the background worker and `remember`.

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

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

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

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

## Owns

- `src/distill/`: evidence selection (`authorizedLearningEvents`, `materializeEvidence`), reconciliation, consolidation, and checkpoints.
- `src/learning/`: `runLearningService`, `runAutomaticLearning`, `scheduleLearning`, the pending queue, receipts, and probes.
- `src/learning/skillMaintenance/`: skill proposals and conflict review (`maintainSkills`).
- `src/preferences/`: `rememberPreference`. `src/importRules/`: repository guidance import.

## Rules

- Only user prompts, plan decisions, question answers, permission denials, and interruptions with a text reference are evidence.
- Each reference passes `authorizeRef` for the current consent and `resolveRedacted` before the model sees it.
- All model calls for one learning run share one `createLearningExecution`. Do not start a second budget.
- Consolidation groups rules by `scope`, `originDirectory`, and `repositoryName`. Merge evidence only within that complete scope.
- A learned rule that reads like an instruction to the agent stays pending with its reasons (`heldLearningReason`).
- The background worker takes the `learning-worker.db` lock. It exits as `busy` when another worker runs.
- Background learning needs `distillation.deep`, `distillation.automatic`, and a managed policy that allows it.

## Tests

Run `bun test` in this folder, or `bun test packages/learning` from the root. The `./testing` export gives `conflictFixture` and `preferenceEditFixture`. The tests use mock runners, so they make no model call.

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