Agent Operating Protocol

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

Evidence hierarchy

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

Every agent must perform the following steps at the beginning of a new session:

Read docs/WORKING_STATE.md and docs/DECISIONS.md.
Run the approved read-only workspace status command: bash scripts/workspace-status.sh.
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.
Wait for explicit approval from the operator before taking any action that modifies files or infrastructure.

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

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

Upon completing a task, every agent must:

State the exact files that were created or changed.
State the exact tests that were run and their results.
State what was not changed to provide clarity on the scope of the work.
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.
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.

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.