docs: harden agent git safety guidance

.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

AGENTS.md

@@ -1,5 +1,37 @@
 # Agent Instructions
 
+## P0 Git Safety Rule
+
+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 <anything>:main`, `git push origin <anything>: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 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.
+
+### 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.
+- The push updates exactly one remote ref: `refs/heads/features/<current-pr-branch>`. 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-ref integration.
+
+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.
 
 ## Repository Overview
@@ -169,18 +201,24 @@ 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. 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` (standard push only)
-- `git merge` (merge commits to integrate branches — the only permitted way to sync with `dev` or resolve conflicts)
-- `git checkout`, `git switch`, `git branch` (branch creation and switching)
+- `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 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` (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)
 
 **Prohibited operations:**
 
+- 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)
@@ -196,7 +234,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