# How a study is kept from pushing

A study is a run that answers a question instead of changing code: it reads, runs the app, asks through Needs you and
ends with a proposal ([Studies](https://andon-docs.pages.dev/guide/studies.md)). It must never push a branch or open a pull request, whichever agent
runs it. Keep every layer below when you change the launch path. The code is `apps/agent/src/study.ts`, and its header
says the same in short.

## Three layers

1. **The run contract** (`apps/agent/src/run-contract.ts`, the `study` contract) has no push lines, and says the run
   never pushes or opens a pull request. It sits above any repository instruction to push.
2. **Claude Code's deny rules.** `STUDY_DENIED_TOOLS` go into the run's `settings.json` under `permissions.deny`:
   `git push` and `gh pr create`, `merge`, `ready`, `edit`, `close`, `comment` and `review`. Deny rules win over any
   allow rule and any permission mode.
3. **Git itself, for every executor.** `studyGitEnv` sets `GIT_CONFIG_COUNT` and `GIT_CONFIG_KEY_n` /
   `GIT_CONFIG_VALUE_n` in the session's environment so every push URL is rewritten to `/andon-study-runs-never-push/`,
   a path that isn't a repository. So `git push` fails with a message that says why, and `gh pr create` fails the
   same way because it pushes first. Fetching and reading still work. The rewrite is:
   - `url./andon-study-runs-never-push/.pushInsteadOf` with an empty value, which covers every URL;
   - the same key once for each remote URL the workspace has at launch (read with `STUDY_REMOTE_URL_ARGS`), so a
     person's own longer `pushInsteadOf` for that URL doesn't win;
   - an exact `insteadOf` for each `pushurl`, because git doesn't apply `pushInsteadOf` to a `pushurl`.

The third layer has one gap. A push to a URL that is no remote's, typed in the session, follows a person's own
`pushInsteadOf` when one covers it (git takes the longest match, and the first of equal ones). There, only the contract
and Claude's deny rules stop it.

## Andon's own pushes skip a study too

The agent pushes on a run's behalf in three places: the safety net, merging without GitHub and memory proposals. Each
acts only on a run that delivers, and for a study `noDelivery()` (`run-contract.ts`) answers `study`. A study is never a PR group, either: not a
group of one when it starts, and not a group's recipe. A person's own **Push branch** or **Move to machine** on the
card still pushes: that is their decision, not the run's.

## The mock folder

A study may build a working mock to show in its proposal, but never in the repository. At launch,
`prepareStudyMock` makes the card's folder, `<scratchRoot>/andon-study-mocks/<card id>` (`studyMockPath`), and refuses
it if it overlaps the worktree, sits inside any git repository, or is outside the machine's `workspaceRoots`. The study
then runs without a mock, and the agent's log says why.

The session gets the folder as an extra directory (Claude and Codex `--add-dir`, Gemini `--include-directories`), in
`$ANDON_STUDY_MOCK`, and in a short brief (`studyMockBrief`): write the mock only there, and show it in the proposal
page or as a second page published with `publish_output` from that folder. It is the only place outside the workspace a
run may publish from. The folder belongs to the card, so a follow-up turn keeps building the same mock. When the card
reaches Done, the agent moves the folder to the Trash. Nothing from the mock is in the worktree, so there is nothing of
it to commit or push.

## Tests

`apps/agent/src/study.test.ts` covers the environment and the mock folder's checks; `apps/agent/test/study.int.test.ts`
runs a study end to end against a real git remote and the fake `gh`, and checks that nothing reached either.
