Why Gator checks a commit

• The charters must stay true. A charter is the map of the code that the next agent reads first. When code changes, the charter that describes it must change in the same commit. Otherwise the map goes wrong without anyone noticing.
• Some patterns need your attention. A possible secret, a dangerous SQL statement, or a sensitive file can be correct or a mistake. The agent should not decide that alone. You decide.

Three outcomes

Charter problems stop the commit. Dangerous patterns call for your attention.

• Fix required. The commit draft is invalid, for example a misspelled change type. The commit stops, and nothing can approve it away. The agent fixes the problem and commits again.
• Pause. The change contains a dangerous pattern, such as a possible secret or a SQL statement that deletes a whole table. The commit pauses with PAUSE. Architect attention required, and the agent brings the finding to you. The pause clears when your decision is recorded in the commit draft. A warning is not an approval and has no approval command.
• External approval. Code changed, but its charter did not. The commit stops. Usually the agent updates the charter and commits again. Sometimes no charter edit is warranted: the check misfired, or the change is too small to describe. Then only you can let it through, by approving that exact staged change in the Dashboard's Commits view, where a blocked commit shows an alert, or with gator hook approve in a terminal. An organization can also require this for dangerous patterns, for example in an Enterprise repository. If anything in the change moves, the approval stops working.

When a commit pauses

1. The agent shows you the findings. It lists every current finding in one question, with the rule, the file and line, and what the pattern means in this change. It ends with: "Reply Acknowledged to keep all of them, or name the findings to fix or remove."
2. You decide. Fix them, remove them, or keep them. A reply of "Acknowledged" applies only to the findings in that question.
3. A decision to keep them is recorded. The agent runs gator hook override acknowledge --all-current, or you choose Acknowledged in the Dashboard's Commits view. Either way, Gator writes the decision for every listed finding into the commit draft and names you as the Architect. You do not type keys or bullets. Gator refuses, and writes nothing, if the findings changed. The agent never records a decision on its own.

The best time is before the pattern is written. A good agent tells you when it is about to write or run something dangerous. Then your decision is in the commit draft before the first attempt, and the commit does not pause.

An agent can choose not to ask. It can only go ahead by recording a skip. The commit then carries Gator-Dangerous-Patterns-Unacknowledged, and the Commits view shows ! Unacknowledged, so the choice is always visible.

What lands in Git

• The commit message. A short, readable summary of the change, and the ordinary Gator trailers: the change type, the significance, and the agent and Architect.
• Your acknowledgement, when you keep a warning. The message keeps an Architect acknowledgement section with your decision. The trailers Gator-Dangerous-Patterns and Gator-Dangerous-Pattern-Acknowledged-By name the findings and you. They never contain the flagged text.
• An override record, only for an external approval. The Gator-Override-* trailers name who approved, the block, the reason and the rules. An approved charter finding also shows as Gator-Charter-Changed: override-skip. An acknowledgement never produces them.

In the Dashboard's Commits view, an acknowledgement shows as ✓ Acknowledged and an override as ⚑ Override.

What Gator does not do

Gator helps you notice and decide. It does not replace your security tools.

• It is not a secret scanner or a static analyzer. Its pattern list is short on purpose. Dedicated security and quality tools stay responsible for their own analysis and fixes.
• It does not fix findings. It makes them visible in the session, so that you and the agent can discuss them while the change is fresh.
• The pause is a prompt, not a lock. It stops the commit so that the agent asks you, and it records every skip. It cannot force an agent to ask, so it does not enforce your approval.