# Agent Operating Protocol

This document outlines the mandatory protocol for all agents operating within the OSVauco repository.

## Evidence hierarchy
1.  **Live platform/API state** is authoritative for runtime, IAM, build, deploy, traffic, and infrastructure state.
2.  **Remote Git branch and immutable commit SHA** are authoritative for versioned repository artifacts.
3.  **Local Git state** is authoritative for the current workstation checkout.
4.  **`WORKING_STATE.md` and `DECISIONS.md`** communicate intended work, known status, and rationale, but do not override live verification.
5.  **Chat, terminal scrollback, and agent memory** are non-authoritative context.

## Session startup protocol
Every agent must perform the following steps at the beginning of a new session:

1.  Read `docs/WORKING_STATE.md` and `docs/DECISIONS.md`.
2.  Run the approved read-only workspace status command: `bash scripts/workspace-status.sh`.
3.  State the current branch, local SHA, remote SHA, any dirty files, the current objective, verified facts, blockers, and propose one single next action based on this information.
4.  Wait for explicit approval from the operator before taking any action that modifies files or infrastructure.

## Change protocol
Every agent must adhere to the following protocol when making changes:

1.  Identify the smallest possible set of files affected by the proposed change.
2.  Present a concrete proposed diff or an exact, detailed plan of the changes to be made.
3.  After receiving approval, execute the change.
4.  Run focused, relevant tests to verify the change. Do not run unrelated tests.
5.  Report the exact test commands used and their pass/fail results.
6.  Commit changes in small, coherent, logical units.
7.  Push commits to the remote repository only after explicit approval or as part of a pre-approved workflow.
8.  Deploy changes only through the canonical, approved deployment flow and only after receiving explicit approval for the deployment itself.

## Completion protocol
Upon completing a task, every agent must:

1.  State the exact files that were created or changed.
2.  State the exact tests that were run and their results.
3.  State what was *not* changed to provide clarity on the scope of the work.
4.  Update `docs/WORKING_STATE.md` if the `Current objective`, `Current deployment state`, `Current blockers`, or `Next single action` have changed as a result of the work.
5.  Never claim infrastructure state (e.g., "deployed") without performing a live, read-only verification command and showing the result. An agent must distinguish committed, pushed, build-created, build-succeeded, revision-created, traffic-shifted, and live-verified states.

## Hard-stop protocol
An agent must stop all work and ask the operator for direction when any of the following conditions are met:

- Required configuration, source code, identity, or a target branch is unknown or ambiguous.
- A proposed command would create, modify, or deploy infrastructure unexpectedly.
- A test failure occurs that is unrelated to the approved task.
- A proposed change would expand permissions, firewall rules, or security scope.
- It is suspected that an existing system or component may already solve the problem at hand.
- The requested action conflicts with the current objective or rules listed in `docs/WORKING_STATE.md` or `docs/DECISIONS.md`.