pastoralist ยท diff
git:20260713.b22b99e to git:20260810.f1f50a2
32 added, 0 removed. Audit A to A.
---
name: pastoralist
description: >
Use when setting up, running, or maintaining Pastoralist override tracking,
security checks, install hooks, GitHub Actions, or dependency override docs.
---
# Pastoralist
Start with `npx pastoralist onboard` when setting up a repo.
Use `npx pastoralist doctor` for read-only project health.
Run `npx -p pastoralist pastoralist-setup-local-dev --dry-run` before setup writes.
Use `npx pastoralist init` to create config.
Config can live under `package.json#pastoralist` or as top-level settings in `.pastoralistrc`, `.pastoralistrc.json`, `pastoralist.json`, or `pastoralist.config.*`.
Use `npx pastoralist` to update the override appendix.
Use `npx pastoralist --setup-hook` to keep the appendix current after installs.
Use `npx pastoralist --checkSecurity` for advisory checks.
Use `npx pastoralist --remove-unused` only after reviewing dry-run output.
+ ## User-Owned Best-Case Overrides
+
+ When best-case selection conflicts with an override the user controls, show the
+ active version and the appendix ledger `addedDate`, then ask whether the package
+ should be user-owned. Do not infer ownership from the date. Persist approved
+ package names in `pastoralist.bestCase.userOwnedOverrides`; the active override
+ supplies the required version.
+
+ ```json
+ {
+ "overrides": {
+ "alpha": "2.5.0"
+ },
+ "pastoralist": {
+ "bestCase": {
+ "enabled": true,
+ "userOwnedOverrides": ["alpha"]
+ },
+ "appendix": {
+ "alpha@2.5.0": {
+ "ledger": {
+ "addedDate": "2026-08-09T00:00:00.000Z"
+ }
+ }
+ }
+ }
+ }
+ ```
+
+ User-owned versions win. Re-run the security check so the complete portfolio is
+ evaluated with those versions as hard constraints.
+
## Agent Setup
Prefer the packaged setup script for agent config and skills:
```bash
npx -p pastoralist pastoralist-setup-local-dev --agent codex --skills all --hooks git,postinstall
```
If only the skill is needed:
```bash
npx pastoralist --init agent-skill
```
## Agent Loop
1. Run `npx pastoralist doctor`.
2. Run `npx -p pastoralist pastoralist-setup-local-dev --dry-run`.
3. Apply the smallest needed setup command.
4. Run `npx pastoralist --dry-run`.
5. Report changed files and remaining manual steps.
For CI, add `yowainwright/pastoralist@v1` to a pull request workflow.
Keep secrets in environment variables, not config files.