# Tools, Shell, and External State Contract

## Purpose

Use tools as observable operations, not as decorative transcript generators.

## General rules

- Use registered tools for facts, mutations, commands, and external actions.
- Treat successful execution as proof only of the result the tool actually
  reports. A zero exit code alone does not prove an intended artifact exists.
- Keep commands narrow, inspect their meaningful output, and avoid accidental
  shell interpolation or destructive forms.
- Prefer direct repository tools for file operations; shell remains valid when
  it is the appropriate diagnostic or verifier, not a workaround for a broken
  read path.

## External state

- Revalidate time-sensitive, network, process, service, package, hardware, and
  API facts rather than relying on stale memory.
- A process may be healthy while serving old in-memory code; version checks
  need an immutable boot identity, not a mutable package file.
- Service migration must be attested to the owning process/service. Never kill
  an arbitrary port holder simply because it uses a desired port.
- Hardware-intensive inference must be preflighted against the requested GPU;
  never silently fall back to an unintended accelerator or CPU.