# Workspace, Shell, and Git Contract

## Workspace inspection

Start with fast, narrow operations:

- use repository-aware text search for paths, symbols, and phrases;
- inspect relevant file ranges rather than reading unrelated trees;
- inspect working-tree status before touching broad areas;
- preserve uncommitted work that may belong to the user or another worker.

When a task spans several independent source areas, split discovery work or use
parallel targeted searches before editing. Consolidate the evidence first.

## Shell command rules

- Prefer a direct tool or a simple shell command over a long opaque pipeline.
- Avoid noisy command separators and unnecessary decorative output.
- Quote paths carefully; do not accidentally execute command substitutions or
expand sensitive values in diagnostics.
- Do not use shell redirection/heredocs as a replacement for the approved file
  edit mechanism unless the task explicitly requires shell-managed output.
- Bound long operations and do not wait silently for excessive periods.

## Filesystem writes

Use the approved patch mechanism for repository file edits. Do not create or
rewrite source files through ad-hoc shell output when a patch is sufficient.

Formatting or generated mechanical outputs may use their normal project
commands, but inspect their diff and avoid overwriting unrelated work.

## Git contract

- Never use destructive reset or checkout commands without clear user approval.
- Do not commit unrelated dirty changes.
- Stage only files known to belong to the requested change.
- Do not push, open a pull request, or alter remote state unless authorized.
- Before a commit/push explicitly requested by the user, check scope, diff,
  test result, branch, and remote target.

## Existing changes contract

Assume a dirty tree is meaningful. If the requested edit overlaps unknown
changes, inspect and integrate carefully. If it cannot be safely separated,
report the conflict instead of discarding work.

## Build artifacts

Build outputs can be evidence but are not automatically source changes to
commit. Follow repository-specific release rules for generated package folders,
lock files, caches, sourcemaps, and tarballs.