AGENTS.md@packages git:20260915.b65685cA

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

# AGENTS.md — `packages/`

Applies to `packages/`. Inherits the root `AGENTS.md`. Scope-specific deltas only.

## Version bump rule

Non-cosmetic package changes update both `version.py` and `pyproject.toml`.
CLI-surface changes may require release; see
[`AGENTS.local.md`](AGENTS.local.md#release-coupling).

## Cross-package traps

- Text reads and writes must pass `encoding="utf-8"`.
- Use list-form subprocess calls only: never `shell=True` or shell out to
  `grep`, `sed`, or `make` from portable package code.
- Tests isolating a user root must set `AGENTBUNDLE_USER_ROOT` with `HOME`:
  Windows `expanduser()` ignores monkeypatched environment variables.
- Do not hardcode `/tmp` or read `os.environ["HOME"]` directly in portable tests.
- Wrap `os.symlink()` in `try/except OSError` and skip when symlinks are unavailable.
- Use `tmp_path`, not `tempfile.mkdtemp()`; autouse fixtures use
  `tmp_path_factory.mktemp()`.
- Patch environments with the `monkeypatch` fixture.
- Projection-layout, orphan-scanner, and adapter-resolution tests parametrize over
  every shipped adapter from `agentbundle/_data/adapter.toml`; document exceptions.
- Use `build_pipeline`, not `build`, for build-pipeline tests: pytest skips any
  directory named `build` by default.

## Test conventions

| Assertion owner | Test home |
| --- | --- |
| Engine distribution | `packages/agentbundle/tests/{unit,integration,build_pipeline}/` |
| Catalogue rule | `tests/conformance/` |
| Catalogue roster | `tests/roster/` |
| Pack behavior | `packs/<pack>/tests/` |
| Repository tool | beside its `tools/` script |

This table is enforced, not stylistic. `packages/agentbundle/tests/` ships inside
the sdist and is re-run against an extracted workspace holding only the package —
no `contracts/`, `packs/`, `docs/`, or `catalogue.toml`. A test placed here that
reads a repository path passes locally and fails the sdist artifact gate. Keep the
package behaviour here against fixtures and move the repository-level half to
`tests/roster/`; [`tests/AGENTS.md`](../tests/AGENTS.md) owns what that obliges.

## Deeper pointers

Package release process lives in
[`docs/guides/explanation/release-coupling.md`](../docs/guides/explanation/release-coupling.md).