From bf170db73e0e4ac6a7431d0602b6ce95a29dd714 Mon Sep 17 00:00:00 2001 From: msbrett Date: Wed, 3 Jun 2026 07:48:59 -0700 Subject: [PATCH 1/3] docs: harden agent git safety guidance --- .gitignore | 28 ++++++++++++++++++++++++++-- AGENTS.md | 25 ++++++++++++++++++++++--- 2 files changed, 48 insertions(+), 5 deletions(-) diff --git a/.gitignore b/.gitignore index 198952770..282578f5f 100644 --- a/.gitignore +++ b/.gitignore @@ -374,6 +374,7 @@ env/ # AI .claude/settings.local.json .claude/scheduled_tasks.lock +.mcp.json # Internal planning docs /TODO.md @@ -384,6 +385,29 @@ env/ # Auto-generated build artifacts src/templates/finops-hub-copilot-studio/knowledge/query-catalog.md .gate/ -todo/ -done/ + +# Gate pipeline files (runtime, not source) +/todo/ +/done/ + +# Ralph autonomous iteration loop +/ralph.sh +/ralph-meta.sh +/ralph/ + +# SRE agent training deck — local working artifacts +src/templates/sre-agent/training/release-deck/renders/ +src/templates/sre-agent/training/release-deck/__pycache__/ +src/templates/sre-agent/training/release-deck/~$*.pptx +src/templates/sre-agent/training/release-deck/finops-toolkit-sre-agent-release-training copy.pptx +src/templates/sre-agent/training/release-deck/finops-toolkit-sre-agent-release-training.pdf +src/templates/sre-agent/training/release-deck/qa4-*.jpg +src/templates/sre-agent/training/release-deck/charts/svg/*.rasterized.png +src/templates/sre-agent/training/release-deck/assets/*.rasterized.png + +# Working PNGs from playwright/CDP captures at repo root +.playwright-mcp/ +cdp-fullpage*.png +cdp-shot*.png +src/templates/sre-agent/training/release-deck/finops-toolkit-sre-agent-release-training.rebuild-*.pptx release/scloud-occurrence-report.md diff --git a/AGENTS.md b/AGENTS.md index 4edd2dc7c..e8d1e064b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,19 @@ # Agent Instructions +## P0 Git Safety Rule + +AI agents must never directly mutate `main` or `dev` in this repository or in any submodule. This includes direct commits, pushes, merges, reverts, cherry-picks, resets, branch updates, or any refspec that targets `main` or `dev`. + +AI agents must never run `git push origin HEAD:main`, `git push origin HEAD:dev`, `git push origin :main`, `git push origin :dev`, or equivalent commands against any remote. + +AI agents must never use privileged credentials, maintainer permissions, administrator permissions, branch-protection bypass permissions, ruleset bypass permissions, or GitHub's "bypass rule violations" path to update a protected branch. + +If GitHub reports that a push would "bypass rule violations" or that "changes must be made through a pull request", the agent must stop immediately and report a P0 policy violation. Do not continue with the push, and do not attempt a workaround. + +The only allowed path for changes intended for `main` or `dev` is: create or update a feature branch, push only that feature branch after explicit approval, and open a pull request. Humans and required repository automation own protected-branch integration. + +Reverting, remediating, or "cleaning up" an unauthorized protected-branch change is also a protected-branch mutation. AI agents must not do it without explicit user approval for the exact branch, commit, and command. + This file provides guidance to AI Agents when working with code in this repository. ## Repository Overview @@ -169,10 +183,12 @@ The PowerShell-based build system: This repository supports production infrastructure managing significant revenue. All git operations must be non-destructive and preserve full commit history. +The P0 Git Safety Rule at the top of this file is authoritative and overrides every permitted operation listed below. + **Permitted operations:** -- `git add`, `git commit`, `git push` (standard push only) -- `git merge` (merge commits to integrate branches — the only permitted way to sync with `dev` or resolve conflicts) +- `git add`, `git commit`, `git push` on non-protected feature branches only (standard push only, after explicit approval) +- `git merge` into non-protected feature branches only (merge commits to integrate from `dev` — the only permitted way to sync with `dev` or resolve conflicts, after explicit approval) - `git checkout`, `git switch`, `git branch` (branch creation and switching) - `git worktree add`, `git worktree remove`, `git worktree prune` (worktree lifecycle) - `git fetch`, `git pull` (with merge, not rebase) @@ -181,6 +197,9 @@ This repository supports production infrastructure managing significant revenue. **Prohibited operations:** +- Any direct mutation of `main` or `dev`, including direct pushes, commits, merges, reverts, or branch ref updates. +- Any use of protected branch, ruleset, or administrator bypass capabilities to update `main` or `dev`. +- Any attempt to land changes on `main` or `dev` without a pull request. - `git rebase` — rewrites commit history. Never permitted on shared branches. Not permitted as a conflict resolution strategy. - `git push --force` / `git push --force-with-lease` — destructive remote update. Never permitted. - `git reset --hard` to a state behind the remote (discarding pushed commits) @@ -196,7 +215,7 @@ This repository supports production infrastructure managing significant revenue. - **`src/scripts/Update-Version.ps1`** — This script has multiple independent version-update blocks (PowerShell, Bicep, plugin.json, survey IDs, etc.). When both sides add new blocks, keep both — they operate on different file sets and do not conflict logically. - **`docs-mslearn/toolkit/changelog.md`** — Both sides may add entries under the same version heading. Keep entries from both sides in logical order (plugin entries, then component entries). -**AI agents must ask for explicit approval** before executing any git write operation (`commit`, `push`, `merge`). Read-only git commands (`status`, `log`, `diff`, `branch --list`, `worktree list`) do not require approval. +**AI agents must ask for explicit approval** before executing any git write operation (`commit`, `push`, `merge`, `revert`, `cherry-pick`, branch deletion, tag creation, or worktree state mutation). Read-only git commands (`status`, `log`, `diff`, `show`, `branch --list`, `worktree list`, `ls-remote`, `fetch`) do not require approval. Approval to perform a task, deploy, unblock a test, or fix an incident is not approval to write to git; approval must name the git action. ### File Organization From 135946e8232a572df9e0f08ee9b48bf6b64d2b3e Mon Sep 17 00:00:00 2001 From: msbrett Date: Wed, 3 Jun 2026 09:40:58 -0700 Subject: [PATCH 2/3] docs: document PR branch rule false positive --- AGENTS.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e8d1e064b..f0b678bff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,7 +8,19 @@ AI agents must never run `git push origin HEAD:main`, `git push origin HEAD:dev` AI agents must never use privileged credentials, maintainer permissions, administrator permissions, branch-protection bypass permissions, ruleset bypass permissions, or GitHub's "bypass rule violations" path to update a protected branch. -If GitHub reports that a push would "bypass rule violations" or that "changes must be made through a pull request", the agent must stop immediately and report a P0 policy violation. Do not continue with the push, and do not attempt a workaround. +If GitHub reports that a push would "bypass rule violations" or that "changes must be made through a pull request", the agent must stop immediately and report a P0 policy violation unless the known PR branch rule false positive below applies. Do not attempt a workaround. + +### Known PR branch rule false positive + +This repository currently has misconfigured branch rules that can report "Bypassed rule violations" and "Changes must be made through a pull request" during a standard push to an existing PR feature branch. Treat that warning as a false positive only when all of these conditions are verified: + +- The target ref is the current PR branch under `refs/heads/features/`. +- The branch has an open pull request targeting `dev`. +- The command is a standard non-force push to that same feature branch. +- No refspec targets `main`, `dev`, or any other protected branch. +- No privileged credentials, administrator bypass, branch-protection bypass, or ruleset-bypass path is being used. + +If any condition is not verified, stop immediately and report a P0 policy violation. The only allowed path for changes intended for `main` or `dev` is: create or update a feature branch, push only that feature branch after explicit approval, and open a pull request. Humans and required repository automation own protected-branch integration. @@ -189,9 +201,9 @@ The P0 Git Safety Rule at the top of this file is authoritative and overrides ev - `git add`, `git commit`, `git push` on non-protected feature branches only (standard push only, after explicit approval) - `git merge` into non-protected feature branches only (merge commits to integrate from `dev` — the only permitted way to sync with `dev` or resolve conflicts, after explicit approval) -- `git checkout`, `git switch`, `git branch` (branch creation and switching) +- `git checkout`, `git switch`, `git branch` (branch creation and switching; do not switch to `main` or `dev` for mutable agent work) - `git worktree add`, `git worktree remove`, `git worktree prune` (worktree lifecycle) -- `git fetch`, `git pull` (with merge, not rebase) +- `git fetch`, `git pull` on non-protected feature branches only (with merge, not rebase) - `git stash`, `git stash pop` (temporary local state management) - `git status`, `git log`, `git diff`, `git show` (read-only inspection) From df0d4b4ac2585cb40c14c12b6a5c4817e40cf756 Mon Sep 17 00:00:00 2001 From: msbrett Date: Thu, 4 Jun 2026 06:13:45 -0700 Subject: [PATCH 3/3] docs: tighten agent git safety policy per rubber-duck review - Generalize protected branches to protected refs (covers protected tags) - Prohibit --tags/--follow-tags/--all/--mirror and multi-ref push refspecs - Tighten PR-branch false-positive carve-out: single-ref push only, no cherry-picks from main, explicit refspec discipline - Remove approval-can-authorize-direct-mutation loophole in the revert/remediation clause; route to a human maintainer instead - Define 'mutable work' on main/dev as anything that touches worktree, index, commits, refs, generated files, or submodules - Add indirect protected-ref mutation clause covering workflows, CODEOWNERS, rulesets, release scripts, and credential handling - Add global approval-required preamble above the permitted list - Root-anchor .gitignore entries the comment claims are 'at repo root' Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .gitignore | 8 ++++---- AGENTS.md | 27 +++++++++++++++++---------- 2 files changed, 21 insertions(+), 14 deletions(-) diff --git a/.gitignore b/.gitignore index 282578f5f..415b8555b 100644 --- a/.gitignore +++ b/.gitignore @@ -374,7 +374,7 @@ env/ # AI .claude/settings.local.json .claude/scheduled_tasks.lock -.mcp.json +/.mcp.json # Internal planning docs /TODO.md @@ -406,8 +406,8 @@ src/templates/sre-agent/training/release-deck/charts/svg/*.rasterized.png src/templates/sre-agent/training/release-deck/assets/*.rasterized.png # Working PNGs from playwright/CDP captures at repo root -.playwright-mcp/ -cdp-fullpage*.png -cdp-shot*.png +/.playwright-mcp/ +/cdp-fullpage*.png +/cdp-shot*.png src/templates/sre-agent/training/release-deck/finops-toolkit-sre-agent-release-training.rebuild-*.pptx release/scloud-occurrence-report.md diff --git a/AGENTS.md b/AGENTS.md index f0b678bff..407afcfbd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,11 +2,11 @@ ## P0 Git Safety Rule -AI agents must never directly mutate `main` or `dev` in this repository or in any submodule. This includes direct commits, pushes, merges, reverts, cherry-picks, resets, branch updates, or any refspec that targets `main` or `dev`. +AI agents must never directly mutate `main`, `dev`, or any other protected ref in this repository or in any submodule. Protected refs include protected branches, protected tags, and any ref covered by a branch protection rule or ruleset. This includes direct commits, pushes, merges, reverts, cherry-picks, resets, branch updates, tag creation, tag deletion, tag force-updates, or any refspec that targets a protected ref. -AI agents must never run `git push origin HEAD:main`, `git push origin HEAD:dev`, `git push origin :main`, `git push origin :dev`, or equivalent commands against any remote. +AI agents must never run `git push origin HEAD:main`, `git push origin HEAD:dev`, `git push origin :main`, `git push origin :dev`, `git push --tags`, `git push --follow-tags`, `git push --all`, `git push --mirror`, or equivalent commands against any remote. -AI agents must never use privileged credentials, maintainer permissions, administrator permissions, branch-protection bypass permissions, ruleset bypass permissions, or GitHub's "bypass rule violations" path to update a protected branch. +AI agents must never use privileged credentials, maintainer permissions, administrator permissions, branch-protection bypass permissions, ruleset bypass permissions, or GitHub's "bypass rule violations" path to update a protected ref. If GitHub reports that a push would "bypass rule violations" or that "changes must be made through a pull request", the agent must stop immediately and report a P0 policy violation unless the known PR branch rule false positive below applies. Do not attempt a workaround. @@ -17,14 +17,20 @@ This repository currently has misconfigured branch rules that can report "Bypass - The target ref is the current PR branch under `refs/heads/features/`. - The branch has an open pull request targeting `dev`. - The command is a standard non-force push to that same feature branch. -- No refspec targets `main`, `dev`, or any other protected branch. +- The push updates exactly one remote ref: `refs/heads/features/`. The command must not include `--all`, `--mirror`, `--tags`, `--follow-tags`, delete refspecs, wildcard refspecs, or any additional refspec. +- No refspec targets `main`, `dev`, or any other protected ref. +- The commits being pushed originated on this feature branch or were authored via a normal merge from `dev`. Cherry-picks from `main` or any other protected ref are not permitted under this carve-out. - No privileged credentials, administrator bypass, branch-protection bypass, or ruleset-bypass path is being used. If any condition is not verified, stop immediately and report a P0 policy violation. -The only allowed path for changes intended for `main` or `dev` is: create or update a feature branch, push only that feature branch after explicit approval, and open a pull request. Humans and required repository automation own protected-branch integration. +The only allowed path for changes intended for `main` or `dev` is: create or update a feature branch, push only that feature branch after explicit approval, and open a pull request. Humans and required repository automation own protected-ref integration. -Reverting, remediating, or "cleaning up" an unauthorized protected-branch change is also a protected-branch mutation. AI agents must not do it without explicit user approval for the exact branch, commit, and command. +Reverting, remediating, or "cleaning up" an unauthorized protected-ref change is itself a protected-ref mutation. AI agents must not perform it directly, even with user approval. The agent must stop and ask a human maintainer to remediate via the repository's protected-branch process or an approved pull request. + +### Indirect protected-ref mutation + +AI agents must not create or modify repository automation, GitHub Actions workflows, workflow permissions, `CODEOWNERS`, branch or ruleset configuration, release scripts, deploy keys, or credential handling in ways that could enable automated writes to protected refs without explicit user approval that names those files and the intended protected-ref behavior. This applies to changes made on feature branches as well, because such changes take effect on protected refs after merge. This file provides guidance to AI Agents when working with code in this repository. @@ -195,13 +201,13 @@ The PowerShell-based build system: This repository supports production infrastructure managing significant revenue. All git operations must be non-destructive and preserve full commit history. -The P0 Git Safety Rule at the top of this file is authoritative and overrides every permitted operation listed below. +The P0 Git Safety Rule at the top of this file is authoritative and overrides every permitted operation listed below. Every permitted git write operation below still requires explicit approval that names the specific git action, per the approval rule at the end of this section. **Permitted operations:** - `git add`, `git commit`, `git push` on non-protected feature branches only (standard push only, after explicit approval) - `git merge` into non-protected feature branches only (merge commits to integrate from `dev` — the only permitted way to sync with `dev` or resolve conflicts, after explicit approval) -- `git checkout`, `git switch`, `git branch` (branch creation and switching; do not switch to `main` or `dev` for mutable agent work) +- `git checkout`, `git switch`, `git branch` (branch creation and switching; do not check out or switch to `main` or `dev` except for read-only inspection — while on `main` or `dev`, agents may run only read-only git commands and must not run commands that modify the worktree, index, commits, refs, generated files, or submodules) - `git worktree add`, `git worktree remove`, `git worktree prune` (worktree lifecycle) - `git fetch`, `git pull` on non-protected feature branches only (with merge, not rebase) - `git stash`, `git stash pop` (temporary local state management) @@ -209,9 +215,10 @@ The P0 Git Safety Rule at the top of this file is authoritative and overrides ev **Prohibited operations:** -- Any direct mutation of `main` or `dev`, including direct pushes, commits, merges, reverts, or branch ref updates. -- Any use of protected branch, ruleset, or administrator bypass capabilities to update `main` or `dev`. +- Any direct mutation of `main`, `dev`, or any other protected ref, including direct pushes, commits, merges, reverts, branch ref updates, tag creation, tag deletion, or tag force-updates. +- Any use of protected branch, ruleset, or administrator bypass capabilities to update a protected ref. - Any attempt to land changes on `main` or `dev` without a pull request. +- `git push --tags`, `git push --follow-tags`, `git push --all`, `git push --mirror`, multi-ref push commands, or any push refspec other than a single non-protected feature branch. - `git rebase` — rewrites commit history. Never permitted on shared branches. Not permitted as a conflict resolution strategy. - `git push --force` / `git push --force-with-lease` — destructive remote update. Never permitted. - `git reset --hard` to a state behind the remote (discarding pushed commits)