# Working in this repository

## Finishing a change

Do not stop at a pushed branch. A merge into `main` ships in the next daily
release (03:00 UTC), so merge only complete, working changes.

1. Update the documentation for what changed, every time: the lead example and the tables in
   `README.md` and `toolpass-py/README.md` when the way a tool is written changes, the guide and
   reference pages under `docs/` that describe the changed behaviour, `docs/README.md` when a page is
   added, and `docs/development/testing.md` when a test directory is added. A page that shows the
   old way of doing something is a bug in the pull request, not a follow-up. Run
   `python3 test/docs/linkcheck.py` afterwards.
2. Run `/code-review main high` on the diff and fix every finding.
3. Run `/security-review` and fix every finding.
4. Run the local checks, after the review fixes, and get them clean
   (in `toolpass-py/`, with `pip install -e ".[crypto]" pytest pytest-timeout hypothesis ruff mypy types-PyYAML build`):
   - `ruff format --check src tests examples`, `ruff check src tests examples`,
     `mypy --strict src/toolpass`, `python -m pytest -q`
   - when an integration or `tests/harness` changed: fetch the API descriptions with
     `test/specs/fetch.sh /tmp/specs`, then `TOOLPASS_SPECS_DIR=/tmp/specs python -m pytest -q tests/integrations tests/harness_tests tests/contract`
   - when a framework adapter (`src/toolpass/<framework>.py`) changed: install its extra
     (`pip install -e ".[<extra>]"`) and run `python -m pytest tests/frameworks/test_<framework>.py`
   - when the vault integration changed: `TOOLPASS_REAL=1 python -m pytest tests/real` (needs docker)
   - when packaging (`pyproject.toml`) changed: build the wheel (`python -m build -o /tmp/dist .`),
     install it into a fresh venv, then run `tests` with that venv's Python from outside the repository
   - when `toolpass-ts` changed: `cd toolpass-ts && npm ci && npm test`, and run the `examples/agent-ts`
     tests, which exercise it
   - when `examples/agent-ts` changed: `cd examples/agent-ts && npm ci && npm test`
   - when any Markdown changed: `python3 test/docs/linkcheck.py`
   - when `deploy/helm` changed: `helm lint deploy/helm/toolpass --strict --set apiKey.value=x`
   - when the `Dockerfile` changed: `docker build .` and the smoke test in the `docker` CI job
5. Open a pull request using `.github/pull_request_template.md`. Mention the
   issue it closes when there is one.
6. Wait for CI on the pull request to pass, then squash-merge with the PR
   title and `(#N)` suffix, as the history on `main` does. If CI is red, fix
   and push; never merge over a failure, and never skip or disable a test to
   get green. A failure in code the change does not touch (a vendor spec, Prism or
   the argocd CLI failing to download, for example) may be re-run once; if it
   fails again, say so and stop.

The maintainer asked for this flow. Ask first only for changes that are
destructive or clearly outside what was requested.